hbutils.binary.str

This module provides C-style string types for binary I/O operations.

It includes support for null-terminated strings (like C strings) and fixed-size strings (like C char arrays). Both types support automatic encoding detection and custom encoding.

Classes:

CStringType: Null-terminated string type (ends with x00)
CSizedStringType: Fixed-size string type with specified buffer length

Functions:

c_sized_str: Factory function to create CSizedStringType instances

Module-level instances:

c_str: Default CStringType instance for reading/writing null-terminated strings

CStringType

class hbutils.binary.str.CStringType(encoding=None)[source]

Simple null-terminated string type.

This class represents C-style strings that end with a single \x00 byte, which is the standard string format in C language.

__init__(encoding=None)[source]

Constructor of CStringType.

Parameters:: encoding (Optional[str]) – Encoding type, default is None which means auto-detect the encodings.

property encoding: str | None

Get the encoding type used for string conversion.

Returns:: The encoding type, or None for auto-detection.
Return type:: Optional[str]

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

Read a null-terminated string value from binary file.

Reads bytes from the file until a null byte (x00) is encountered, then decodes the bytes to a string using the specified or auto-detected encoding.

Parameters:: file (BinaryIO) – Binary file object to read from, io.BytesIO is supported as well.
Returns:: The decoded string value (without the null terminator).
Return type:: str

write(file: BinaryIO, val: str)[source]

Write a null-terminated string value to binary IO object.

Encodes the string using the specified or default encoding and appends a null byte (x00) at the end.

Parameters:

file (BinaryIO) – Binary file object to write to, io.BytesIO is supported as well.
val (str) – String value to write.

Raises:

TypeError – If val is not a string.

c_str

hbutils.binary.str.c_str = <hbutils.binary.str.CStringType object>

Default instance for reading and writing null-terminated strings.

This instance provides convenient access to CStringType functionality with default encoding (auto-detection).

Examples:

>>> import io
>>> from hbutils.binary import c_str
>>> 
>>> with io.BytesIO(
...         b'kdsfjldsjflkdsmgds\x00'
...         b'\xd0\x94\xd0\xbe\xd0\xb1\xd1\x80\xd1\x8b\xd0\xb9 \xd0'
...         b'\xb2\xd0\xb5\xd1\x87\xd0\xb5\xd1\x80\x00'
...         b'\xa4\xb3\xa4\xf3\xa4\xd0\xa4\xf3\xa4\xcf\x00'
...         b'\xcd\xed\xc9\xcf\xba\xc3\x00'
... ) as file:
...     print(c_str.read(file))
...     print(c_str.read(file))
...     print(c_str.read(file))
...     print(c_str.read(file))
kdsfjldsjflkdsmgds
Добрый вечер
こんばんは
晚上好
>>> with io.BytesIO() as file:
...     c_str.write(file, "kdsfjld")
...     c_str.write(file, "Добрый")
...     print(file.getvalue())
b'kdsfjld\x00\xd0\x94\xd0\xbe\xd0\xb1\xd1\x80\xd1\x8b\xd0\xb9\x00'

CSizedStringType

class hbutils.binary.str.CSizedStringType(size: int, encoding=None)[source]

Fixed-size string type.

This class represents C-style fixed-size character arrays, defined like char s[size] in C language. The string occupies a fixed amount of space regardless of its actual content length.

__init__(size: int, encoding=None)[source]

Constructor of CSizedStringType.

Parameters:

size (int) – Size of the string’s buffer space in bytes.
encoding (Optional[str]) – Encoding type, default is None which means auto-detect the encodings.

property encoding: str | None

Get the encoding type used for string conversion.

Returns:: The encoding type, or None for auto-detection.
Return type:: Optional[str]

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

Read a fixed-size string value from binary file.

Reads exactly the specified number of bytes from the file, then decodes them as a null-terminated string using the specified or auto-detected encoding.

Parameters:: file (BinaryIO) – Binary file object to read from, io.BytesIO is supported as well.
Returns:: The decoded string value (without padding or null terminator).
Return type:: str

property size: int

Size of the given type in bytes.

Returns:: The size of the type.
Return type:: int

write(file: BinaryIO, val: str)[source]

Write a fixed-size string value to binary IO object.

Encodes the string and writes it to the file, padding with null bytes if necessary to fill the fixed size buffer.

Parameters:

file (BinaryIO) – Binary file object to write to, io.BytesIO is supported as well.
val (str) – String value to write.

Raises:

TypeError – If val is not a string.

c_sized_str

hbutils.binary.str.c_sized_str(size: int) → CSizedStringType[source]

Factory function to create a fixed-size string type.

Creates a CSizedStringType instance that reads and writes strings occupying a fixed amount of space, similar to C char arrays.

Parameters:: size (int) – Size of the string’s buffer space in bytes.
Returns:: A CSizedStringType instance with the specified size.
Return type:: CSizedStringType

Examples:

>>> import io
>>> from hbutils.binary import c_sized_str
>>> 
>>> with io.BytesIO(
...         b'kdsfjld\x00\x00\x00\x00\x00\x00\x00\x00'
...         b'\xd0\x94\xd0\xbe\xd0\xb1\xd1\x80\xd1\x8b\xd0\xb9\x00\x00\x00'
... ) as file:
...     print(c_sized_str(15).read(file))
...     print(c_sized_str(15).read(file))
kdsfjld
Добрый
>>> with io.BytesIO() as file:
...     c_sized_str(15).write(file, "kdsfjld")
...     c_sized_str(15).write(file, "Добрый")
...     print(file.getvalue())
b'kdsfjld\x00\x00\x00\x00\x00\x00\x00\x00\xd0\x94\xd0\xbe\xd0\xb1\xd1\x80\xd1\x8b\xd0\xb9\x00\x00\x00'