hbutils.binary.int

Signed integer binary I/O utilities.

This module implements signed integer types for binary input/output operations using little-endian byte order. It provides fixed-size signed integer types (8-bit, 16-bit, 32-bit, and 64-bit) and platform-dependent aliases that mirror the sizes of C language integer types.

The module contains the following public components:

CSignedIntType - Signed integer type with two’s complement conversion.
c_int8 - 8-bit signed integer reader/writer.
c_int16 - 16-bit signed integer reader/writer.
c_int32 - 32-bit signed integer reader/writer.
c_int64 - 64-bit signed integer reader/writer.
c_byte - C-compatible signed byte alias.
c_short - C-compatible signed short alias.
c_int - C-compatible signed int alias.
c_long - C-compatible signed long alias.
c_longlong - C-compatible signed long long alias.

These types are primarily used to read from and write to binary files or streams while handling two’s complement representation for signed integers.

Example:

>>> import io
>>> from hbutils.binary import c_int32
>>>
>>> # Reading signed integers
>>> with io.BytesIO(b'\xde\xad\xbe\xef') as file:
...     value = c_int32.read(file)
...     print(value)
-272716322
>>>
>>> # Writing signed integers
>>> with io.BytesIO() as file:
...     c_int32.write(file, -272716322)
...     print(file.getvalue())
b'\xde\xad\xbe\xef'

all

hbutils.binary.int.__all__ = ['CSignedIntType', 'c_int8', 'c_int16', 'c_int32', 'c_int64', 'c_byte', 'c_short', 'c_int', 'c_long', 'c_longlong']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

c_int8

hbutils.binary.int.c_int8 = <hbutils.binary.int.CSignedIntType object>

Reading and writing signed integer with 8-bits.

This type represents a signed 8-bit integer with a range of -128 to 127.

Examples:

>>> import io
>>> from hbutils.binary import c_int8
>>>
>>> with io.BytesIO(b'\xde\xad\xbe\xef') as file:
...     print(c_int8.read(file))
...     print(c_int8.read(file))
...     print(c_int8.read(file))
...     print(c_int8.read(file))
-34
-83
-66
-17
>>> with io.BytesIO() as file:
...     c_int8.write(file, -34)
...     c_int8.write(file, -83)
...     c_int8.write(file, -66)
...     c_int8.write(file, -17)
...     print(file.getvalue())
b'\xde\xad\xbe\xef'

c_int16

hbutils.binary.int.c_int16 = <hbutils.binary.int.CSignedIntType object>

Reading and writing signed integer with 16-bits.

This type represents a signed 16-bit integer with a range of -32768 to 32767.

Examples:

>>> import io
>>> from hbutils.binary import c_int16
>>>
>>> with io.BytesIO(b'\xde\xad\xbe\xef\x12\x34\x56\xf7') as file:
...     print(c_int16.read(file))
...     print(c_int16.read(file))
...     print(c_int16.read(file))
...     print(c_int16.read(file))
-21026
-4162
13330
-2218
>>> with io.BytesIO() as file:
...     c_int16.write(file, -21026)
...     c_int16.write(file, -4162)
...     c_int16.write(file, 13330)
...     c_int16.write(file, -2218)
...     print(file.getvalue())
b'\xde\xad\xbe\xef\x124V\xf7'

c_int32

hbutils.binary.int.c_int32 = <hbutils.binary.int.CSignedIntType object>

Reading and writing signed integer with 32-bits.

This type represents a signed 32-bit integer with a range of -2147483648 to 2147483647.

Examples:

>>> import io
>>> from hbutils.binary import c_int32
>>>
>>> with io.BytesIO(b'\xde\xad\xbe\xef\x12\x34\x56\xf7') as file:
...     print(c_int32.read(file))
...     print(c_int32.read(file))
-272716322
-145345518
>>> with io.BytesIO() as file:
...     c_int32.write(file, -272716322)
...     c_int32.write(file, -145345518)
...     print(file.getvalue())
b'\xde\xad\xbe\xef\x124V\xf7'

c_int64

hbutils.binary.int.c_int64 = <hbutils.binary.int.CSignedIntType object>

Reading and writing signed integer with 64-bits.

This type represents a signed 64-bit integer with a range of -9223372036854775808 to 9223372036854775807.

Examples:

>>> import io
>>> from hbutils.binary import c_int64
>>>
>>> with io.BytesIO(b'\xde\xad\xbe\xef\x12\x34\x56\xf7') as file:
...     print(c_int64.read(file))
-624254242407928354
>>> with io.BytesIO() as file:
...     c_int64.write(file, -624254242407928354)
...     print(file.getvalue())
b'\xde\xad\xbe\xef\x124V\xf7'

c_byte

hbutils.binary.int.c_byte = <hbutils.binary.int.CSignedIntType object>

Alias for c_int8.

This type represents a signed byte, equivalent to a signed 8-bit integer.

c_short

hbutils.binary.int.c_short = <hbutils.binary.int.CSignedIntType object>

Alias for c_int16.

This type represents a short integer, equivalent to a signed 16-bit integer.

c_int

hbutils.binary.int.c_int = <hbutils.binary.int.CSignedIntType object>: Alias for c_int32 (in 64-bit OS).

Note

Size of c_int is the same as that in C language, which mainly depends on CPU and OS. On most modern 64-bit systems, this is a 32-bit signed integer.

c_long

hbutils.binary.int.c_long = <hbutils.binary.int.CSignedIntType object>: Alias for c_int64 (in 64-bit OS).

Note

Size of c_long is the same as that in C language, which mainly depends on CPU and OS. On 64-bit Unix-like systems, this is typically a 64-bit signed integer. On Windows, it may be 32-bit even on 64-bit systems.

c_longlong

hbutils.binary.int.c_longlong = <hbutils.binary.int.CSignedIntType object>: Alias for c_int64 (in 64-bit OS).

Note

Size of c_longlong is the same as that in C language, which mainly depends on CPU and OS. This is typically a 64-bit signed integer on all modern platforms.

CSignedIntType

class hbutils.binary.int.CSignedIntType(size: int)[source]

Signed integer type for binary I/O operations.

This class provides functionality to read and write signed integers of a specific size to and from binary streams. It handles two’s complement representation internally by using an unsigned integer type for the actual I/O operations.

Parameters:: size (int) – Size of the integer type in bytes.

Example:

>>> import io
>>> from hbutils.binary import CSignedIntType
>>>
>>> # Create a 2-byte signed integer type
>>> int16_type = CSignedIntType(2)
>>>
>>> # Read a signed integer
>>> with io.BytesIO(b'\xde\xad') as file:
...     value = int16_type.read(file)
...     print(value)
-21026
>>>
>>> # Write a signed integer
>>> with io.BytesIO() as file:
...     int16_type.write(file, -21026)
...     print(file.getvalue())
b'\xde\xad'

__init__(size: int)[source]

Initialize a signed integer type with the specified size.

Parameters:: size (int) – Size of the integer type in bytes.

The constructor sets up the internal unsigned integer type for I/O operations and calculates the valid range for signed integers of this size.

read(file: BinaryIO) → int[source]

Read a signed integer value from a binary stream.

Parameters:: file (BinaryIO) – Binary file or stream to read from. io.BytesIO is supported as well.
Returns:: The signed integer value read from the stream.
Return type:: int

This method reads the unsigned representation and converts it to a signed integer using two’s complement representation.

Example:

>>> import io
>>> from hbutils.binary import c_int16
>>>
>>> with io.BytesIO(b'\xde\xad') as file:
...     value = c_int16.read(file)
...     print(value)
-21026

write(file: BinaryIO, val: int) → None[source]

Write a signed integer value to a binary stream.

Parameters:

file (BinaryIO) – Binary file or stream to write to. io.BytesIO is supported as well.
val (int) – Signed integer value to write.

Returns:

None.

Return type:

None

Raises:

TypeError – If the value is not an integer.
ValueError – If the value is outside the valid range for this integer type.

This method converts the signed integer to its unsigned two’s complement representation before writing to the stream.

Example:

>>> import io
>>> from hbutils.binary import c_int16
>>>
>>> with io.BytesIO() as file:
...     c_int16.write(file, -21026)
...     print(file.getvalue())
b'\xde\xad'

hbutils.binary.int

__all__

c_int8

c_int16

c_int32

c_int64

c_byte

c_short

c_int

c_long

c_longlong

CSignedIntType

all