Python math.trunc(): Truncating Decimals Towards Zero

Syntax & Parameters 🔝

The math.trunc() function is part of Python's standard math module:

import math

integer_val = math.trunc(x)

Basic Usage & Rounding Towards Zero 🔝

Observe how math.trunc() strips fractional values without performing upward or downward rounding:

import math

# Positive floats: simply strips decimals
print("trunc(3.14): ", math.trunc(3.14))   # Output: 3
print("trunc(3.99): ", math.trunc(3.99))   # Output: 3 (not rounded to 4)

# Negative floats: rounds upward towards zero
print("trunc(-3.14):", math.trunc(-3.14))  # Output: -3
print("trunc(-3.99):", math.trunc(-3.99))  # Output: -3 (not rounded to -4)

# Pure integers and zeros
print("trunc(42):   ", math.trunc(42))     # Output: 42
print("trunc(0.0):  ", math.trunc(0.0))    # Output: 0
print("trunc(-0.0): ", math.trunc(-0.0))   # Output: 0

Output:

trunc(3.14):  3
trunc(3.99):  3
trunc(-3.14): -3
trunc(-3.99): -3
trunc(42):    42
trunc(0.0):   0
trunc(-0.0):  0

The __trunc__() Dunder Protocol for Custom Classes 🔝

In Python's object-oriented architecture, math.trunc(obj) calls obj.__trunc__(). Any user-defined class can implement this magic method to define custom integer conversion:

import math

class FinancialAmount:
    def __init__(self, dollars, cents):
        self.total = dollars + cents / 100.0
        
    def __trunc__(self):
        """Defines custom truncation for math.trunc()"""
        return math.trunc(self.total)

wallet = FinancialAmount(149, 85)  # $149.85
print("Truncated wallet:", math.trunc(wallet))  # Output: 149
print("Built-in int():   ", int(wallet))         # Output: 149 (falls back to __trunc__)

Output:

Truncated wallet: 149
Built-in int():    149

math.trunc() vs. int() vs. math.floor() vs. math.ceil() 🔝

Understanding the precise behavioral distinctions between Python's integer extraction tools is essential, especially when dealing with negative values:

Key Difference: math.trunc() vs. int()

While int(3.7) and math.trunc(3.7) produce identical numerical output on floats, their design intent differs:

• int() is a general-purpose type constructor that parses string representations (int("123")).
• math.trunc() is an explicit mathematical operation that strictly demands a number or object implementing __trunc__(). Calling math.trunc("123") raises a TypeError.

Handling Infinities, NaNs, and Exceptions 🔝

Because infinity and Not-a-Number have no valid integer representation, math.trunc() raises specific exceptions when passed IEEE 754 non-finite floats:

import math

# 1. Truncating infinity raises OverflowError
try:
    math.trunc(float('inf'))
except OverflowError as err:
    print("OverflowError on inf:", err)

# 2. Truncating NaN raises ValueError
try:
    math.trunc(float('nan'))
except ValueError as err:
    print("ValueError on nan:   ", err)

# 3. Truncating non-numeric string raises TypeError
try:
    math.trunc("42.5")
except TypeError as err:
    print("TypeError on string: ", err)

Output:

OverflowError on inf: cannot convert float infinity to integer
ValueError on nan:    cannot convert float NaN to integer
TypeError on string:  type str doesn't define __trunc__ method

Hands-on Exercise: Video SMPTE Timecode Converter with Assertions 🔝

In digital video editing and broadcasting, continuous media playback elapsed time in seconds (e.g. 3665.48 seconds) must be converted into standard SMPTE Timecode: HH:MM:SS:FF (Hours, Minutes, Seconds, Frames).

Using math.trunc() ensures that fractional leftovers are systematically stripped into their respective discrete components without rounding errors altering frame counts:

import math

def seconds_to_smpte(total_seconds, fps=30):
    """
    Converts elapsed seconds into SMPTE timecode string: HH:MM:SS:FF.
    Uses math.trunc() to ensure clean, non-rounding component extraction.
    """
    if not isinstance(total_seconds, (int, float)) or total_seconds < 0:
        raise ValueError("Total seconds must be a non-negative number.")
    if not isinstance(fps, int) or fps <= 0:
        raise ValueError("Frames per second (fps) must be a positive integer.")
        
    # 1. Total integer seconds and fractional sub-second
    int_sec = math.trunc(total_seconds)
    sub_sec = total_seconds - int_sec
    
    # 2. Extract hours, minutes, and remaining seconds
    hours = math.trunc(int_sec / 3600)
    rem_sec = int_sec % 3600
    
    minutes = math.trunc(rem_sec / 60)
    seconds = rem_sec % 60
    
    # 3. Calculate discrete frames
    frames = math.trunc(sub_sec * fps)
    
    return f"{hours:02d}:{minutes:02d}:{seconds:02d}:{frames:02d}"

# Unit Assertions
assert seconds_to_smpte(0.0) == "00:00:00:00"
assert seconds_to_smpte(65.5, fps=30) == "00:01:05:15"      # 0.5s = 15 frames
assert seconds_to_smpte(3661.1, fps=30) == "01:01:01:03"    # 1 hr, 1 min, 1 sec, 3 frames
assert seconds_to_smpte(7200.0, fps=24) == "02:00:00:00"

# Error validation
try:
    seconds_to_smpte(-10.0)
    assert False, "Should raise ValueError"
except ValueError:
    pass

sample_playback = 5423.85  # ~1 hr, 30 min, 23 sec
print(f"Playback ({sample_playback}s at 30fps): {seconds_to_smpte(sample_playback, 30)}")
print("All SMPTE timecode assertions passed successfully!")

Practice in Google Colab & GitHub 🔝

Open in Google Colab View on GitHub

Run all math.trunc() examples interactively, test custom classes with the __trunc__() dunder protocol, inspect error exceptions, and execute SMPTE timecode conversions in Google Colab.

More Details & Related Guides 🔝

• Python Math Module Overview — Master arithmetic, trigonometry, and numeric constants in Python.
• math.floor() & math.ceil() Functions — Downward and upward integer rounding.
• math.modf() Function — Decompose floats into fractional and integer parts.
• math.round() Guide — Rounding numbers to nearest even integers and decimal places.
• Python int Data Type — Comprehensive guide to integers and conversions in Python.
• Python float Data Type — Complete guide to IEEE 754 floating-point mechanics.
• Python Classes & Dunder Methods — Creating custom classes with special magic methods.

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author   Watch on YouTube

Connect: