hbutils.binary.str

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

This module provides implementations of C-style string handling for binary streams, including null-terminated strings (char * / char[] with a terminator) and fixed-size buffers (char s[size]). The types are designed to operate on binary file objects such as io.BytesIO and other typing.BinaryIO-compatible streams.

The module contains the following public components:

Example:

>>> import io
>>> from hbutils.binary import c_str, c_sized_str
>>>
>>> with io.BytesIO(b'hello\x00world\x00') as file:
...     print(c_str.read(file))
...     print(c_str.read(file))
hello
world
>>> with io.BytesIO() as file:
...     c_sized_str(8).write(file, "hi")
...     print(file.getvalue())
b'hi\x00\x00\x00\x00\x00\x00'

Note

The CSizedStringType decoder currently uses automatic encoding detection during reads, regardless of the instance’s encoding attribute.

__all__

hbutils.binary.str.__all__ = ['CStringType', 'c_str', 'CSizedStringType', 'c_sized_str']

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_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 the 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'

CStringType

class hbutils.binary.str.CStringType(encoding: str | None = 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 the C language.

Parameters:

encoding (Optional[str]) – Encoding type, default is None which enables auto-detection during decoding and UTF-8 during encoding.

Variables:

encoding (Optional[str]) – Encoding type configured for the instance.

__init__(encoding: str | None = 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 a 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.

Returns:

The decoded string value (without the null terminator).

Return type:

str

Raises:

IndexError – If EOF is reached before a null terminator is found.

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

Write a null-terminated string value to a 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.

  • val (str) – String value to write.

Raises:

TypeError – If val is not a string.

Example:

>>> import io
>>> from hbutils.binary import c_str
>>> with io.BytesIO() as file:
...     c_str.write(file, "hello")
...     print(file.getvalue())
b'hello\x00'

CSizedStringType

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

Fixed-size string type.

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

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 during decoding and UTF-8 during encoding.

Variables:

  • encoding (Optional[str]) – Encoding type configured for the instance.

  • size (int) – Size of the fixed buffer in bytes.

__init__(size: int, encoding: str | None = 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 a binary file.

Reads exactly the specified number of bytes from the file, then decodes them as a null-terminated string using auto-detected encoding. The current implementation uses c_str internally, so any encoding configured on this instance is not applied during reads.

Parameters:

file (BinaryIO) – Binary file object to read from; io.BytesIO is supported.

Returns:

The decoded string value (without padding or null terminator).

Return type:

str

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

Write a fixed-size string value to a 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.

  • 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'