Array¶

The Array class is used as a container for contiguously allocated Bits objects with the same Dtype.

Array instances act very like an ordinary Python array, but with each element being a fixed-length dtype. They are mutable, so values can be changed after creation.

class Array(dtype: str | Dtype, iterable: Iterable | None = None)¶

An Array whose elements are all a single data type.

The Array data is stored compactly as a MutableBits object and the Array behaves very like a list of items of the given format.

If the data length is not a multiple of the dtype length then the Array will have trailing_bits which will prevent some methods from appending to the Array.

To construct, use a builder ‘from’ method:

Array.from_iterable(dtype, iterable) - Create and initialise from an iterable.
Array.from_bits(dtype, bits) - Create with data from a Bits or MutableBits object.
Array.from_bytes(dtype, bytes_data) - Create with data from a bytes -like object.
Array.from_zeros(dtype, n) - Initialise with enough zero bits for n elements.

Using the constructor Array(dtype, iterable) is an alias for Array.from_iterable(dtype, iterable), but this does not accept either Bits or bytes objects as the iterable to avoid confusion.

Other methods:

append(item): Append a single item to the end of the Array.
as_type(dtype): Creates a new Array with a new data type, initialized from the current Array.
byte_swap(): Change byte endianness of all items.
count(value): Count the number of occurrences of a value.
equals(other): Comparison method between Arrays.
extend(iterable): Append new items to the end of the Array from an iterable.
insert(index, item): Insert an item at a given position.
pop([index]): Remove and return an item. Default is the last item.
pp([dtype1, dtype2, groups, width, show_offset, stream]): Pretty print the Array.
reverse(): Reverse the order of all items.
to_bits(): Return a copy of the Array data as an immutable Bits.
to_bytes(): Return Array data as bytes object, padding with zero bits at the end if needed.
to_list(): Return Array items as a list of values.

Special methods:

Also available are the operators [], ==, !=, +, *, <<, >>, &, |, ^, plus the mutating operators []=, +=, *=, <<=, >>=, &=, |=, ^=.

Properties:

bits: The binary data of the Array as a MutableBits object.
dtype: The data type of the elements in the Array.
item_size: The length in bits of a single item. Read only.
trailing_bits: If the data length is not a multiple of the dtype length, this Bits gives the leftovers at the end of the data.

append(x, /)¶

Append a single item to the end of the Array.

Parameters:: x (Union[float, str, int, bytes, bool, Bits, MutableBits]) – The item to append.
Return type:: Array
Returns:: The modified Array.

as_type(dtype, /)¶

Creates and returns a new Array instance with a specified data type, initialized with the current Array’s elements.

This method allows for the conversion of the Array’s elements to a different data type, specified by the dtype parameter. The conversion process respects the original values of the elements, adapting them to the new data type format. This can be useful for changing the representation of data within the Array, for example, from integers to floating-point numbers or vice versa.

Parameters:: dtype (str | Dtype) – The target data type for the new Array.
Return type:: Array
Returns:: A new Array instance with the specified dtype, containing the elements of the current Array converted to the new data type.
Raises:: ValueError – If the specified dtype is not supported or cannot be applied to the elements of the current Array.

>>> original_array = Array('i5', [1, 2, 3])
>>> float_array = original_array.as_type('f16')
>>> print(float_array)
Array('f16', [1.0, 2.0, 3.0])

byte_swap()¶

Change the endianness in-place of all items in the Array.

Return type:: Array
Returns:: The modified Array.
Raises:: ValueError – If the Array format is not a whole number of bytes.

count(value, /)¶

Return count of Array items that equal value.

Parameters:: value (Union[float, str, int, bytes, bool, Bits, MutableBits]) – The quantity to compare each Array element to. Type should be appropriate for the Array format.
Return type:: int

For floating point types using a value of float('nan') will count the number of elements that are NaN.

equals(other, /)¶

Return True if the data type and all Array items are equal to another Array.

This method should be used to test the equality of two Arrays. Normally types will provide an == operator to do this task, but for Arrays the == operator is instead used for element-wise comparison and will return a new Array of bools.

Parameters:: other (Any) – The other Array to compare with.
Return type:: bool
Returns:: True if the Arrays are equal, False otherwise.

extend(iterable, /)¶

Append new items to the end of the Array from an iterable.

This method allows you to extend the Array by appending elements from another iterable. The iterable can be another Array, bytes, bytearray, Bits, or any other iterable containing elements of a compatible type.

Parameters:: iterable (Union[Array, bytes, bytearray, Bits, Iterable[Any]]) – The iterable containing elements to append to the Array.
Return type:: Array
Returns:: The extended Array.

classmethod from_bits(dtype, bits)¶

Return type:: Array

classmethod from_bytes(dtype, bytes_data)¶

Create a new Array from a data type and a bytes object.

Parameters:

dtype (str | Dtype) – The data type of the elements in the Array.
bytes_data (bytes | bytearray | memoryview) – The bytes object to convert to a Bits.

Return type:

Array

a = Array.from_bytes('u8', b"some_bytes_maybe_from_a_file")

classmethod from_iterable(dtype, iterable)¶

Return type:: Array

classmethod from_zeros(dtype, n)¶

Return type:: Array

info()¶

Return a descriptive string with information about the Array.

Note that the output is designed to be helpful to users and is not considered part of the API. You should not use the output programmatically as it may change even between point versions.

Return type:: str

insert(pos, x, /)¶

Insert a new element into the Array at position pos.

Parameters:

pos (int) – The position to insert the item.
x (Union[float, str, int, bytes, bool, Bits, MutableBits]) – The item to insert.

Return type:

Array

Returns:

The modified Array.

pop(pos=-1, /)¶

Return and remove an element of the Array.

Default is to return and remove the final element.

Parameters:: pos (int) – The position of the item to remove. Default is -1 (last item).
Return type:: Union[float, str, int, bytes, bool, Bits, MutableBits]
Returns:: The removed item.

pp(dtype1=None, dtype2=None, groups=None, width=80, show_offset=True, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)¶

Pretty-print the Array contents.

This method provides a formatted output of the Array’s contents, allowing for easy inspection of the data. The output can be customized with various parameters to control the format, width, and display options.

Parameters:

dtype1 (str | Dtype | None) – Data type to display. Defaults to the current Array dtype.
dtype2 (str | Dtype | None) – Data type for addition display data.
groups (int | None) – How many groups of bits to display on each line. This overrides any value given for width.
width (int) – Maximum width of printed lines in characters. Defaults to 80, but ignored if groups parameter is set. A single group will always be printed per line even if it exceeds the max width.
show_offset (bool) – If True, shows the element offset in the first column of each line.
stream (TextIO) – A TextIO object with a write() method. Defaults to sys.stdout.

Return type:

None

Returns:

None

reverse()¶

Reverse the order of all items in the Array in place.

Raises:: ValueError – If the Array’s data length is not a multiple of the item size in bits.
Return type:: Array
Returns:: The Array object with its items reversed.

>>> a = Array('i14', [-3, 0, 100])
>>> a.reverse()
Array('i14', [100, 0, -3])

to_bits()¶

Return as a Bits object. This is an immutable copy of the current Array data.

Return type:: Bits

to_bytes()¶

Return the Array data as a bytes object, padding with zero bits if needed.

Up to seven zero bits will be added at the end to byte align.

Return type:: bytes

to_list(dtype=None)¶

Interpret the Array as a list of elements of a given dtype, defaulting to the Array’s current dtype.

>>> a = Array('i3', [2, 1, -2, 0])
>>> a.to_list()
[2, 1, -2, 0]
>>> a.to_list('bin3')
['010', '001', '110', '000']
>>> a.to_list('u5, bool')
[(8, True), (24, False)]

Return type:: list[Union[float, str, int, bytes, bool, Bits, MutableBits]]

property bits: MutableBits¶

Property that provides access to the Array data as a MutableBits.

Note that this is the actual data of the Array and any changes made to it will affect the Array. Use the to_bits method if you need a copy of the data instead.

property dtype: Dtype¶: The data type of the elements in the Array.

property item_size: int¶: The length of a single item in bits. Read only.

property trailing_bits: Bits¶: The Bits at the end of the Array that don’t fit into a whole number of elements.