Bits¶
Bits
is the most basic class and is just a container of bits. It is immutable, so once created its value cannot change.
Bits(__auto, length: Optional[int], offset: Optional[int], **kwargs)
The first parameter (usually referred to as auto) can be many different types, including parsable strings, a file handle, a bytes or bytearray object, an integer or an iterable.
A single initialiser from kwargs can be used instead of auto, including bin
, hex
, oct
, bool
, uint
, int
, float
, bytes
and filename
.
Examples:
Bits('0xef')
Bits(float=-50.5, length=32)
Bits('uint10=99')
Bits(uint=99, length=10)
Methods¶
all
– Check if all specified bits are set to 1 or 0.any
– Check if any of specified bits are set to 1 or 0.copy
– Return a copy of the bitstring.count
– Count the number of bits set to 1 or 0.cut
– Create generator of constant sized chunks.endswith
– Return whether the bitstring ends with a sub-bitstring.find
– Find a sub-bitstring in the current bitstring.findall
– Find all occurrences of a sub-bitstring in the current bitstring.join
– Join bitstrings together using current bitstring.pp
– Pretty print the bitstring.rfind
– Seek backwards to find a sub-bitstring.split
– Create generator of chunks split by a delimiter.startswith
– Return whether the bitstring starts with a sub-bitstring.tobitarray
– Return bitstring as abitarray
object from the bitarray package.tobytes
– Return bitstring as bytes, padding if needed.tofile
– Write bitstring to file, padding if needed.unpack
– Interpret bits using format string.
Special methods¶
Also available are operators that will return a new bitstring (or check for equality):
[]
– Get an element or slice.+
– Concatenate with another bitstring.*
– Concatenate multiple copies of the current bitstring.~
– Invert every bit of the bitstring.<<
– Shift bits to the left.>>
– Shift bits to the right.&
– Bit-wise AND between two bitstrings.|
– Bit-wise OR between two bitstrings.^
– Bit-wise XOR between two bitstrings.
Properties¶
These read-only properties of the Bits
object are interpretations of the binary data and are calculated as required.
Many require the bitstring to be specific lengths.
bin
/b
– The bitstring as a binary string.bool
– For single bit bitstrings, interpret as True or False.bytes
– The bitstring as a bytes object.float
/floatbe
/f
– Interpret as a big-endian floating point number.floatle
– Interpret as a little-endian floating point number.floatne
– Interpret as a native-endian floating point number.float8_143
– Interpret as an 8 bit float with 1:4:3 format.float8_152
– Interpret as an 8 bit float with 1:5:2 format.bfloat
/bfloatbe
– Interpret as a big-endian bfloat floating point number.bfloatle
– Interpret as a little-endian bfloat floating point number.bfloatne
– Interpret as a native-endian bfloat floating point number.hex
/h
– The bitstring as a hexadecimal string.int
/i
– Interpret as a two’s complement signed integer.intbe
– Interpret as a big-endian signed integer.intle
– Interpret as a little-endian signed integer.intne
– Interpret as a native-endian signed integer.len
– Length of the bitstring in bits.oct
/o
– The bitstring as an octal string.se
– Interpret as a signed exponential-Golomb code.ue
– Interpret as an unsigned exponential-Golomb code.sie
– Interpret as a signed interleaved exponential-Golomb code.uie
– Interpret as an unsigned interleaved exponential-Golomb code.uint
/u
– Interpret as a two’s complement unsigned integer.uintbe
– Interpret as a big-endian unsigned integer.uintle
– Interpret as a little-endian unsigned integer.uintne
– Interpret as a native-endian unsigned integer.
BitArray¶
Bits
⟶ BitArray
BitArray
adds mutating methods to Bits
. The constructor is the same as for Bits
.
Additional methods¶
All of the methods listed above for the Bits
class are available, plus:
append
– Append a bitstring.byteswap
– Change byte endianness in-place.clear
– Remove all bits from the bitstring.insert
– Insert a bitstring.invert
– Flip bit(s) between one and zero.overwrite
– Overwrite a section with a new bitstring.prepend
– Prepend a bitstring.replace
– Replace occurrences of one bitstring with another.reverse
– Reverse bits in-place.rol
– Rotate bits to the left.ror
– Rotate bits to the right.set
– Set bit(s) to 1 or 0.
Additional special methods¶
The special methods available for the Bits
class are all available, plus some which will modify the bitstring:
[]
– Set an element or slice.del
– Delete an element or slice.+=
– Append bitstring to the current bitstring.*=
– Concatenate multiple copies of the current bitstring.<<=
– Shift bits in-place to the left.>>=
– Shift bits in-place to the right.&=
– In-place bit-wise AND between two bitstrings.|=
– In-place bit-wise OR between two bitstrings.^=
– In-place bit-wise XOR between two bitstrings.
BitArray
objects have the same properties as Bits
, except that they are all (with the exception of len
) writable as well as readable.
ConstBitStream¶
Bits
⟶ ConstBitStream
ConstBitStream
adds a bit position and methods to read and navigate in an immutable bitstream.
If you wish to use streaming methods on a large file without changing it then this is often the best class to use.
The constructor is the same as for Bits
/ BitArray
but with an optional current bit position.
ConstBitStream(auto, length: Optional[int], offset: Optional[int], pos: int = 0, **kwargs)
All of the methods, special methods and properties listed above for the Bits
class are available, plus:
Additional methods¶
bytealign
– Align to next byte boundary.peek
– Peek at and interpret next bits as a single item.peeklist
– Peek at and interpret next bits as a list of items.read
– Read and interpret next bits as a single item.readlist
– Read and interpret next bits as a list of items.readto
– Read up to and including next occurrence of a bitstring.
Additional properties¶
BitStream¶
Bits
⟶ BitArray / ConstBitStream
⟶ BitStream
BitStream
contains all of the ‘stream’ elements of ConstBitStream
and adds all of the mutating methods of BitArray
.
The constructor is the same as for ConstBitStream
.
It has all the methods, special methods and properties of the Bits
, BitArray
and ConstBitArray
classes.
It is the most general of the four classes, but it is usually best to choose the simplest class for your use case.
Array¶
A bitstring Array
is a contiguously allocated sequence of bitstrings of the same type.
It is similar to the array
type in the array module, except that it is far more flexible.
Array(fmt: str, initializer, trailing_bits)
The fmt can any single fixed-length token as described in Format tokens and Compact format strings.
The inititalizer will typically be an iterable such as a list, but can also be many other things including an open binary file, a bytes or bytearray object, another bitstring.Array
or an array.array
.
The trailing_bits typically isn’t used in construction, and specifies bits left over after interpreting the stored binary data according to the format fmt.
Both the format and the underlying bit data (stored as a BitArray
) can be freely modified after creation, and element-wise operations can be used on the Array
. Modifying the data or format after creation may cause the trailing_bits to not be empty.
Initialization examples:
Array('>H', [1, 10, 20])
Array('float16', a_file_object)
Array('int4', stored_bytes)
Methods¶
append
– Append a single item to the end of the Array.byteswap
– Change byte endianness of all items.count
– Count the number of occurences of a value.extend
– Append multiple items to the end of the Array from an iterable.fromfile
– Append items read from a file object.insert
– Insert an item at a given position.pop
– Return and remove an item.pp
– Pretty print the Array.reverse
– Reverse the order of all items.tobytes
– Return Array data as bytes object, padding with zero bits at the end if needed.tofile
– Write Array data to a file, padding with zero bits at the end if needed.tolist
– Return Array items as a list.
Special methods¶
These non-mutating special methods are available. Where appropriate they return a new Array
.
[]
– Get an element or slice.+
– Add value to each element.-
– Subtract value from each element.*
– Multiply each element by a value./
– Divide each element by a value.//
– Floor divide each element by a value.<<
– Shift value of each element to the left.>>
– Shift value of each element to the right.&
– Bit-wise AND of each element.|
– Bit-wise OR of each element.^
– Bit-wise XOR of each element.
For example:
>>> b = Array('i6', [30, -10, 1, 0])
>>> b >> 2
Array('i6', [7, -3, 0, 0])
>>> b + 1
Array('i6', [31, -9, 2, 1])
>>> b + b
Array('i6', [30, -10, 1, 0, 30, -10, 1, 0])
Mutating versions of many of the methods are also available.
[]
– Set an element or slice.del
– Delete an element or slice.+=
– Concatenate Array, or add value to each element in-place.-=
– Subtract value from each element in-place.*=
– Multiply each element by a value in-place./=
– Divide each element by a value in-place.//=
– Floor divide each element by a value in-place.<<=
– Shift bits of each element to the left in-place.>>=
– Shift bits of each element to the right in-place.&=
– In-place bit-wise AND of each element.|=
– In-place bit-wise OR of each element.^=
– In-place bit-wise XOR of each element.
Example:
>>> a = Array('float16', [1.5, 2.5, 7, 1000])
>>> a[::2] *= 3.0 # Multiply every other float16 value in-place
>>> a
Array('float16', [4.5, 2.5, 21.0, 1000.0])
The bit-wise logical operations (&
, |
, ^
) are performed on each element with a Bits
object, which must have the same length as the Array
elements.
The other element-wise operations are performed on the interpreted data, not on the bit-data.
For example this means that the shift operations won’t work on floating point formats.
Properties¶
data
– The complete binary data in aBitArray
object. Can be freely modified.fmt
– The format string or typecode. Can be freely modified.itemsize
– The length in bits of a single item. Read only.trailing_bits
– If the data length is not a multiple of the fmt length, thisBitArray
gives the leftovers at the end of the data.
General Information¶
Format tokens¶
Format strings are used when constructing bitstrings, as well as reading, packing and unpacking them, as well as giving the format for Array
objects.
They can also be auto promoted to bitstring when appropriate - see The auto initialiser.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
16 bits as a big-endian bfloat floating point number (same as |
|
16 bits as a big-endian bfloat floating point number (same as |
|
16 bits as a little-endian floating point number. |
|
16 bits as a native-endian floating point number. |
|
8 bits as a 1:4:3 format floating point number. |
|
8 bits as a 1:5:2 format floating point number. |
|
|
|
|
|
|
|
|
|
|
|
next bits as an unsigned exponential-Golomb code. |
|
next bits as a signed exponential-Golomb code. |
|
next bits as an interleaved unsigned exponential-Golomb code. |
|
next bits as an interleaved signed exponential-Golomb code. |
|
next bit as a boolean (True or False). |
|
next |
The ':'
before the length is optional, and is mostly omitted in the documentation, except where it improves readability.
The hex
, bin
, oct
, int
, uint
and float
properties can all be shortened to just their initial letter.
Bitstring literals¶
To make a literal quantity (one that directly represents a sequence of bits) you can use any of the format tokens above followed by an '='
and a value to initialise with.
For example:
s = BitArray('float32=10.125, int7=-9')
s.append('hex:abc')
You can also create binary, octal and hexadecimal literals by starting a string with '0b'
, '0o'
and '0ox'
respectively:
t = BitArray('0b101')
t += '0x001f'
Compact format strings¶
Another option is to use a format specifier similar to those used in the struct
and array
modules. These consist of a character to give the endianness, followed by more single characters to give the format.
The endianness character must start the format string:
|
Big-endian |
|
Little-endian |
|
Native-endian |
Note
For native-endian
'@'
and'='
can both be used and are equivalent. The'@'
character was required for native-endianness prior to version 4.1 of bitstring.For ‘network’ endianness use
'>'
as network and big-endian are equivalent.
This is followed by at least one of these format characters:
|
8 bit signed integer |
|
8 bit unsigned integer |
|
16 bit signed integer |
|
16 bit unsigned integer |
|
32 bit signed integer |
|
32 bit unsigned integer |
|
64 bit signed integer |
|
64 bit unsigned integer |
|
16 bit floating point number |
|
32 bit floating point number |
|
64 bit floating point number |
The exact type is determined by combining the endianness character with the format character, but rather than give an exhaustive list a single example should explain:
|
Big-endian 16 bit signed integer |
|
|
Little-endian 16 bit signed integer |
|
|
Native-endian 16 bit signed integer |
|
As you can see all three are signed integers in 16 bits, the only difference is the endianness. The native-endian '=h'
will equal the big-endian '>h'
on big-endian systems, and equal the little-endian '<h'
on little-endian systems. For the single byte codes 'b'
and 'B'
the endianness doesn’t make any difference, but you still need to specify one so that the format string can be parsed correctly.
Module level¶
Functions¶
pack
– Create a newBitStream
according to a format string and values.
Exceptions¶
Error
– Base class for module exceptions.ReadError
– Reading or peeking past the end of a bitstring.InterpretError
– Inappropriate interpretation of binary data.ByteAlignError
– Whole-byte position or length needed.CreationError
– Inappropriate argument during bitstring creation.
Module variables¶
bytealigned
– Determines whether a number of methods default to working only on byte boundaries.lsb0
– If True, index bits with the least significant bit (the final bit) as bit zero.