jam.utils.codec.primitives.strings module

String codec implementation for JAM protocol.

Implements encoding and decoding of string values according to the JAM specification. Strings are encoded with a length prefix followed by UTF-8 encoded bytes.

Format:

[Length: u64][UTF-8 encoded bytes]

The length is encoded using little-endian u64 format to match specification and ensure compatibility with the maximum possible string size.

class jam.utils.codec.primitives.strings.StringCodec

Bases: Codec[str]

Codec for string values.

Handles both str and static str references with UTF-8 encoding. Maximum string length is determined by u64 max value.

encode_size(value: str | bytes) → int

Calculate the number of bytes needed to encode the string.

The size includes: - 8 bytes for length prefix (u64) - bytes needed for UTF-8 encoded string content

Parameters:

value – String to encode

Returns:

Total number of bytes needed

Raises:

EncodeError – If string is too large to encode

encode_into(value: str, buffer: bytearray, offset: int = 0) → int

Encode a string into the provided buffer.

Parameters:

• value – String to encode

• buffer – Target buffer

• offset – Starting position in buffer

Returns:

Number of bytes written

Raises:

EncodeError – If buffer is too small or string cannot be encoded

static decode_from(buffer: bytes | bytearray | memoryview, offset: int = 0) → Tuple[str, int]

Decode a string from the provided buffer.

Parameters:

• buffer – Source buffer

• offset – Starting position in buffer

Returns:

Tuple of (decoded string, bytes read)

Raises:

DecodeError – If buffer is too small or contains invalid UTF-8