Mutibs#

The Mutibs class (pronounced ‘mew-tibs’) is a mutable container for binary data.

It’s mostly a superset of the Tibs class, and adds methods that can change the contained data in-place.

Unlike Tibs, a Mutibs instance is not hashable, and so can’t be used as a dictionary key or in a set. It can also be less efficient to use a Mutibs if an immutable Tibs would work equally well, but the differences are likely to be small in most use-cases.

Methods on Tibs which produce an iterator over the data, such as Tibs.find_all_iter() and Tibs.chunks_iter(), as well as iterating over the instance directly, are not available for Mutibs. This is because the underlying data could change while the iterator is active. To use these methods call Mutibs.to_tibs() first to create an immutable copy.

The special methods include those from Tibs, plus the following which mutate the instance:

[] : Setting slices, e.g. m[4:16] = [1, 0]
+=: Concatenation in-place, e.g. m += '0b1'
*=: Concatenation of self in-place, e.g. m *= 6
<<=: Left bit shift in-place, e.g. m <<= 3
>>=: Right bit shift in-place, e.g. m >>= 3
&=: Bit-wise AND in-place
|=: Bit-wise OR in-place
^=: Bit-wise XOR in-place

class Mutibs(auto=None)#

A mutable container of binary data.

To construct, use a builder ‘from’ method:

Mutibs.from_bin(s) - Create from a binary string, optionally starting with ‘0b’.
Mutibs.from_oct(s) - Create from an octal string, optionally starting with ‘0o’.
Mutibs.from_hex(s) - Create from a hex string, optionally starting with ‘0x’.
Mutibs.from_u(u, length, [byte_order]) - Create from an unsigned int to a given length.
Mutibs.from_i(i, length, [byte_order]) - Create from a signed int to a given length.
Mutibs.from_f(f, length, [byte_order]) - Create from an IEEE float to a 16, 32 or 64 bit length.
Mutibs.from_bytes(b) - Create directly from a bytes, bytearray or memoryview object.
Mutibs.from_string(s) - Use a formatted string.
Mutibs.from_bools(iterable) - Convert each element in iterable to a bool.
Mutibs.from_zeros(length) - Initialise with length 0 bits.
Mutibs.from_ones(length) - Initialise with length 1 bits.
Mutibs.from_random(length, [secure, seed]) - Initialise with length randomly set bits.
Mutibs.from_joined(iterable) - Concatenate an iterable of objects.

Using Mutibs(auto) will try to delegate to from_string, from_bytes or from_bools.

all()#

Return True if all bits are equal to 1, otherwise return False.

Returns:: True if all bits are 1, otherwise False.

>>> Mutibs('0b1111').all()
True
>>> Mutibs('0b1011').all()
False

any()#

Return True if any bits are equal to 1, otherwise return False.

Returns:: True if any bits are 1, otherwise False.

>>> Mutibs('0b0000').any()
False
>>> Mutibs('0b1000').any()
True

append(bit)#

Append a single bit to the current Mutibs in-place.

Parameters:: bit (bool | int) – Either 0, 1, True or False to append.
Returns:: None

>>> a = Mutibs()
>>> a.append(True)
>>> a
Mutibs('0b1')

as_raw_data()#

Return the raw bytes and offset information, leaving the Mutibs empty.

This returns the underlying byte data using a move rather than a copy, and can contain leading and trailing bits that are not considered part of the object’s value. Usually using to_bytes() is what you really need.

The way that the data is stored is not considered part of the public interface and so the output of this method may change between point releases, and even during the running of a program.

See also to_raw_data() which copies the byte data instead of moving it.

Returns:: A tuple of the raw bytes, the bit offset and the bit length.

raw_bytes, offset, length = t.as_raw_data()
assert t == []

as_tibs()#

Create and return a Tibs instance by moving the Mutibs data.

The data is moved to the new Tibs, so the Mutibs will be empty after the operation. This is more efficient than to_tibs() if you no longer need the Mutibs.

It will try to reclaim any excess memory capacity that the Mutibs may have had.

Returns:: A Tibs instance with the same bit data.

>>> a = Mutibs('0b10110')
>>> b = a.as_tibs()
>>> a
Mutibs()
>>> b
Tibs('0b10110')

byte_swap(byte_length=None, start=None, end=None)#

Swap byte order in-place.

The selected slice will be byte-swapped. It must be a multiple of byte_length long.

Parameters:

byte_length (int | None) – An int giving the number of bytes in each swap, or None (the default) to do a single reverse over the selected slice.
start (int | None) – Start of slice to byte-swap. Defaults to 0.
end (int | None) – End of slice to byte-swap. Defaults to len(self).

Returns:

None

>>> a = Mutibs('0x12345678')
>>> a.byte_swap(2)
>>> a
Mutibs('0x34127856')

byte_swapped(byte_length=None, start=None, end=None)#

Return a new instance with the byte order swapped.

The selected slice will be byte-swapped. It must be a multiple of byte_length long.

Parameters:

byte_length (int | None) – An int giving the number of bytes in each swap, or None (the default) to do a single reverse over the selected slice.
start (int | None) – Start of slice to byte-swap. Defaults to 0.
end (int | None) – End of slice to byte-swap. Defaults to len(self).

Returns:

Mutibs

>>> a = Mutibs('0x12345678')
>>> b = a.byte_swapped(2)
>>> b
Mutibs('0x34127856')

capacity()#

Return the number of bits the Mutibs can hold without reallocating memory.

The capacity is always equal to or greater than the current length of the Mutibs. If the length ever exceeds the capacity then memory will have to be reallocated, and the capacity will increase.

It can be helpful as a performance optimization to reserve enough capacity before constructing a large Mutibs incrementally. See also reserve().

Returns:: The current capacity in bits.

>>> m = Mutibs()
>>> m.capacity() >= len(m)
True

chunks(chunk_size, count=None)#

Return a list of Mutibs by cutting into chunks.

Parameters:

chunk_size (int) – The size in bits of the chunks to create.
count (int | None) – If specified, at most count items are created. Default is to cut as many times as possible.

Returns:

A list of Mutibs chunks.

>>> Mutibs('0b110011').chunks(2)
[Mutibs('0b11'), Mutibs('0b00'), Mutibs('0b11')]

clear()#

Clear all bits, making the Mutibs empty.

This doesn’t change the allocated capacity, so won’t free up any memory.

Returns:: None.

>>> m = Mutibs('0b1011')
>>> m.clear()
>>> m
Mutibs()

count(value)#

Counts the total number of occurrences of a bit pattern.

Parameters:: value (object) – Either something that can be converted to a Tibs, or a single bit (one of 0, 1, False or True).
Returns:: The number of times the bit pattern is found.

>>> Mutibs('0xef').count(1)
7
>>> Mutibs('0xff00ff').count([1, 1, 1])
12

decode(b, /)#

Create a Mutibs by decoding bytes created via encode().

Parameters:: b (bytes | bytearray) – The encoded bytes to decode.
Returns:: A new Mutibs.
Raises:: ValueError – for badly formed, truncated or extended input bytes.

>>> Mutibs.decode(Mutibs('0b101').encode())
Mutibs('0b101')

encode()#

Encode the Mutibs as a bytes instance.

The bytes instance can be used to recreate the Mutibs exactly with decode().

Parameters:: codec (Codec) – The codec to use. Defaults to Codec.Auto.
Returns:: The encoded bytes.

>>> Mutibs.decode(Mutibs('0b101').encode())
Mutibs('0b101')

ends_with(suffix)#

Return whether the current Mutibs ends with suffix.

Parameters:: suffix (Tibs) – The bits to search for.
Returns:: True if the Mutibs ends with the suffix, otherwise False.

>>> Mutibs('0b101100').ends_with('0b100')
True
>>> Mutibs('0b101100').ends_with('0b101')
False

extend(bs, /)#

Extend the current Mutibs in-place.

Parameters:: bs (Tibs) – The bits to extend with.
Returns:: None

>>> a = Mutibs('0x0f')
>>> a.extend('0x0a')
>>> a
Mutibs('0x0f0a')

extend_left(bs, /)#

Extend the current Mutibs in-place from the start.

This is broadly equivalent to self = bs + self. Note that this method is inherently slower than extend() and should be avoided in performance critical code. See also from_joined().

Parameters:: bs (Tibs) – The bits to prepend to the current Mutibs.
Returns:: None

>>> a = Mutibs('0x0f')
>>> a.extend_left('0x0a')
>>> a
Mutibs('0x0a0f')

field(a, b)#

Extract a mutable field using inclusive MSB0 bit labels.

a and b must be zero or positive bit labels. The two endpoints are inclusive and may be provided in either order. This is equivalent to self.msb0.field(a, b).

Parameters:

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

Returns:

A new MutableView.

find(needle, start=None, end=None, byte_aligned=False)#

Find first occurrence of a bit sequence.

Returns the bit position if found, or None if not found.

Parameters:

needle (Tibs) – The Tibs to find.
start (int | None) – The starting bit position. Defaults to 0.
end (int | None) – The end position. Defaults to len(self).
byte_aligned (bool) – If True, the bits will only be found on byte boundaries.

Returns:

The bit position if found, or None if not found.

Raises:

ValueError – if needle is empty, or if the slice parameters are invalid.

>>> Mutibs('0xc3e').find('0b1111')
6

find_all(needle, start=None, end=None, byte_aligned=False)#

Find all occurrences of a bit sequence.

Parameters:

needle (Tibs) – The Tibs to find.
start (int | None) – The starting bit position. Defaults to 0.
end (int | None) – The end position. Defaults to len(self).
byte_aligned (bool) – If True, the bits will only be found on byte boundaries.

Returns:

A list of bit positions.

Raises:

ValueError – if needle is empty, or if the slice parameters are invalid.

All occurrences of needle are found, even if they overlap.

>>> Mutibs('0xc3e').find_all('0b1111')
[6]

from_bin(s, /)#

Create a new instance from a binary string.

Parameters:: s (str) – A string of 0 and 1 s, optionally preceded with 0b and optionally containing underscores.
Returns:: A newly constructed Mutibs.

a = Mutibs.from_bin("0000_1111_0101")

from_bools(iterable, /)#

Create a new instance from an iterable by converting each element to a bool.

Parameters:: iterable (Iterable) – The iterable to convert to a Mutibs.
Returns:: A newly constructed Mutibs.

a = Mutibs.from_bools([False, 0, 1, "Steven"])  # binary 0011

from_bytes(data, /, offset=None, length=None)#

Create a new instance from a bytes object.

Parameters:

data (bytes | bytearray | memoryview) – The bytes, bytearray or memoryview object to convert to a Mutibs.
offset (int | None) – The bit offset from the start. Defaults to zero.
length (int | None) – The bit length to use. Defaults to the whole of the data.

Returns:

A newly constructed Mutibs.

a = Mutibs.from_bytes(b"some_bytes_maybe_from_a_file")

from_f(f, /, length, byte_order=None)#

Create a new instance from a floating point number.

Parameters:

f (float) – A floating point value.
length (int) – The bit length to create. Must be 16, 32 or 64.
byte_order (Endianness) – The byte order used to store the float. Defaults to Endianness.Unspecified.

Returns:

A newly constructed Mutibs.

>>> Mutibs.from_f(1.5, length=32)
Mutibs('0x3fc00000')

from_hex(s, /)#

Create a new instance from a hexadecimal string.

Equivalent to using the hex property.

Parameters:: s (str) – A string of hexadecimal digits, optionally preceded with 0x and optionally containing underscores.
Returns:: A newly constructed Mutibs.

>>> Mutibs.from_hex("0f")
Mutibs('0x0f')

from_i(i, /, length, byte_order=None)#

Create a new instance from a signed integer.

Parameters:

i (int) – A signed integer.
length (int) – The bit length to create. Can be up to 128.
byte_order (Endianness) – The byte order used to store the integer. Defaults to Endianness.Unspecified.

Returns:

A newly constructed Mutibs.

Raises:

ValueError – if the integer doesn’t fit in the length given.

>>> Mutibs.from_i(-2, length=4)
Mutibs('0xe')

from_joined(iterable, /)#

Create a new instance by concatenating a sequence of Mutibs objects.

This method concatenates a sequence of Mutibs objects into a single Mutibs object.

Parameters:: iterable (Iterable) – An iterable to concatenate. Items can be anything that can be promoted to a Mutibs.
Returns:: A newly constructed Mutibs.

a = Mutibs.from_joined(['0x01', [1, 0], b'some_bytes'])

from_oct(s, /)#

Create a new instance from an octal string.

Parameters:: s (str) – A string of octal digits, optionally preceded with 0o and optionally containing underscores.
Returns:: A newly constructed Mutibs.

>>> Mutibs.from_oct("17")
Mutibs('0b001111')

from_ones(length, /)#

Create a new instance with all bits set to one.

Parameters:: length (int) – The number of bits to set.
Returns:: A Mutibs object with all bits set to one.

>>> Mutibs.from_ones(5)
Mutibs('0b11111')

from_random(length, /, secure=False, seed=None)#

Create a new instance with all bits randomly set.

Parameters:

length (int) – The number of bits to set. Must be positive.
secure (bool) – If True, use the OS’s cryptographically secure generator. Default is False.
seed (bytes | bytearray | None) – A bytes or bytearray to use as an optional seed, only if secure is False.

Returns:

A newly constructed Mutibs with random data.

The ‘secure’ option uses the OS’s random data source, so will be slower and could potentially fail.

a = Mutibs.from_random(1000000)  # A million random bits
b = Mutibs.from_random(100, seed=b'a_seed')

from_string(s, /)#

Create a new instance from a formatted string.

This method initializes a new instance of Mutibs using a formatted string.

Parameters:: s (str) – The formatted string to convert. This can begin with ‘0b’, ‘0o’ or ‘0x’ to indicate binary, octal or hexadecimal, and commas can be used to separate items.
Returns:: A newly constructed Mutibs.

a = Mutibs.from_string("0xff01")
b = Mutibs.from_string("0b1")

The __init__ method for Mutibs can also redirect to from_string:

a = Mutibs("0xff01")

from_u(u, /, length, byte_order=None)#

Create a new instance from an unsigned integer.

Parameters:

u (int) – An unsigned integer.
length (int) – The bit length to create. Can be up to 128.
byte_order (Endianness) – The byte order used to store the integer. Defaults to Endianness.Unspecified.

Returns:

A newly constructed Mutibs.

Raises:

ValueError – if the integer doesn’t fit in the length given.

>>> Mutibs.from_u(15, length=8)
Mutibs('0x0f')

from_value(dtype, value, /)#

Create a new instance by encoding one value with a dtype.

Parameters:

dtype (Dtype | str) – The value encoding to use.
value (object) – The value to encode.

Returns:

A newly constructed Mutibs.

>>> Mutibs.from_value("u8", 15)
Mutibs('0x0f')

from_values(dtype, iterable, /)#

Create a new instance by encoding and concatenating values with a dtype.

Parameters:

dtype (Dtype | str) – The value encoding to use for each item.
iterable (Iterable) – The values to encode.

Returns:

A newly constructed Mutibs.

>>> Mutibs.from_values("u8", [1, 2, 3])
Mutibs('0x010203')

from_zeros(length, /)#

Create a new instance with all bits set to zero.

Parameters:: length (int) – The number of bits to set.
Returns:: A Mutibs object with all bits set to zero.

a = Mutibs.from_zeros(500)  # 500 zero bits

insert(pos, bs, /)#

Insert bits at position pos.

Clips to start or end if insert position is out of range.

Parameters:

pos (int) – The bit position to insert at.
bs (Tibs) – The bits to insert.

Returns:

None

>>> a = Mutibs('0b1011')
>>> a.insert(2, '0b00')
>>> a
Mutibs('0b100011')

inserted(pos, bs, /)#

Insert bits at position pos and return a new Mutibs.

This is the non-inplace version of insert().

Parameters:

pos (int) – The bit position to insert at. Clips to the start or end if out of range.
bs (Tibs) – The bits to insert.

Returns:

A new Mutibs.

>>> Mutibs('0b1011').inserted(2, '0b00')
Mutibs('0b100011')

invert(pos=None)#

Invert one or many bits in place.

Parameters:: pos (int | Iterable[int] | None) – Either a single bit position or an iterable of bit positions.
Returns:: None
Raises:: IndexError – if pos < -len(self) or pos >= len(self).

>>> a = Mutibs('0b10111')
>>> a.invert(1)
>>> a
Mutibs('0b11111')
>>> a.invert([0, 2])
>>> a
Mutibs('0b01011')
>>> a.invert()
>>> a
Mutibs('0b10100')

inverted(pos=None)#

Return a new Mutibs with selected bits inverted.

This is the non-inplace version of invert().

Parameters:: pos (int | Iterable[int] | None) – Either a single bit position, an iterable of bit positions, or None to invert every bit. Defaults to None.
Returns:: A new Mutibs.
Raises:: IndexError – if pos < -len(self) or pos >= len(self).

>>> Mutibs('0b10110').inverted([0, 2])
Mutibs('0b00010')

pop()#

Remove and return the final bit.

Returns:: bool
Raises:: IndexError – if the Mutibs is empty.

>>> a = Mutibs('0b101')
>>> a.pop()
True
>>> a
Mutibs('0b10')

replace(old, new, start=None, end=None, count=None, byte_aligned=False)#

Search and replace in-place.

Parameters:

old (Tibs) – The bits to search for.
new (Tibs) – The bits to replace with.
start (int | None) – The starting bit position. Defaults to 0.
end (int | None) – The end position. Defaults to len(self).
count (int | None) – If present, the maximum number of replacements to make.
byte_aligned (bool) – If True, the bits will only be found on byte boundaries.

Returns:

The number of replacements made.

>>> m = Mutibs('0b00010010')
>>> m.replace([0, 1], [1, 1, 1])
2
>>> m
Mutibs('0b0011101110')

replaced(old, new, start=None, end=None, count=None, byte_aligned=False)#

Search and replace and return a new Mutibs.

This is the non-inplace version of replace().

Parameters:

old (Tibs) – The bits to search for.
new (Tibs) – The bits to replace with.
start (int | None) – The starting bit position. Defaults to 0.
end (int | None) – The end position. Defaults to len(self).
count (int | None) – If present, the maximum number of replacements to make.
byte_aligned (bool) – If True, the bits will only be found on byte boundaries.

Returns:

A new Mutibs.

Raises:

ValueError – if old is empty, count is negative or the slice parameters are invalid.

>>> Mutibs('0b00010010').replaced([0, 1], [1, 1, 1])
Mutibs('0b0011101110')

reserve(additional)#

Reserve memory for at least additional more bits to be appended to the Mutibs.

This can be helpful as a performance optimization to avoid multiple memory reallocations when constructing a large Mutibs incrementally. If enough memory is already reserved then this method will have no effect. See also capacity().

Parameters:: additional (int) – The number of bits that can be appended without any further memory reallocations.
Returns:: None.

m = Mutibs()
m.reserve(1000)

reverse()#

Reverse bits in-place.

Returns:: None

>>> a = Mutibs('0b10110')
>>> a.reverse()
>>> a
Mutibs('0b01101')

reversed()#

Return a new instance with the bits reversed.

Returns:: Mutibs

>>> a = Mutibs('0b00011')
>>> a.reversed()
Mutibs('0b11000')

rfind(needle, start=None, end=None, byte_aligned=False)#

Find last occurrence of a bit sequence.

Returns the bit position if found, or None if not found.

Parameters:

needle (Tibs) – The bits to find.
start (int | None) – The starting bit position. Defaults to 0.
end (int | None) – The end position. Defaults to len(self).
byte_aligned (bool) – If True, the bits will only be found on byte boundaries.

Returns:

The bit position if found, or None if not found.

Raises:

ValueError – if needle is empty, or if the slice parameters are invalid.

>>> Mutibs('0b10111011').rfind('0b11')
6

rotate_left(n, start=None, end=None)#

Rotates bit pattern to the left in-place.

Parameters:

n (int) – The number of bits to rotate by.
start (int | None) – Start of slice to rotate. Defaults to 0.
end (int | None) – End of slice to rotate. Defaults to len(self).

Returns:

None

Raises:

ValueError – if n < 0.

>>> a = Mutibs('0b10110')
>>> a.rotate_left(2)
>>> a
Mutibs('0b11010')

rotate_right(n, start=None, end=None)#

Rotates bit pattern to the right in-place.

Parameters:

n (int) – The number of bits to rotate by.
start (int | None) – Start of slice to rotate. Defaults to 0.
end (int | None) – End of slice to rotate. Defaults to len(self).

Returns:

None

Raises:

ValueError – if n < 0.

>>> a = Mutibs('0b10110')
>>> a.rotate_right(1)
>>> a
Mutibs('0b01011')

rotated_left(n, start=None, end=None)#

Return a new Mutibs with the bits rotated to the left.

This is the non-inplace version of rotate_left().

Parameters:

n (int) – The number of bits to rotate by.
start (int | None) – Start of slice to rotate. Defaults to 0.
end (int | None) – End of slice to rotate. Defaults to len(self).

Returns:

A new Mutibs.

Raises:

ValueError – if n < 0.

>>> Mutibs('0b10110').rotated_left(2)
Mutibs('0b11010')

rotated_right(n, start=None, end=None)#

Return a new Mutibs with the bits rotated to the right.

This is the non-inplace version of rotate_right().

Parameters:

n (int) – The number of bits to rotate by.
start (int | None) – Start of slice to rotate. Defaults to 0.
end (int | None) – End of slice to rotate. Defaults to len(self).

Returns:

A new Mutibs.

Raises:

ValueError – if n < 0.

>>> Mutibs('0b10110').rotated_right(1)
Mutibs('0b01011')

set(pos)#

Set one or many bits set to 1.

Parameters:: pos (int | Iterable[int]) – Either a single bit position or an iterable of bit positions.
Returns:: None
Raises:: IndexError – if pos < -len(self) or pos >= len(self).