Skip to content
Back to top
View this page

# 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).