binobj.fields.stringlike module

Fields representing strings and byte sequences.

class Bytes(*_args: Any, **kwargs: Any)

Bases: Field[bytes]

Raw binary data.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class String(*_args: Any, **kwargs: Any)

Bases: Field[str]

A fixed-length string.

Parameters:

• size (int) – The field’s size in bytes, not characters. For most text encodings these are the same, but some encodings use multiple bytes per character.

• encoding (str) – The encoding to use for converting the string to and from bytes. Defaults to ISO 8859-1.

• pad_byte (bytes) –

  A single byte to use as padding for strings that are too short to fit into the field. If not given, strings that aren’t exactly size bytes when encoded will trigger a ValueSizeError.

  New in version 0.2.0.

Note

The utf-8-sig, utf-16, and utf-32 codecs add a byte order mark (BOM) at the beginning of the string, so you’ll need to take those extra bytes into account when defining this field size. Alternatively, you can use the codecs’ variants that don’t add the BOM, such as utf-16-le or utf-16-be.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class StringZ(*_args: Any, **kwargs: Any)

Bases: String

A variable-length null-terminated string.

The terminating null is guaranteed to be the proper size for multi-byte encodings.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class UUID4(*_args: Any, **kwargs: Any)

Bases: Field[UUID]

A UUID, version 4 (the most common nowadays).

New in version 0.11.0.

class UUIDFormat(value)

Bases: Enum

The storage format of a UUID4.

BINARY_VARIANT_1 = 'binary_var_1'

The binary format, RFC-4122 variant 1.

The UUID4 is stored as a 16-byte sequence of big-endian integers. This is the most common format used today.

BINARY_VARIANT_2 = 'binary_var_2'

The binary format, RFC-4122 variant 2.

The UUID4 is stored as a 16-byte sequence of integers in mixed-endian format. This is described in the RFC as “Microsoft Corporation backward compatibility format”. As the name suggests, this is pretty much only used by Microsoft software.

CANONICAL_STRING = 'canonical_string'

The canonical string representation of a UUID4.

An example would be the ASCII string “4fcd056d-f29b-4cb8-8e37-99ab1b56a555”.

HEX_STRING = 'hex_string'

Like CANONICAL_STRING but without dashes.