U24 Class

class U24(value: int)

A 24-bit unsigned integer type with range 0 to 16,777,215.

The U24 class is implemented in Rust and provides a frozen (immutable) Python wrapper for 24-bit unsigned integer operations. It supports all standard arithmetic, comparison, and bitwise operations with appropriate overflow checking.

Parameters:: value (int) – An integer in the range [0, 16,777,215]
Raises:: ValueError – If value is out of range for U24

Example:

from i24 import U24

x = U24(1000)
y = U24(500)
result = x + y
print(result.to_int())  # 1500

Class Attributes

U24.min_value: U24: The minimum value for U24: U24(0)

U24.max_value: U24: The maximum value for U24: U24(16777215)

Construction Methods

U24.__init__(value: int) → None

Create a new U24 from a Python int.

Parameters:: value – An integer in the range [0, 16,777,215]
Raises:: ValueError – If value is out of range

static U24.from_bytes(bytes: list[int], byteorder: Literal['little', 'big', 'native'] = 'native') → U24

Create a U24 from a list of 3 bytes.

Parameters:

bytes – A list of exactly 3 integers (0-255) representing bytes
byteorder – Byte order for interpretation (‘little’, ‘big’, or ‘native’)

Returns:

A new U24 instance

Raises:

ValueError – If bytes list is not exactly 3 bytes long or byteorder is invalid

Example:

bytes_le = [0xFF, 0xFF, 0xFF]
value = U24.from_bytes(bytes_le, byteorder='little')  # 16777215

Conversion Methods

U24.to_int() → int

Convert this U24 to a Python int.

Returns:: The U24 value as a Python int

Example:

x = U24(1000)
print(x.to_int())  # 1000

U24.to_bytes(byteorder: Literal['little', 'big', 'native'] = 'native') → list[int]

Convert this U24 to a list of bytes.

Parameters:: byteorder – Byte order for conversion (‘little’, ‘big’, or ‘native’)
Returns:: A list of 3 integers (0-255) representing the bytes
Raises:: ValueError – If byteorder is invalid

Example:

value = U24(0x123456)
be_bytes = value.to_bytes(byteorder='big')  # [18, 52, 86]

Comparison Operators

U24.__eq__(other: object) → bool: Test for equality.

U24.__ne__(other: object) → bool: Test for inequality.

U24.__lt__(other: U24) → bool: Test if less than.

U24.__le__(other: U24) → bool: Test if less than or equal.

U24.__gt__(other: U24) → bool: Test if greater than.

U24.__ge__(other: U24) → bool: Test if greater than or equal.

Arithmetic Operators

U24.__add__(other: U24) → U24

Add two U24 values.

Raises:: OverflowError – If the result overflows U24 range

U24.__sub__(other: U24) → U24

Subtract two U24 values.

Raises:: OverflowError – If the result overflows U24 range

U24.__mul__(other: U24) → U24

Multiply two U24 values.

Raises:: OverflowError – If the result overflows U24 range

U24.__truediv__(other: U24) → float

Divide two U24 values (true division, returns float).

Raises:: ZeroDivisionError – If dividing by zero

U24.__floordiv__(other: U24) → U24

Floor divide two U24 values.

Raises:: ZeroDivisionError – If dividing by zero

U24.__mod__(other: U24) → U24

Modulo operation on two U24 values.

Raises:: ZeroDivisionError – If dividing by zero

Bitwise Operators

U24.__and__(other: U24) → U24: Bitwise AND operation.

U24.__or__(other: U24) → U24: Bitwise OR operation.

U24.__xor__(other: U24) → U24: Bitwise XOR operation.

U24.__lshift__(other: int) → U24

Left shift operation.

Raises:

ValueError – If shift count is out of range (>= 32)
OverflowError – If the result overflows U24 range

U24.__rshift__(other: int) → U24

Right shift operation.

Raises:: ValueError – If shift count is out of range (>= 32)

U24.__invert__() → U24: Bitwise NOT operation.

Unary Operators

U24.__pos__() → U24: Unary positive (returns self).

Special Methods

U24.__int__() → int: Convert to Python int.

U24.__str__() → str: String representation (the numeric value).

U24.__repr__() → str: Developer-friendly representation.

U24.__hash__() → int: Hash value for use in sets and dicts.

Rounding Methods

U24.__round__(ndigits: int | None = None) → U24: Round to nearest integer (returns self for U24).

U24.__ceil__() → U24: Ceiling (returns self for U24).

U24.__floor__() → U24: Floor (returns self for U24).

U24.__trunc__() → U24: Truncate (returns self for U24).

Bit Manipulation Methods

U24.count_ones() → int: Count the number of one bits in the binary representation.

U24.count_zeros() → int: Count the number of zero bits in the binary representation.

U24.leading_zeros() → int: Count the number of leading zero bits.

U24.trailing_zeros() → int: Count the number of trailing zero bits.

U24.bit_length() → int: Number of bits necessary to represent this value.

U24.bit_count() → int: Number of one bits in the value.

Checked Arithmetic Methods

U24.checked_add(other: U24) → U24 | None

Checked addition. Returns None on overflow.

Parameters:: other – The U24 value to add
Returns:: The result if it fits in U24, None otherwise

U24.checked_sub(other: U24) → U24 | None

Checked subtraction. Returns None on overflow.

Parameters:: other – The U24 value to subtract
Returns:: The result if it fits in U24, None otherwise

U24.checked_mul(other: U24) → U24 | None

Checked multiplication. Returns None on overflow.

Parameters:: other – The U24 value to multiply
Returns:: The result if it fits in U24, None otherwise

U24.checked_div(other: U24) → U24 | None

Checked division. Returns None on division by zero.

Parameters:: other – The U24 value to divide by
Returns:: The result, or None if dividing by zero

Wrapping Arithmetic Methods

U24.wrapping_add(other: U24) → U24

Wrapping addition. Wraps on overflow.

Parameters:: other – The U24 value to add
Returns:: The wrapped result

U24.wrapping_sub(other: U24) → U24

Wrapping subtraction. Wraps on overflow.

Parameters:: other – The U24 value to subtract
Returns:: The wrapped result

U24.wrapping_mul(other: U24) → U24

Wrapping multiplication. Wraps on overflow.

Parameters:: other – The U24 value to multiply
Returns:: The wrapped result

Saturating Arithmetic Methods

U24.saturating_add(other: U24) → U24

Saturating addition. Clamps to min/max on overflow.

Parameters:: other – The U24 value to add
Returns:: The result, clamped to U24 range

U24.saturating_sub(other: U24) → U24

Saturating subtraction. Clamps to min/max on overflow.

Parameters:: other – The U24 value to subtract
Returns:: The result, clamped to U24 range

U24.saturating_mul(other: U24) → U24

Saturating multiplication. Clamps to min/max on overflow.

Parameters:: other – The U24 value to multiply
Returns:: The result, clamped to U24 range

Utility Methods

U24.as_integer_ratio() → Tuple[int, int]

Return integer ratio (self, 1).

Returns:: A tuple of (numerator, denominator) = (self.to_int(), 1)