librt.strings¶

The librt.strings module is part of the librt package on PyPI, and it includes low-level string and bytes utilities.

Classes¶

Thread safety¶

BytesWriter and StringWriter objects are unsafe to access from another thread if they are concurrently modified (on free-threaded Python builds). They are optimized for maximal performance, and they aren’t fully synchronized. Read-only access from multiple threads is safe.

BytesWriter¶

class BytesWriter¶

This class can be used to efficiently construct a bytes object from individual byte values and from bytes or bytearray objects. It also provides some operations for accessing and modifying items, but it doesn’t support the full sequence interface.

This can be used as a faster replacement for io.BytesIO or bytearray in compiled code. This is also usually faster than constructing a list of bytes objects and using the bytes.join() method to concatenate them.

append(x: int, /) → None¶: Append a byte to contents.

write(b: bytes | bytearray, /) → None¶: Append a bytes or bytearray object to contents.

getvalue() → bytes¶: Return the contents as a bytes object.

truncate(size: i64, /) → None¶: Truncate the length of the contents to the given size.

len(writer) → i64: Return the length of the contents.

writer[i] → u8: Return the byte at a specific index. The index can be negative.

writer[i] = x: Set a byte at a specific index. The index can be negative.

StringWriter¶

class StringWriter¶

This class can be used to efficiently construct a string object from individual Unicode code point integer values and from string objects. It also provides some operations for accessing items, but it doesn’t support the full sequence interface.

StringWriter can be used as a faster replacement for io.StringIO in compiled code. This is also usually faster than constructing a list of str objects and using the str.join() method to concatenate them.

If you construct a string from individual characters or code points, using integer values can be much faster than using 1-length strings. You can rely on expressions like ord("x") being treated as compile-time integer constants in compiled code. Also ord(s[i]) is guaranteed to be a very quick operation in compiled code, if s has type str.

append(x: int, /) → None¶: Append a Unicode code point (often representing a character) to the contents.

write(s: str, /) → None¶: Append a string to contents.

getvalue() → str¶: Return the contents as a string.

len(writer) → i64: Return the length of the contents (number of code points).

writer[i] → i32: Return the Unicode code point at a specific index as an integer. The index can be negative.

Functions¶

The write_* and read_* functions allow interpreting bytes as packed binary data. They can be used as (much) more efficient but lower-level alternatives to the stdlib struct module in compiled code.

There are no functions for reading or writing individual bytes. BytesWriter.append can be used to insert a byte value, and b[n] can be used to read a byte value. Both are fast operations in compiled code.

This example writes two binary values and reads them afterwards:

def example() -> None:
    b = BytesWriter()
    write_i32_le(b, 123)
    write_f64_le(b, 4.5)
    data = b.getvalue()

    x = read_i32_le(data, 0)
    y = read_f64_le(data, 4)
    ...

write_i16_le(b: BytesWriter, n: i16, /) → None¶: Append a 16-bit integer as a little-endian binary value.

write_i16_be(b: BytesWriter, n: i16, /) → None¶: Append a 16-bit integer as a big-endian binary value.

read_i16_le(b: bytes, index: i64, /) → i16¶: Read a 16-bit integer value starting at the given index as a little-endian binary value (2 bytes).

read_i16_be(b: bytes, index: i64, /) → i16¶: Read a 16-bit integer value starting at the given index as a big-endian binary value (2 bytes).

write_i32_le(b: BytesWriter, n: i32, /) → None¶: Append a 32-bit integer as a little-endian binary value.

write_i32_be(b: BytesWriter, n: i32, /) → None¶: Append a 32-bit integer as a big-endian binary value.

read_i32_le(b: bytes, index: i64, /) → i32¶: Read a 32-bit integer value starting at the given index as a little-endian binary value (4 bytes).

read_i32_be(b: bytes, index: i64, /) → i32¶: Read a 32-bit integer value starting at the given index as a big-endian binary value (4 bytes).

write_i64_le(b: BytesWriter, n: i64, /) → None¶: Append a 64-bit integer as a little-endian binary value.

write_i64_be(b: BytesWriter, n: i64, /) → None¶: Append a 64-bit integer as a big-endian binary value.

read_i64_le(b: bytes, index: i64, /) → i64¶: Read a 64-bit integer value starting at the given index as a little-endian binary value (8 bytes).

read_i64_be(b: bytes, index: i64, /) → i64¶: Read a 64-bit integer value starting at the given index as a big-endian binary value (8 bytes).

write_f32_le(b: BytesWriter, n: float, /) → None¶: Append a 32-bit floating-point value as a little-endian binary value.

write_f32_be(b: BytesWriter, n: float, /) → None¶: Append a 32-bit floating-point value as a big-endian binary value.

read_f32_le(b: bytes, index: i64, /) → float¶: Read a 32-bit floating-point value starting at the given index as a little-endian binary value (4 bytes).

read_f32_be(b: bytes, index: i64, /) → float¶: Read a 32-bit floating-point value starting at the given index as a big-endian binary value (4 bytes).

write_f64_le(b: BytesWriter, n: float, /) → None¶: Append a 64-bit floating-point value as a little-endian binary value.

write_f64_be(b: BytesWriter, n: float, /) → None¶: Append a 64-bit floating-point value as a big-endian binary value.

read_f64_le(b: bytes, index: i64, /) → float¶: Read a 64-bit floating-point value starting at the given index as a little-endian binary value (8 bytes).

read_f64_be(b: bytes, index: i64, /) → float¶: Read a 64-bit floating-point value starting at the given index as a big-endian binary value (8 bytes).