I24 Class

class I24(value: int)

A 24-bit signed integer type with range -8,388,608 to 8,388,607.

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

Parameters:: value (int) – An integer in the range [-8,388,608, 8,388,607]
Raises:: ValueError – If value is out of range for I24

Example:

from i24 import I24

x = I24(1000)
y = I24(-500)
result = x + y
print(result.to_int())  # 500

Class Attributes

I24.min_value: I24: The minimum value for I24: I24(-8388608)

I24.max_value: I24: The maximum value for I24: I24(8388607)

Construction Methods

I24.__init__(value: int) → None

Create a new I24 from a Python int.

Parameters:: value – An integer in the range [-8,388,608, 8,388,607]
Raises:: ValueError – If value is out of range

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

Create an I24 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 I24 instance

Raises:

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

Example:

bytes_le = [0x00, 0x10, 0x00]
value = I24.from_bytes(bytes_le, byteorder='little')

Conversion Methods

I24.to_int() → int

Convert this I24 to a Python int.

Returns:: The I24 value as a Python int

Example:

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

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

Convert this I24 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 = I24(0x123456)
be_bytes = value.to_bytes(byteorder='big')  # [18, 52, 86]

Comparison Operators

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

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

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

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

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

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

Arithmetic Operators

I24.__add__(other: I24) → I24

Add two I24 values.

Raises:: OverflowError – If the result overflows I24 range

I24.__sub__(other: I24) → I24

Subtract two I24 values.

Raises:: OverflowError – If the result overflows I24 range

I24.__mul__(other: I24) → I24

Multiply two I24 values.

Raises:: OverflowError – If the result overflows I24 range

I24.__truediv__(other: I24) → float

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

Raises:: ZeroDivisionError – If dividing by zero

I24.__floordiv__(other: I24) → I24

Floor divide two I24 values.

Raises:: ZeroDivisionError – If dividing by zero

I24.__mod__(other: I24) → I24

Modulo operation on two I24 values.

Raises:: ZeroDivisionError – If dividing by zero

Bitwise Operators

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

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

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

I24.__lshift__(other: int) → I24

Left shift operation.

Raises:

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

I24.__rshift__(other: int) → I24

Right shift operation.

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

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

Unary Operators

I24.__neg__() → I24

Negate this I24 value.

Raises:: OverflowError – If negating I24::MIN

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

I24.__abs__() → I24

Absolute value.

Raises:: OverflowError – If called on I24::MIN

Special Methods

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

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

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

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

Rounding Methods

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

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

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

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

Bit Manipulation Methods

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

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

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

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

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

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

Checked Arithmetic Methods

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

Checked addition. Returns None on overflow.

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

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

Checked subtraction. Returns None on overflow.

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

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

Checked multiplication. Returns None on overflow.

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

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

Checked division. Returns None on division by zero.

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

Wrapping Arithmetic Methods

I24.wrapping_add(other: I24) → I24

Wrapping addition. Wraps on overflow.

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

I24.wrapping_sub(other: I24) → I24

Wrapping subtraction. Wraps on overflow.

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

I24.wrapping_mul(other: I24) → I24

Wrapping multiplication. Wraps on overflow.

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

Saturating Arithmetic Methods

I24.saturating_add(other: I24) → I24

Saturating addition. Clamps to min/max on overflow.

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

I24.saturating_sub(other: I24) → I24

Saturating subtraction. Clamps to min/max on overflow.

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

I24.saturating_mul(other: I24) → I24

Saturating multiplication. Clamps to min/max on overflow.

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

Utility Methods

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

Return integer ratio (self, 1).

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