ByteReader

class ByteReader(*args, **kwargs)

ByteReader provides a byte reader that can read different integer and floating point types from a memory buffer. It provides functions for reading signed/unsigned, little/big endian integers of 8, 16, 24, 32 and 64 bits and functions for reading little/big endian floating points numbers of 32 and 64 bits. It also provides functions to read NUL-terminated strings in various character encodings.

Methods

class ByteReader

dup_data() → tuple[bool, bytes]

Free-function: g_free

Returns a newly-allocated copy of the current data position if at least size bytes are left and updates the current position. Free with free() when no longer needed.

dup_string_utf16() → tuple[bool, list[int]]

Free-function: g_free

Returns a newly-allocated copy of the current data position if there is a NUL-terminated UTF-16 string in the data (this could be an empty string as well), and advances the current position.

No input checking for valid UTF-16 is done. This function is endianness agnostic - you should not assume the UTF-16 characters are in host endianness.

This function will fail if no NUL-terminator was found in in the data.

Note: there is no peek or get variant of this function to ensure correct byte alignment of the UTF-16 string.

dup_string_utf32() → tuple[bool, list[int]]

Free-function: g_free

Returns a newly-allocated copy of the current data position if there is a NUL-terminated UTF-32 string in the data (this could be an empty string as well), and advances the current position.

No input checking for valid UTF-32 is done. This function is endianness agnostic - you should not assume the UTF-32 characters are in host endianness.

This function will fail if no NUL-terminator was found in in the data.

Note: there is no peek or get variant of this function to ensure correct byte alignment of the UTF-32 string.

dup_string_utf8() → tuple[bool, list[str]]

Free-function: g_free

FIXME:Reads (copies) a NUL-terminated string in the ByteReader instance, advancing the current position to the byte after the string. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done.

This function will fail if no NUL-terminator was found in in the data.

free() → None: Frees a ByteReader instance, which was previously allocated by new().

get_data() → tuple[bool, bytes]: Returns a constant pointer to the current data position if at least size bytes are left and updates the current position.

get_float32_be() → tuple[bool, float]: Read a 32 bit big endian floating point value into val and update the current position.

get_float32_le() → tuple[bool, float]: Read a 32 bit little endian floating point value into val and update the current position.

get_float64_be() → tuple[bool, float]: Read a 64 bit big endian floating point value into val and update the current position.

get_float64_le() → tuple[bool, float]: Read a 64 bit little endian floating point value into val and update the current position.

get_int16_be() → tuple[bool, int]: Read a signed 16 bit big endian integer into val and update the current position.

get_int16_le() → tuple[bool, int]: Read a signed 16 bit little endian integer into val and update the current position.

get_int24_be() → tuple[bool, int]: Read a signed 24 bit big endian integer into val and update the current position.

get_int24_le() → tuple[bool, int]: Read a signed 24 bit little endian integer into val and update the current position.

get_int32_be() → tuple[bool, int]: Read a signed 32 bit big endian integer into val and update the current position.

get_int32_le() → tuple[bool, int]: Read a signed 32 bit little endian integer into val and update the current position.

get_int64_be() → tuple[bool, int]: Read a signed 64 bit big endian integer into val and update the current position.

get_int64_le() → tuple[bool, int]: Read a signed 64 bit little endian integer into val and update the current position.

get_int8() → tuple[bool, int]: Read a signed 8 bit integer into val and update the current position.

get_pos() → int: Returns the current position of a ByteReader instance in bytes.

get_remaining() → int: Returns the remaining number of bytes of a ByteReader instance.

get_size() → int: Returns the total number of bytes of a ByteReader instance.

get_string_utf8() → tuple[bool, list[str]]

Returns a constant pointer to the current data position if there is a NUL-terminated string in the data (this could be just a NUL terminator), advancing the current position to the byte after the string. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc.

No input checking for valid UTF-8 is done.

This function will fail if no NUL-terminator was found in in the data.

get_uint16_be() → tuple[bool, int]: Read an unsigned 16 bit big endian integer into val and update the current position.

get_uint16_le() → tuple[bool, int]: Read an unsigned 16 bit little endian integer into val and update the current position.

get_uint24_be() → tuple[bool, int]: Read an unsigned 24 bit big endian integer into val and update the current position.

get_uint24_le() → tuple[bool, int]: Read an unsigned 24 bit little endian integer into val and update the current position.

get_uint32_be() → tuple[bool, int]: Read an unsigned 32 bit big endian integer into val and update the current position.

get_uint32_le() → tuple[bool, int]: Read an unsigned 32 bit little endian integer into val and update the current position.

get_uint64_be() → tuple[bool, int]: Read an unsigned 64 bit big endian integer into val and update the current position.

get_uint64_le() → tuple[bool, int]: Read an unsigned 64 bit little endian integer into val and update the current position.

get_uint8() → tuple[bool, int]: Read an unsigned 8 bit integer into val and update the current position.

init(data: Sequence[int]) → None

Initializes a ByteReader instance to read from data. This function can be called on already initialized instances.

Parameters:: data – data from which the ByteReader should read

masked_scan_uint32(mask: int, pattern: int, offset: int, size: int) → int

Scan for pattern pattern with applied mask mask in the byte reader data, starting from offset offset relative to the current position.

The bytes in pattern and mask are interpreted left-to-right, regardless of endianness. All four bytes of the pattern must be present in the byte reader data for it to match, even if the first or last bytes are masked out.

It is an error to call this function without making sure that there is enough data (offset+size bytes) in the byte reader.

Parameters:

mask – mask to apply to data before matching against pattern
pattern – pattern to match (after mask is applied)
offset – offset from which to start scanning, relative to the current position
size – number of bytes to scan from offset

masked_scan_uint32_peek(mask: int, pattern: int, offset: int, size: int) → tuple[int, int]

Scan for pattern pattern with applied mask mask in the byte reader data, starting from offset offset relative to the current position.

It is an error to call this function without making sure that there is enough data (offset+size bytes) in the byte reader.

Added in version 1.6.

Parameters:

mask – mask to apply to data before matching against pattern
pattern – pattern to match (after mask is applied)
offset – offset from which to start scanning, relative to the current position
size – number of bytes to scan from offset

peek_data() → tuple[bool, bytes]: Returns a constant pointer to the current data position if at least size bytes are left and keeps the current position.

peek_float32_be() → tuple[bool, float]: Read a 32 bit big endian floating point value into val but keep the current position.

peek_float32_le() → tuple[bool, float]: Read a 32 bit little endian floating point value into val but keep the current position.

peek_float64_be() → tuple[bool, float]: Read a 64 bit big endian floating point value into val but keep the current position.

peek_float64_le() → tuple[bool, float]: Read a 64 bit little endian floating point value into val but keep the current position.

peek_int16_be() → tuple[bool, int]: Read a signed 16 bit big endian integer into val but keep the current position.

peek_int16_le() → tuple[bool, int]: Read a signed 16 bit little endian integer into val but keep the current position.

peek_int24_be() → tuple[bool, int]: Read a signed 24 bit big endian integer into val but keep the current position.

peek_int24_le() → tuple[bool, int]: Read a signed 24 bit little endian integer into val but keep the current position.

peek_int32_be() → tuple[bool, int]: Read a signed 32 bit big endian integer into val but keep the current position.

peek_int32_le() → tuple[bool, int]: Read a signed 32 bit little endian integer into val but keep the current position.

peek_int64_be() → tuple[bool, int]: Read a signed 64 bit big endian integer into val but keep the current position.

peek_int64_le() → tuple[bool, int]: Read a signed 64 bit little endian integer into val but keep the current position.

peek_int8() → tuple[bool, int]: Read a signed 8 bit integer into val but keep the current position.

peek_string_utf8() → tuple[bool, list[str]]

Returns a constant pointer to the current data position if there is a NUL-terminated string in the data (this could be just a NUL terminator). The current position will be maintained. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc.

No input checking for valid UTF-8 is done.

This function will fail if no NUL-terminator was found in in the data.

peek_uint16_be() → tuple[bool, int]: Read an unsigned 16 bit big endian integer into val but keep the current position.

peek_uint16_le() → tuple[bool, int]: Read an unsigned 16 bit little endian integer into val but keep the current position.

peek_uint24_be() → tuple[bool, int]: Read an unsigned 24 bit big endian integer into val but keep the current position.

peek_uint24_le() → tuple[bool, int]: Read an unsigned 24 bit little endian integer into val but keep the current position.

peek_uint32_be() → tuple[bool, int]: Read an unsigned 32 bit big endian integer into val but keep the current position.

peek_uint32_le() → tuple[bool, int]: Read an unsigned 32 bit little endian integer into val but keep the current position.

peek_uint64_be() → tuple[bool, int]: Read an unsigned 64 bit big endian integer into val but keep the current position.

peek_uint64_le() → tuple[bool, int]: Read an unsigned 64 bit little endian integer into val but keep the current position.

peek_uint8() → tuple[bool, int]: Read an unsigned 8 bit integer into val but keep the current position.

set_pos(pos: int) → bool

Sets the new position of a ByteReader instance to pos in bytes.

Parameters:: pos – The new position in bytes

skip(nbytes: int) → bool

Skips nbytes bytes of the ByteReader instance.

Parameters:: nbytes – the number of bytes to skip

skip_string_utf16() → bool

Skips a NUL-terminated UTF-16 string in the ByteReader instance, advancing the current position to the byte after the string.

No input checking for valid UTF-16 is done.

This function will fail if no NUL-terminator was found in in the data.

skip_string_utf32() → bool

Skips a NUL-terminated UTF-32 string in the ByteReader instance, advancing the current position to the byte after the string.

No input checking for valid UTF-32 is done.

This function will fail if no NUL-terminator was found in in the data.

skip_string_utf8() → bool

Skips a NUL-terminated string in the ByteReader instance, advancing the current position to the byte after the string. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done.

This function will fail if no NUL-terminator was found in in the data.

Fields

class ByteReader

byte: Current byte position

data: Data from which the bit reader will read

size: Size of data in bytes