Bits Class¶
The Bits
class is the simplest type in the bitstring module, and represents an immutable sequence of bits. This is the best class to use if you will not need to modify the data after creation and don’t need streaming methods.
- class Bits([auto, length, offset, **kwargs])¶
Creates a new bitstring. You must specify either no initialiser, just an
auto
value, or one of the keyword argumentsbytes
,bin
,hex
,oct
,uint
,int
,uintbe
,intbe
,uintle
,intle
,uintne
,intne
,se
,ue
,sie
,uie
,float
,floatbe
,floatle
,floatne
,bfloat
,bfloatbe
,bfloatle
,bfloatne
,bool
orfilename
. If no initialiser is given then a zeroed bitstring oflength
bits is created.The initialiser for the
Bits
class is precisely the same as forBitArray
,BitStream
andConstBitStream
.offset
is available when using thebytes
orfilename
initialisers. It gives a number of bits to ignore at the start of the bitstring.Specifying
length
is mandatory when using the various integer initialisers. It must be large enough that a bitstring can contain the integer inlength
bits. It must also be specified for the float initialisers (the only valid values are 16, 32 and 64). It is optional for thebytes
andfilename
initialisers and can be used to truncate data from the end of the input value.>>> s1 = Bits(hex='0x934') >>> s2 = Bits(oct='0o4464') >>> s3 = Bits(bin='0b001000110100') >>> s4 = Bits(int=-1740, length=12) >>> s5 = Bits(uint=2356, length=12) >>> s6 = Bits(bytes=b'\x93@', length=12) >>> s1 == s2 == s3 == s4 == s5 == s6 True
For information on the use of
auto
see The auto initialiser.>>> s = Bits('uint12=32, 0b110') >>> t = Bits('0o755, ue=12, int:3=-1')
Methods¶
all¶
- Bits.all(value[, pos])¶
Returns
True
if all of the specified bits are all set to value, otherwise returnsFalse
.If value is
True
then1
bits are checked for, otherwise0
bits are checked for.pos should be an iterable of bit positions. Negative numbers are treated in the same way as slice indices and it will raise an
IndexError
ifpos < -len(s)
orpos > len(s)
. It defaults to the whole bitstring.>>> s = Bits('int15=-1') >>> s.all(True, [3, 4, 12, 13]) True >>> s.all(1) True
any¶
- Bits.any(value[, pos])¶
Returns
True
if any of the specified bits are set to value, otherwise returnsFalse
.If value is
True
then1
bits are checked for, otherwise0
bits are checked for.pos should be an iterable of bit positions. Negative numbers are treated in the same way as slice indices and it will raise an
IndexError
ifpos < -len(s)
orpos > len(s)
. It defaults to the whole bitstring.>>> s = Bits('0b11011100') >>> s.any(False, range(6)) True >>> s.any(1) True
copy¶
- Bits.copy()¶
Returns a copy of the bitstring.
s.copy()
is equivalent to the shallow copys[:]
and creates a new copy of the bitstring in memory.
count¶
- Bits.count(value)¶
Returns the number of bits set to value.
value can be
True
orFalse
or anything that can be cast to a bool, so you could equally use1
or0
.>>> s = BitArray(1000000) >>> s.set(1, [4, 44, 444444]) >>> s.count(1) 3 >>> s.count(False) 999997Note that if the bitstring is very sparse, as in the example here, it could be quicker to find and count all the set bits with something like
len(list(s.findall('0b1')))
. For bitstrings with more entropy thecount
method will be much quicker than finding.
cut¶
- Bits.cut(bits[, start, end, count])¶
Returns a generator for slices of the bitstring of length bits.
At most count items are returned and the range is given by the slice [start:end], which defaults to the whole bitstring.
>>> s = BitArray('0x1234') >>> for nibble in s.cut(4): ... s.prepend(nibble) >>> print(s) 0x43211234
endswith¶
- Bits.endswith(bs[, start, end])¶
Returns
True
if the bitstring ends with the sub-string bs, otherwise returnsFalse
.A slice can be given using the start and end bit positions and defaults to the whole bitstring.
>>> s = Bits('0x35e22') >>> s.endswith('0b10, 0x22') True >>> s.endswith('0x22', start=13) False
find¶
- Bits.find(bs[, start, end, bytealigned])¶
Searches for bs in the current bitstring and sets
pos
to the start of bs and returns it in a tuple if found, otherwise it returns an empty tuple.The reason for returning the bit position in a tuple is so that it evaluates as True even if the bit position is zero. This allows constructs such as
if s.find('0xb3'):
to work as expected.If bytealigned is
True
then it will look for bs only at byte aligned positions (which is generally much faster than searching for it in every possible bit position). start and end give the search range and default to the whole bitstring.>>> s = Bits('0x0023122') >>> s.find('0b000100', bytealigned=True) (16,)
findall¶
- Bits.findall(bs[, start, end, count, bytealigned])¶
Searches for all occurrences of bs (even overlapping ones) and returns a generator of their bit positions.
If bytealigned is
True
then bs will only be looked for at byte aligned positions. start and end optionally define a search range and default to the whole bitstring.The count parameter limits the number of items that will be found - the default is to find all occurrences.
>>> s = Bits('0xab220101')*5 >>> list(s.findall('0x22', bytealigned=True)) [8, 40, 72, 104, 136]
join¶
- Bits.join(sequence)¶
Returns the concatenation of the bitstrings in the iterable sequence joined with
self
as a separator.>>> s = Bits().join(['0x0001ee', 'uint:24=13', '0b0111']) >>> print(s) 0x0001ee00000d7 >>> s = Bits('0b1').join(['0b0']*5) >>> print(s.bin) 010101010
pp¶
- Bits.pp([fmt, width, sep, show_offset, stream])¶
Pretty print the bitstring’s value according to the fmt. Either a single, or two comma separated formats can be specified, together with options for setting the maximum display width, the number of bits to display in each group, and the separator to print between groups.
>>> s = Bits(int=-98987987293452, length=200) >>> s.pp() 0: 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111111 64: 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111111 128: 11111111 11111111 11111111 10100101 11111000 10010000 00101110 00101010 192: 11110100>>> s.pp('h12, b', show_offset=False, sep='-') fff-fff-fff-fff 111111111111-111111111111-111111111111-111111111111 fff-fff-fff-fff 111111111111-111111111111-111111111111-111111111111 fff-fff-fff-fff 111111111111-111111111111-111111111111-111111111111 ffa-5f8-902-e2a 111111111010-010111111000-100100000010-111000101010 f4 11110100The available formats are
'bin'
(the default),'oct'
,'hex'
and'bytes'
. A bit length can be specified after the format (with an optional :) to give the number of bits represented by each group, otherwise the default is based on the format or formats selected. Using a length of zero removes all separators and displays one block of characters per line for each format in fmt (e.g.'hex0'
).The
hex
,oct
andbin
format string can be replaced with just their initial letter.For the
'bytes'
format unprintable characters are replaced with a full stop.If the bitstring cannot be represented in a format due to it’s length not being a multiple of the number of bits represented by each character then an
InterpretError
will be raised.An output stream can be specified. This should be an object with a
write
method and the default issys.stdout
.
rfind¶
- Bits.rfind(bs[, start, end, bytealigned])¶
Searches backwards for bs in the current bitstring and sets
pos
to the start of bs and returns it in a tuple if found, otherwise it returns an empty tuple.The reason for returning the bit position in a tuple is so that it evaluates as True even if the bit position is zero. This allows constructs such as
if s.rfind('0xb3'):
to work as expected.If bytealigned is
True
then it will look for bs only at byte aligned positions. start and end give the search range and default to0
andlen
respectively.Note that as it’s a reverse search it will start at end and finish at start.
>>> s = Bits('0o031544') >>> s.rfind('0b100') (15,) >>> s.rfind('0b100', end=17) (12,)
split¶
- Bits.split(delimiter[, start, end, count, bytealigned])¶
Splits the bitstring into sections that start with delimiter. Returns a generator for bitstring objects.
The first item generated is always the bits before the first occurrence of delimiter (even if empty). A slice can be optionally specified with start and end, while count specifies the maximum number of items generated.
If bytealigned is
True
then the delimiter will only be found if it starts at a byte aligned position.>>> s = Bits('0x42423') >>> [bs.bin for bs in s.split('0x4')] ['', '01000', '01001000', '0100011']
startswith¶
- Bits.startswith(bs[, start, end])¶
Returns
True
if the bitstring starts with the sub-string bs, otherwise returnsFalse
.A slice can be given using the start and end bit positions and defaults to the whole bitstring.
tobytes¶
- Bits.tobytes()¶
Returns the bitstring as a
bytes
object.The returned value will be padded at the end with between zero and seven
0
bits to make it byte aligned.This method can also be used to output your bitstring to a file - just open a file in binary write mode and write the function’s output.
>>> s = Bits(bytes=b'hello') >>> s += '0b01' >>> s.tobytes() b'hello@'
tofile¶
- Bits.tofile(f)¶
Writes the bitstring to the file object f, which should have been opened in binary write mode.
The data written will be padded at the end with between zero and seven
0
bits to make it byte aligned.>>> f = open('newfile', 'wb') >>> Bits('0x1234').tofile(f)
unpack¶
- Bits.unpack(fmt, **kwargs)¶
Interprets the whole bitstring according to the fmt string or iterable and returns a list of bitstring objects.
A dictionary or keyword arguments can also be provided. These will replace length identifiers in the format string.
fmt is an iterable or a string with comma separated tokens that describe how to interpret the next bits in the bitstring. See the entry for
read
for details.>>> s = Bits('int4=-1, 0b1110') >>> i, b = s.unpack('int:4, bin')If a token doesn’t supply a length (as with
bin
above) then it will try to consume the rest of the bitstring. Only one such token is allowed.
Properties¶
Note that the bin
, oct
, hex
, int
, uint
and float
properties can all be shortened to their initial letter. Properties can also have a length in bits appended to them to such as u8
or f64
(for the bytes
property the length is interpreted in bytes instead of bits). These properties with lengths will cause an InterpretError
to be raised if the bitstring is not of the specified length.
bin / b¶
bfloat / bfloatbe¶
Note
The
bfloat
properties are specialised representations mainly used in machine learning. They are essentially the first half of the IEEE 32-bit floats, so have the same range but with less accuracy. If you don’t know what a bfloat is then you almost certainly want to use thefloat
properties instead.
- Bits.bfloat¶
- Bits.bfloatbe¶
Property for the 2 byte bfloat floating point representation of the bitstring.
The bitstring must be 16 bits long to support this floating point interpretation, otherwise an
InterpretError
will be raised.The
bfloat
property is bit-wise big-endian, which as all floats must be whole-byte is exactly equivalent to the byte-wise big-endianbfloatbe
.
bfloatle¶
- Bits.bfloatle¶
Property for the byte-wise little-endian 2 byte bfloat floating point representation of the bitstring.
bfloatne¶
- Bits.bfloatne¶
Property for the byte-wise native-endian 2 byte bfloat floating point representation of the bitstring.
bool¶
- Bits.bool¶
Property for representing the bitstring as a boolean (
True
orFalse
).If the bitstring is not a single bit then the getter will raise an
InterpretError
.
bytes¶
- Bits.bytes¶
Property representing the underlying byte data that contains the bitstring.
When used as a getter the bitstring must be a whole number of byte long or a
InterpretError
will be raised.An alternative is to use the
tobytes
method, which will pad with between zero and seven0
bits to make it byte aligned if needed.>>> s = Bits('0x12345678') >>> s.bytes b'\x124Vx'
hex / h¶
- Bits.hex¶
- Bits.h¶
Property representing the hexadecimal value of the bitstring.
If the bitstring is not a multiple of four bits long then getting its hex value will raise an
InterpretError
.>>> s = Bits(bin='1111 0000') >>> s.hex 'f0'
int / i¶
intbe¶
- Bits.intbe¶
Property for the byte-wise big-endian signed two’s complement integer representation of the bitstring.
Only valid for whole-byte bitstrings, in which case it is equal to
s.int
, otherwise anInterpretError
is raised.
intle¶
- Bits.intle¶
Property for the byte-wise little-endian signed two’s complement integer representation of the bitstring.
Only valid for whole-byte bitstring, in which case it is equal to
s[::-8].int
, i.e. the integer representation of the byte-reversed bitstring.
intne¶
- Bits.intne¶
Property for the byte-wise native-endian signed two’s complement integer representation of the bitstring.
Only valid for whole-byte bitstrings, and will equal either the big-endian or the little-endian integer representation depending on the platform being used.
float / floatbe / f¶
- Bits.float¶
- Bits.floatbe¶
- Bits.f¶
Property for the floating point representation of the bitstring.
The bitstring must be 16, 32 or 64 bits long to support the floating point interpretations, otherwise an
InterpretError
will be raised.If the underlying floating point methods on your machine are not IEEE 754 compliant then using the float interpretations is undefined (this is unlikely unless you’re on some very unusual hardware).
The
float
property is bit-wise big-endian, which as all floats must be whole-byte is exactly equivalent to the byte-wise big-endianfloatbe
.
floatle¶
- Bits.floatle¶
Property for the byte-wise little-endian floating point representation of the bitstring.
floatne¶
- Bits.floatne¶
Property for the byte-wise native-endian floating point representation of the bitstring.
len / length¶
- Bits.len¶
- Bits.length¶
Read-only property that give the length of the bitstring in bits (
len
andlength
are equivalent).Using the
len()
built-in function is preferred in almost all cases, but these properties are available for backward compatibility. The only occasion where the properties are needed is if a 32-bit build of Python is being used and you have a bitstring whose length doesn’t fit in a 32-bit unsigned integer. In that caselen(s)
may fail with anOverflowError
, whereass.len
will still work. With 64-bit Python the problem shouldn’t occur unless you have more than a couple of exabytes of data!
oct / o¶
- Bits.oct¶
- Bits.o¶
Property for the octal representation of the bitstring.
If the bitstring is not a multiple of three bits long then getting its octal value will raise a
InterpretError
.>>> s = Bits('0b111101101') >>> s.oct '755' >>> s.oct = '01234567' >>> s.oct '01234567'
se¶
- Bits.se¶
Property for the signed exponential-Golomb code representation of the bitstring.
When used as a getter an
InterpretError
will be raised if the bitstring is not a single code.>>> s = BitArray(se=-40) >>> s.bin 0000001010001 >>> s += '0b1' >>> s.se Error: BitString is not a single exponential-Golomb code.
ue¶
- Bits.ue¶
Property for the unsigned exponential-Golomb code representation of the bitstring.
When used as a getter an
InterpretError
will be raised if the bitstring is not a single code.
sie¶
- Bits.sie¶
Property for the signed interleaved exponential-Golomb code representation of the bitstring.
When used as a getter an
InterpretError
will be raised if the bitstring is not a single code.
uie¶
- Bits.uie¶
Property for the unsigned interleaved exponential-Golomb code representation of the bitstring.
When used as a getter an
InterpretError
will be raised if the bitstring is not a single code.
uint / u¶
uintbe¶
- Bits.uintbe¶
Property for the byte-wise big-endian unsigned base-2 integer representation of the bitstring.
uintle¶
- Bits.uintle¶
Property for the byte-wise little-endian unsigned base-2 integer representation of the bitstring.
uintne¶
- Bits.uintne¶
Property for the byte-wise native-endian unsigned base-2 integer representation of the bitstring.
Special Methods¶
__add__ / __radd__¶
__and__ / __rand__¶
__bool__¶
- Bits.__bool__()¶
if s:
Returns
True
if at least one bit is set to 1, otherwise returnsFalse
.>>> bool(Bits()) False >>> bool(Bits('0b0000010000')) True >>> bool(Bits('0b0000000000')) False
__contains__¶
__copy__¶
- Bits.__copy__()¶
s2 = copy.copy(s1)
This allows the
copy
module to correctly copy bitstrings. Other equivalent methods are to initialise a new bitstring with the old one or to take a complete slice.>>> import copy >>> s = Bits('0o775') >>> s_copy1 = copy.copy(s) >>> s_copy2 = Bits(s) >>> s_copy3 = s[:] >>> s == s_copy1 == s_copy2 == s_copy3 True
__eq__¶
- Bits.__eq__(bs)¶
s1 == s2
Compares two bitstring objects for equality, returning
True
if they have the same binary representation, otherwise returningFalse
.>>> Bits('0o7777') == '0xfff' True >>> a = Bits(uint=13, length=8) >>> b = Bits(uint=13, length=10) >>> a == b False
__getitem__¶
- Bits.__getitem__(key)¶
s[start:end:step]
Returns a slice of the bitstring.
The usual slice behaviour applies.
>>> s = Bits('0x0123456') >>> s[4:8] Bits('0x1') >>> s[1::8] # 1st, 9th, 17th and 25th bits Bits('0x3')If a single element is asked for then either
True
orFalse
will be returned.>>> s[0] False >>> s[-1] True
__hash__¶
__invert__¶
__len__¶
- Bits.__len__()¶
len(s)
Returns the length of the bitstring in bits if it is less than
sys.maxsize
, otherwise raisesOverflowError
.It’s recommended that you use the
len
property rather than thelen
function because of the function’s behaviour for large bitstring objects, although calling the special function directly will always work.>>> s = Bits(filename='11GB.mkv') >>> s.len 93944160032 >>> len(s) OverflowError: long int too large to convert to int >>> s.__len__() 93944160032
__lshift__¶
- Bits.__lshift__(n)¶
s << n
Returns the bitstring with its bits shifted n places to the left. The n right-most bits will become zeros.
>>> s = Bits('0xff') >>> s << 4 Bits('0xf0')
__mul__ / __rmul__¶
__ne__¶
- Bits.__ne__(bs)¶
s1 != s2
Compares two bitstring objects for inequality, returning
False
if they have the same binary representation, otherwise returningTrue
.
__nonzero__¶
__or__ / __ror__¶
__repr__¶
- Bits.__repr__()¶
repr(s)
A representation of the bitstring that could be used to create it (which will often not be the form used to create it).
If the result is too long then it will be truncated with
...
and the length of the whole will be given.>>> Bits(‘0b11100011’) Bits(‘0xe3’)
__rshift__¶
- Bits.__rshift__(n)¶
s >> n
Returns the bitstring with its bits shifted n places to the right. The n left-most bits will become zeros.
>>> s = Bits(‘0xff’) >>> s >> 4 Bits(‘0x0f’)
__str__¶
- Bits.__str__()¶
print(s)
Used to print a representation of the bitstring, trying to be as brief as possible.
If the bitstring is a multiple of 4 bits long then hex will be used, otherwise either binary or a mix of hex and binary will be used. Very long strings will be truncated with
...
.>>> s = Bits('0b1')*7 >>> print(s) 0b1111111 >>> print(s + '0b1') 0xffSee also the
pp
method for ways to pretty-print the bitstring.