View and MutableView#

Views wrap bit data with interpretation settings such as byte order and bit order. They do not change the meaning of normal Tibs or Mutibs indexing; they only affect conversions such as integer, float, bytes and labelled field access.

See Views in the manual for more details.

View#

class View#

A view of a Tibs with different interpretation settings.

A View does not change the underlying bits. It records how operations such as integer conversion, byte conversion and field extraction should interpret those bits.

Views are usually created from Tibs instances using the le, be, lsb0, msb0 or view() helpers.

Passing a Mutibs to the direct View constructor stores a Tibs snapshot. Later changes to the original Mutibs are not reflected in the view. Use MutableView for a live mutable view.

>>> t = Tibs('0x0100')
>>> t.le.u
1
>>> t.lsb0.hex
'8000'

field(a, b)#

Extract a field using inclusive bit labels.

This is intended for specifications that describe fields using inclusive bit labels such as 31:26. a and b must be zero or positive bit labels. The endpoints may be provided in either order.

For an LSB0 view, labels are interpreted within each byte with bit 0 at the least significant bit. For an MSB0 view, labels match normal Python slice positions.

Labels are selected in ascending order after endpoint normalization. The returned view has BitOrder.Msb0 because the selected bits have been materialized. The current byte order is kept for whole-byte fields and dropped for non-whole-byte fields.

Parameters:

a (int) – One non-negative inclusive field endpoint.
b (int) – The other non-negative inclusive field endpoint.

Returns:

A new View containing the field.

>>> t = Tibs('0x88040410')
>>> t.lsb0.field(31, 26).u
8

from_indices()#

Create a view by materializing selected source bit positions.

indices may be a range or any iterable of integers. It maps each viewed bit to a physical bit position in the source. Passing a Mutibs source stores an immutable snapshot.

This is a low-level reconstruction API. Use field() for normal specification-labelled fields.

>>> View.from_indices(Tibs('0xf0'), range(0, 4)).bin
'1111'
>>> View.from_indices(Tibs('0xf0'), [7, 6, 5, 4]).bin
'0000'

to_bin()#

Return the viewed bits as a binary string.

Returns:: The binary representation as a string.

to_bytes()#

Return the viewed bits as bytes.

The viewed length must be a whole number of bytes.

Returns:: A bytes value.

to_f()#

Interpret the viewed bits as an IEEE floating point value.

The viewed length must be 16, 32 or 64 bits.

Returns:: The floating point value.

to_hex()#

Return the viewed bits as a hexadecimal string.

Returns:: The hexadecimal representation as a string.

>>> Tibs('0x0100').le.to_hex()
'0001'

to_i()#

Interpret the viewed bits as a signed integer.

Returns:: The signed integer value.

to_mutibs()#

Materialize the view as a new Mutibs.

Returns:: A Mutibs containing the viewed bits.

to_oct()#

Return the viewed bits as an octal string.

Returns:: The octal representation as a string.

to_tibs()#

Materialize the view as a new Tibs.

Returns:: A Tibs containing the viewed bits.

to_u()#

Interpret the viewed bits as an unsigned integer.

Returns:: The unsigned integer value.

>>> Tibs('0x0100').le.to_u()
1

view(byte_order=None, bit_order=None)#

Return a view with updated interpretation settings.

Any setting left as None keeps its current value.

Byte-oriented views must have a whole-byte length. This applies when using little-endian or big-endian byte order, or when using BitOrder.Lsb0.

Parameters:

byte_order (Endianness) – The byte order to use, or None to keep the current byte order.
bit_order (BitOrder) – The bit order to use, or None to keep the current bit order.

Returns:

A new View.

>>> Tibs('0x0100').view(byte_order=Endianness.Little).u
1

be#

Return a big-endian byte-order view.

Equivalent to view(byte_order=Endianness.Big).

The view length must be a whole number of bytes.

bin#

Return the viewed bits as a binary string.

Equivalent to using to_bin().

bit_order#: Return the bit-order interpretation setting for this view.

byte_order#: Return the byte-order interpretation setting for this view.

bytes#

Return the viewed bits as bytes.

Equivalent to using to_bytes().

f#

Interpret the viewed bits as an IEEE floating point value.

Equivalent to using to_f().

hex#

Return the viewed bits as a hexadecimal string.

Equivalent to using to_hex().

i#

Interpret the viewed bits as a signed integer.

Equivalent to using to_i().

le#

Return a little-endian byte-order view.

Equivalent to view(byte_order=Endianness.Little).

The view length must be a whole number of bytes.

lsb0#

Return an LSB0 bit-order view.

BitOrder.Lsb0 means that field labels are counted from the least significant bit of each byte. The view length must be a whole number of bytes.

Equivalent to view(bit_order=BitOrder.Lsb0).

msb0#

Return an MSB0 bit-order view.

BitOrder.Msb0 means that field labels are counted from the most significant bit of each byte. This is the default bit order.

Equivalent to view(bit_order=BitOrder.Msb0).

oct#

Return the viewed bits as an octal string.

Equivalent to using to_oct().

u#

Interpret the viewed bits as an unsigned integer.

Equivalent to using to_u().

MutableView#

class MutableView#

A live mutable view of a Mutibs with different interpretation settings.

MutableView records how operations such as integer conversion, byte conversion and field extraction should interpret the source bits. Unlike View, it keeps a live reference to the source Mutibs.

Assigning through u, i or f mutates the source Mutibs without changing its length.

field(a, b)#

Extract a field using inclusive bit labels.

a and b must be zero or positive bit labels. The two endpoints are inclusive and may be provided in either order. The returned MutableView is a live view onto the selected source bits.

from_indices()#

Create a live mutable view from source bit positions.

indices may be a range or any iterable of integers. It maps each viewed bit to a physical bit position in the source Mutibs.

This is a low-level reconstruction API. Use field() for normal specification-labelled fields.

>>> m = Mutibs('0x00')
>>> view = MutableView.from_indices(m, range(0, 8, 2))
>>> view.bin = '1111'
>>> m.bin
'10101010'

to_bin()#: Return the viewed bits as a binary string.

to_bytes()#: Return the viewed bits as bytes.

to_f()#: Interpret the viewed bits as an IEEE floating point value.

to_hex()#: Return the viewed bits as a hexadecimal string.

to_i()#: Interpret the viewed bits as a signed integer.

to_mutibs()#: Materialize the current view as a new Mutibs.

to_oct()#: Return the viewed bits as an octal string.

to_tibs()#: Materialize the current view as a new Tibs.

to_u()#: Interpret the viewed bits as an unsigned integer.

view(byte_order=None, bit_order=None)#

Return a mutable view with updated interpretation settings.

Any setting left as None keeps its current value.

write_bin(s, /)#: Write the viewed bits from a binary string without changing the view length.

write_bytes(data, /)#: Write the viewed bits from a bytes-like object without changing the view length.

write_f(f, /)#: Write the viewed bits from a floating point number without changing the source length.

write_hex(s, /)#: Write the viewed bits from a hexadecimal string without changing the view length.

write_i(i, /)#: Write the viewed bits from a signed integer without changing the source length.

write_oct(s, /)#: Write the viewed bits from an octal string without changing the view length.

write_u(u, /)#: Write the viewed bits from an unsigned integer without changing the source length.

be#: Return a big-endian byte-order mutable view.

bin#: Return the viewed bits as a binary string.

bit_order#: Return the bit-order interpretation setting for this mutable view.

byte_order#: Return the byte-order interpretation setting for this mutable view.

bytes#: Return the viewed bits as bytes.

f#: Interpret the viewed bits as an IEEE floating point value.

hex#: Return the viewed bits as a hexadecimal string.

i#: Interpret the viewed bits as a signed integer.

le#: Return a little-endian byte-order mutable view.

lsb0#: Return an LSB0 bit-order mutable view.

msb0#: Return an MSB0 bit-order mutable view.

oct#: Return the viewed bits as an octal string.

u#: Interpret the viewed bits as an unsigned integer.