Integer Types#

This document provides detailed API documentation for integer types in the caterpillar.c module. These integer types are low-level representations of integers with customizable bit-length, signedness, and byte order. They are particularly useful when interacting with binary data or when a fixed-width integer representation is required.

The integer types offered here are optimized for performance, making them more efficient than their Python equivalents (FormatField) in almost every context. The global predefined integer types (e.g., u8, i32) are convenient for most common cases, but you can also define custom integer types with specific bit-widths, signedness, and endianness using the Int class.

class caterpillar.c.Int(bits, signed=True, little_endian=True)#

C API Type: CpIntAtomObject

This class implements an integer type with a variable number of bits, supporting signed and unsigned integers, and little-endian or big-endian byte orders.

Unlike its Python counterpart (FormatField), this C-based class focuses solely on integer operations, optimizing performance through direct use of the int.from_bytes and int.to_bytes methods. Although you can instantiate the class directly, it is recommended to use the global predefined instances for common integer types (see below for more details).

Note

For most use cases, utilize the pre-defined global instances like u8, i16, etc., for simplicity and efficiency.

Supported Operations#
Action	Operator	Result
Byteorder	`<endian> + <obj>`	new `Int` object with corresponding byteorder
Sequence	`<obj>[<length>]`	`repeated` object
Offset	`<obj> @ <offset>`	`atoffset` object
Condition	`<obj> // <condition>`	`condition` object
Switch	`<obj> >> <cases>`	`switch` object

Added in version 2.2.0.

__init__(self, bits, signed=True, little_endian=True)#

Initializes the integer type with the given number of bits, sign specification, and byte order.

Parameters:

bits (int) – The number of bits for the integer. Must be a multiple of 8.
signed (bool) – Optional; whether the integer is signed. Defaults to True.
little_endian (bool) – Optional; whether the integer should be stored in little-endian byte order. Defaults to True.

Examples of using Int#

from caterpillar.c import *

# Unsigned 8-bit integer
assert unpack(b"\x01", u8) == 1

# Signed 8-bit integer
assert pack(1, i8) == b"\x01"

# Unsigned 16-bit little-endian integer
assert unpack(b"\x01\x00", u16) == 1

# Signed 16-bit big-endian integer
assert pack(-1, Int(16, signed=True, little_endian=False)) == b"\xff\xff"

__repr__(self) → str#

Returns a string representation of the integer type. The format of the returned string is as follows:

<repr> := '<' ('le' | 'be') ['u'] 'int' <nbits> '>'

>>> assert repr(u32) == "<le uint32>"

Returns:: A string representation of the integer type, indicating the byte order, sign, and number of bits.

__type__(self) → type#

Returns the Python type for this class. This is typically int.

Returns:: The Python type for this class.

__size__(self, ctx) → int#

Returns the size in bytes of the integer type.

>>> assert sizeof(u64) == 8

Parameters:: ctx – The context object. (must not be null)
Returns:: The size in bytes of the integer type.

nbytes: int#: The number of bytes in the integer, calculated from nbits.

nbits: int#

The number of bits in the integer.

>>> assert u32.nbits == 32

signed: bool#

Indicates whether the integer is signed (True) or unsigned (False).

>>> assert i8.signed is True

little_endian: bool#

Indicates whether the integer is stored in little-endian byte order (True) or big-endian byte order (False).

>>> assert Int(32, little_endian=False).little_endian is False
>>> assert (BIG_ENDIAN + u32).little_endian is False

Pre-Defined Integer Types (global)#

The following pre-defined integer types are globally available, optimized for common use cases. By default, they use little-endian byte order. To switch to big-endian, use the byteorder operation (e.g., BIG_ENDIAN + u16).

Unsigned Integer Types:#

caterpillar.c.u8#: Unsigned 8-bit integer type.

caterpillar.c.u16#: Unsigned 16-bit integer type.

caterpillar.c.u24#: Unsigned 24-bit integer type.

caterpillar.c.u32#: Unsigned 32-bit integer type.

caterpillar.c.u64#: Unsigned 64-bit integer type.

caterpillar.c.u128#: Unsigned 128-bit integer type.

Signed Integer Types:#

caterpillar.c.i8#: Signed 8-bit integer type.

caterpillar.c.i16#: Signed 16-bit integer type.

caterpillar.c.i24#: Signed 24-bit integer type.

caterpillar.c.i32#: Signed 32-bit integer type.

caterpillar.c.i64#: Signed 64-bit integer type.

caterpillar.c.i128#: Signed 128-bit integer type.