4389 lines
172 KiB
Python
Executable File
4389 lines
172 KiB
Python
Executable File
#!/usr/bin/env python
|
|
"""
|
|
This package defines classes that simplify bit-wise creation, manipulation and
|
|
interpretation of data.
|
|
|
|
Classes:
|
|
|
|
Bits -- An immutable container for binary data.
|
|
BitArray -- A mutable container for binary data.
|
|
ConstBitStream -- An immutable container with streaming methods.
|
|
BitStream -- A mutable container with streaming methods.
|
|
|
|
Bits (base class)
|
|
/ \
|
|
+ mutating methods / \ + streaming methods
|
|
/ \
|
|
BitArray ConstBitStream
|
|
\ /
|
|
\ /
|
|
\ /
|
|
BitStream
|
|
|
|
Functions:
|
|
|
|
pack -- Create a BitStream from a format string.
|
|
|
|
Exceptions:
|
|
|
|
Error -- Module exception base class.
|
|
CreationError -- Error during creation.
|
|
InterpretError -- Inappropriate interpretation of binary data.
|
|
ByteAlignError -- Whole byte position or length needed.
|
|
ReadError -- Reading or peeking past the end of a bitstring.
|
|
|
|
https://github.com/scott-griffiths/bitstring
|
|
"""
|
|
|
|
__licence__ = """
|
|
The MIT License
|
|
|
|
Copyright (c) 2006-2020 Scott Griffiths (dr.scottgriffiths@gmail.com)
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
THE SOFTWARE.
|
|
"""
|
|
|
|
__version__ = "3.1.7"
|
|
|
|
__author__ = "Scott Griffiths"
|
|
|
|
import numbers
|
|
import copy
|
|
import sys
|
|
import re
|
|
import binascii
|
|
import mmap
|
|
import os
|
|
import struct
|
|
import operator
|
|
import array
|
|
import io
|
|
import collections
|
|
|
|
try:
|
|
collectionsAbc = collections.abc
|
|
except AttributeError: # Python 2.7
|
|
collectionsAbc = collections
|
|
|
|
byteorder = sys.byteorder
|
|
|
|
bytealigned = False
|
|
"""Determines whether a number of methods default to working only on byte boundaries."""
|
|
|
|
|
|
# Maximum number of digits to use in __str__ and __repr__.
|
|
MAX_CHARS = 250
|
|
|
|
# Maximum size of caches used for speed optimisations.
|
|
CACHE_SIZE = 1000
|
|
|
|
|
|
class Error(Exception):
|
|
"""Base class for errors in the bitstring module."""
|
|
|
|
def __init__(self, *params):
|
|
self.msg = params[0] if params else ''
|
|
self.params = params[1:]
|
|
|
|
def __str__(self):
|
|
if self.params:
|
|
return self.msg.format(*self.params)
|
|
return self.msg
|
|
|
|
|
|
class ReadError(Error, IndexError):
|
|
"""Reading or peeking past the end of a bitstring."""
|
|
|
|
def __init__(self, *params):
|
|
Error.__init__(self, *params)
|
|
|
|
|
|
class InterpretError(Error, ValueError):
|
|
"""Inappropriate interpretation of binary data."""
|
|
|
|
def __init__(self, *params):
|
|
Error.__init__(self, *params)
|
|
|
|
|
|
class ByteAlignError(Error):
|
|
"""Whole-byte position or length needed."""
|
|
|
|
def __init__(self, *params):
|
|
Error.__init__(self, *params)
|
|
|
|
|
|
class CreationError(Error, ValueError):
|
|
"""Inappropriate argument during bitstring creation."""
|
|
|
|
def __init__(self, *params):
|
|
Error.__init__(self, *params)
|
|
|
|
|
|
class ConstByteStore(object):
|
|
"""Stores raw bytes together with a bit offset and length.
|
|
|
|
Used internally - not part of public interface.
|
|
"""
|
|
|
|
__slots__ = ('offset', '_rawarray', 'bitlength')
|
|
|
|
def __init__(self, data, bitlength=None, offset=None):
|
|
"""data is either a bytearray or a MmapByteArray"""
|
|
self._rawarray = data
|
|
if offset is None:
|
|
offset = 0
|
|
if bitlength is None:
|
|
bitlength = 8 * len(data) - offset
|
|
self.offset = offset
|
|
self.bitlength = bitlength
|
|
|
|
def __iter__(self):
|
|
start_byte, start_bit = divmod(self.offset, 8)
|
|
end_byte, end_bit = divmod(self.offset + self.bitlength, 8)
|
|
|
|
for byte_index in xrange(start_byte, end_byte):
|
|
byte = self._rawarray[byte_index]
|
|
for bit in range(start_bit, 8):
|
|
yield bool(byte & (128 >> bit))
|
|
start_bit = 0
|
|
|
|
if end_bit:
|
|
byte = self._rawarray[end_byte]
|
|
for bit in range(start_bit, end_bit):
|
|
yield bool(byte & (128 >> bit))
|
|
|
|
def _getbit_lsb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
pos = self.bitlength - pos - 1
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
return bool(self._rawarray[byte] & (128 >> bit))
|
|
|
|
def _getbit_msb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
return bool(self._rawarray[byte] & (128 >> bit))
|
|
|
|
def getbyte(self, pos):
|
|
"""Direct access to byte data."""
|
|
return self._rawarray[pos]
|
|
|
|
def getbyteslice(self, start, end):
|
|
"""Direct access to byte data."""
|
|
c = self._rawarray[start:end]
|
|
return c
|
|
|
|
@property
|
|
def bytelength(self):
|
|
if not self.bitlength:
|
|
return 0
|
|
sb = self.offset // 8
|
|
eb = (self.offset + self.bitlength - 1) // 8
|
|
return eb - sb + 1
|
|
|
|
def __copy__(self):
|
|
return ByteStore(self._rawarray[:], self.bitlength, self.offset)
|
|
|
|
def _appendstore(self, store):
|
|
"""Join another store on to the end of this one."""
|
|
if not store.bitlength:
|
|
return
|
|
# Set new array offset to the number of bits in the final byte of current array.
|
|
store = offsetcopy(store, (self.offset + self.bitlength) % 8)
|
|
if store.offset:
|
|
# first do the byte with the join.
|
|
joinval = (self._rawarray.pop() & (255 ^ (255 >> store.offset)) |
|
|
(store.getbyte(0) & (255 >> store.offset)))
|
|
self._rawarray.append(joinval)
|
|
self._rawarray.extend(store._rawarray[1:])
|
|
else:
|
|
self._rawarray.extend(store._rawarray)
|
|
self.bitlength += store.bitlength
|
|
|
|
def _prependstore(self, store):
|
|
"""Join another store on to the start of this one."""
|
|
if not store.bitlength:
|
|
return
|
|
# Set the offset of copy of store so that it's final byte
|
|
# ends in a position that matches the offset of self,
|
|
# then join self on to the end of it.
|
|
store = offsetcopy(store, (self.offset - store.bitlength) % 8)
|
|
assert (store.offset + store.bitlength) % 8 == self.offset % 8
|
|
bit_offset = self.offset % 8
|
|
if bit_offset:
|
|
# first do the byte with the join.
|
|
joinval = (store.getbyte(-1) & (255 ^ (255 >> bit_offset)) |
|
|
(self._rawarray[self.byteoffset] & (255 >> bit_offset)))
|
|
store._rawarray[-1] = joinval
|
|
store._rawarray.extend(self._rawarray[self.byteoffset + 1: self.byteoffset + self.bytelength])
|
|
else:
|
|
store._rawarray.extend(self._rawarray[self.byteoffset: self.byteoffset + self.bytelength])
|
|
self._rawarray = store._rawarray
|
|
self.offset = store.offset
|
|
self.bitlength += store.bitlength
|
|
|
|
@property
|
|
def byteoffset(self):
|
|
return self.offset // 8
|
|
|
|
@property
|
|
def rawbytes(self):
|
|
return self._rawarray
|
|
|
|
|
|
class ByteStore(ConstByteStore):
|
|
"""Adding mutating methods to ConstByteStore
|
|
|
|
Used internally - not part of public interface.
|
|
"""
|
|
__slots__ = ()
|
|
|
|
def _setbit_lsb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
pos = self.bitlength - pos - 1
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
self._rawarray[byte] |= (128 >> bit)
|
|
|
|
def _setbit_msb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
self._rawarray[byte] |= (128 >> bit)
|
|
|
|
def _unsetbit_lsb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
pos = self.bitlength - pos - 1
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
self._rawarray[byte] &= ~(128 >> bit)
|
|
|
|
def _unsetbit_msb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
self._rawarray[byte] &= ~(128 >> bit)
|
|
|
|
def _invertbit_lsb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
pos = self.bitlength - pos - 1
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
self._rawarray[byte] ^= (128 >> bit)
|
|
|
|
def _invertbit_msb0(self, pos):
|
|
assert 0 <= pos < self.bitlength
|
|
byte, bit = divmod(self.offset + pos, 8)
|
|
self._rawarray[byte] ^= (128 >> bit)
|
|
|
|
def setbyte(self, pos, value):
|
|
self._rawarray[pos] = value
|
|
|
|
def setbyteslice(self, start, end, value):
|
|
self._rawarray[start:end] = value
|
|
|
|
|
|
def offsetcopy(s, newoffset):
|
|
"""Return a copy of a ByteStore with the newoffset.
|
|
|
|
Not part of public interface.
|
|
"""
|
|
assert 0 <= newoffset < 8
|
|
if not s.bitlength:
|
|
return copy.copy(s)
|
|
else:
|
|
if newoffset == s.offset % 8:
|
|
return type(s)(s.getbyteslice(s.byteoffset, s.byteoffset + s.bytelength), s.bitlength, newoffset)
|
|
newdata = []
|
|
d = s._rawarray
|
|
assert newoffset != s.offset % 8
|
|
if newoffset < s.offset % 8:
|
|
# We need to shift everything left
|
|
shiftleft = s.offset % 8 - newoffset
|
|
# First deal with everything except for the final byte
|
|
for x in range(s.byteoffset, s.byteoffset + s.bytelength - 1):
|
|
newdata.append(((d[x] << shiftleft) & 0xff) +\
|
|
(d[x + 1] >> (8 - shiftleft)))
|
|
bits_in_last_byte = (s.offset + s.bitlength) % 8
|
|
if not bits_in_last_byte:
|
|
bits_in_last_byte = 8
|
|
if bits_in_last_byte > shiftleft:
|
|
newdata.append((d[s.byteoffset + s.bytelength - 1] << shiftleft) & 0xff)
|
|
else: # newoffset > s._offset % 8
|
|
shiftright = newoffset - s.offset % 8
|
|
newdata.append(s.getbyte(0) >> shiftright)
|
|
for x in range(s.byteoffset + 1, s.byteoffset + s.bytelength):
|
|
newdata.append(((d[x - 1] << (8 - shiftright)) & 0xff) +\
|
|
(d[x] >> shiftright))
|
|
bits_in_last_byte = (s.offset + s.bitlength) % 8
|
|
if not bits_in_last_byte:
|
|
bits_in_last_byte = 8
|
|
if bits_in_last_byte + shiftright > 8:
|
|
newdata.append((d[s.byteoffset + s.bytelength - 1] << (8 - shiftright)) & 0xff)
|
|
new_s = type(s)(bytearray(newdata), s.bitlength, newoffset)
|
|
assert new_s.offset == newoffset
|
|
return new_s
|
|
|
|
|
|
def equal(a, b):
|
|
"""Return True if ByteStores a == b.
|
|
|
|
Not part of public interface.
|
|
"""
|
|
# We want to return False for inequality as soon as possible, which
|
|
# means we get lots of special cases.
|
|
# First the easy one - compare lengths:
|
|
a_bitlength = a.bitlength
|
|
b_bitlength = b.bitlength
|
|
if a_bitlength != b_bitlength:
|
|
return False
|
|
if not a_bitlength:
|
|
assert b_bitlength == 0
|
|
return True
|
|
# Make 'a' the one with the smaller offset
|
|
if (a.offset % 8) > (b.offset % 8):
|
|
a, b = b, a
|
|
# and create some aliases
|
|
a_bitoff = a.offset % 8
|
|
b_bitoff = b.offset % 8
|
|
a_byteoffset = a.byteoffset
|
|
b_byteoffset = b.byteoffset
|
|
a_bytelength = a.bytelength
|
|
b_bytelength = b.bytelength
|
|
da = a._rawarray
|
|
db = b._rawarray
|
|
|
|
# If they are pointing to the same data, they must be equal
|
|
if da is db and a.offset == b.offset:
|
|
return True
|
|
|
|
if a_bitoff == b_bitoff:
|
|
bits_spare_in_last_byte = 8 - (a_bitoff + a_bitlength) % 8
|
|
if bits_spare_in_last_byte == 8:
|
|
bits_spare_in_last_byte = 0
|
|
# Special case for a, b contained in a single byte
|
|
if a_bytelength == 1:
|
|
a_val = ((da[a_byteoffset] << a_bitoff) & 0xff) >> (8 - a_bitlength)
|
|
b_val = ((db[b_byteoffset] << b_bitoff) & 0xff) >> (8 - b_bitlength)
|
|
return a_val == b_val
|
|
# Otherwise check first byte
|
|
if da[a_byteoffset] & (0xff >> a_bitoff) != db[b_byteoffset] & (0xff >> b_bitoff):
|
|
return False
|
|
# then everything up to the last
|
|
b_a_offset = b_byteoffset - a_byteoffset
|
|
for x in range(1 + a_byteoffset, a_byteoffset + a_bytelength - 1):
|
|
if da[x] != db[b_a_offset + x]:
|
|
return False
|
|
# and finally the last byte
|
|
return (da[a_byteoffset + a_bytelength - 1] >> bits_spare_in_last_byte ==
|
|
db[b_byteoffset + b_bytelength - 1] >> bits_spare_in_last_byte)
|
|
|
|
assert a_bitoff != b_bitoff
|
|
# This is how much we need to shift a to the right to compare with b:
|
|
shift = b_bitoff - a_bitoff
|
|
# Special case for b only one byte long
|
|
if b_bytelength == 1:
|
|
assert a_bytelength == 1
|
|
a_val = ((da[a_byteoffset] << a_bitoff) & 0xff) >> (8 - a_bitlength)
|
|
b_val = ((db[b_byteoffset] << b_bitoff) & 0xff) >> (8 - b_bitlength)
|
|
return a_val == b_val
|
|
# Special case for a only one byte long
|
|
if a_bytelength == 1:
|
|
assert b_bytelength == 2
|
|
a_val = ((da[a_byteoffset] << a_bitoff) & 0xff) >> (8 - a_bitlength)
|
|
b_val = ((db[b_byteoffset] << 8) + db[b_byteoffset + 1]) << b_bitoff
|
|
b_val &= 0xffff
|
|
b_val >>= 16 - b_bitlength
|
|
return a_val == b_val
|
|
|
|
# Compare first byte of b with bits from first byte of a
|
|
if (da[a_byteoffset] & (0xff >> a_bitoff)) >> shift != db[b_byteoffset] & (0xff >> b_bitoff):
|
|
return False
|
|
# Now compare every full byte of b with bits from 2 bytes of a
|
|
for x in range(1, b_bytelength - 1):
|
|
# Construct byte from 2 bytes in a to compare to byte in b
|
|
b_val = db[b_byteoffset + x]
|
|
a_val = ((da[a_byteoffset + x - 1] << 8) + da[a_byteoffset + x]) >> shift
|
|
a_val &= 0xff
|
|
if a_val != b_val:
|
|
return False
|
|
|
|
# Now check bits in final byte of b
|
|
final_b_bits = (b.offset + b_bitlength) % 8
|
|
if not final_b_bits:
|
|
final_b_bits = 8
|
|
b_val = db[b_byteoffset + b_bytelength - 1] >> (8 - final_b_bits)
|
|
final_a_bits = (a.offset + a_bitlength) % 8
|
|
if not final_a_bits:
|
|
final_a_bits = 8
|
|
if b.bytelength > a_bytelength:
|
|
assert b_bytelength == a_bytelength + 1
|
|
a_val = da[a_byteoffset + a_bytelength - 1] >> (8 - final_a_bits)
|
|
a_val &= 0xff >> (8 - final_b_bits)
|
|
return a_val == b_val
|
|
assert a_bytelength == b_bytelength
|
|
a_val = da[a_byteoffset + a_bytelength - 2] << 8
|
|
a_val += da[a_byteoffset + a_bytelength - 1]
|
|
a_val >>= (8 - final_a_bits)
|
|
a_val &= 0xff >> (8 - final_b_bits)
|
|
return a_val == b_val
|
|
|
|
|
|
class MmapByteArray(object):
|
|
"""Looks like a bytearray, but from an mmap.
|
|
|
|
Not part of public interface.
|
|
"""
|
|
|
|
__slots__ = ('filemap', 'filelength', 'source', 'byteoffset', 'bytelength')
|
|
|
|
def __init__(self, source, bytelength=None, byteoffset=None):
|
|
self.source = source
|
|
source.seek(0, os.SEEK_END)
|
|
self.filelength = source.tell()
|
|
if byteoffset is None:
|
|
byteoffset = 0
|
|
if bytelength is None:
|
|
bytelength = self.filelength - byteoffset
|
|
self.byteoffset = byteoffset
|
|
self.bytelength = bytelength
|
|
self.filemap = mmap.mmap(source.fileno(), 0, access=mmap.ACCESS_READ)
|
|
|
|
def __getitem__(self, key):
|
|
try:
|
|
start = key.start
|
|
stop = key.stop
|
|
except AttributeError:
|
|
try:
|
|
assert 0 <= key < self.bytelength
|
|
return ord(self.filemap[key + self.byteoffset])
|
|
except TypeError:
|
|
# for Python 3
|
|
return self.filemap[key + self.byteoffset]
|
|
else:
|
|
if start is None:
|
|
start = 0
|
|
if stop is None:
|
|
stop = self.bytelength
|
|
assert key.step is None
|
|
assert 0 <= start < self.bytelength
|
|
assert 0 <= stop <= self.bytelength
|
|
s = slice(start + self.byteoffset, stop + self.byteoffset)
|
|
return bytearray(self.filemap.__getitem__(s))
|
|
|
|
def __len__(self):
|
|
return self.bytelength
|
|
|
|
|
|
# This creates a dictionary for every possible byte with the value being
|
|
# the key with its bits reversed.
|
|
BYTE_REVERSAL_DICT = dict()
|
|
|
|
# For Python 2.7/ 3.x coexistence
|
|
# Yes this is very very hacky.
|
|
if sys.version_info[0] == 2:
|
|
for i in range(256):
|
|
BYTE_REVERSAL_DICT[i] = chr(int("{0:08b}".format(i)[::-1], 2))
|
|
else:
|
|
for i in range(256):
|
|
BYTE_REVERSAL_DICT[i] = bytes([int("{0:08b}".format(i)[::-1], 2)])
|
|
from io import IOBase as file
|
|
xrange = range
|
|
basestring = str
|
|
|
|
# Python 2.x octals start with '0', in Python 3 it's '0o'
|
|
LEADING_OCT_CHARS = len(oct(1)) - 1
|
|
|
|
def tidy_input_string(s):
|
|
"""Return string made lowercase and with all whitespace removed."""
|
|
s = ''.join(s.split()).lower()
|
|
return s
|
|
|
|
INIT_NAMES = ('uint', 'int', 'ue', 'se', 'sie', 'uie', 'hex', 'oct', 'bin', 'bits',
|
|
'uintbe', 'intbe', 'uintle', 'intle', 'uintne', 'intne',
|
|
'float', 'floatbe', 'floatle', 'floatne', 'bytes', 'bool', 'pad')
|
|
|
|
TOKEN_RE = re.compile(r'(?P<name>' + '|'.join(INIT_NAMES) +
|
|
r')((:(?P<len>[^=]+)))?(=(?P<value>.*))?$', re.IGNORECASE)
|
|
DEFAULT_UINT = re.compile(r'(?P<len>[^=]+)?(=(?P<value>.*))?$', re.IGNORECASE)
|
|
|
|
MULTIPLICATIVE_RE = re.compile(r'(?P<factor>.*)\*(?P<token>.+)')
|
|
|
|
# Hex, oct or binary literals
|
|
LITERAL_RE = re.compile(r'(?P<name>0(x|o|b))(?P<value>.+)', re.IGNORECASE)
|
|
|
|
# An endianness indicator followed by one or more struct.pack codes
|
|
STRUCT_PACK_RE = re.compile(r'(?P<endian><|>|@)?(?P<fmt>(?:\d*[bBhHlLqQfd])+)$')
|
|
|
|
# A number followed by a single character struct.pack code
|
|
STRUCT_SPLIT_RE = re.compile(r'\d*[bBhHlLqQfd]')
|
|
|
|
# These replicate the struct.pack codes
|
|
# Big-endian
|
|
REPLACEMENTS_BE = {'b': 'intbe:8', 'B': 'uintbe:8',
|
|
'h': 'intbe:16', 'H': 'uintbe:16',
|
|
'l': 'intbe:32', 'L': 'uintbe:32',
|
|
'q': 'intbe:64', 'Q': 'uintbe:64',
|
|
'f': 'floatbe:32', 'd': 'floatbe:64'}
|
|
# Little-endian
|
|
REPLACEMENTS_LE = {'b': 'intle:8', 'B': 'uintle:8',
|
|
'h': 'intle:16', 'H': 'uintle:16',
|
|
'l': 'intle:32', 'L': 'uintle:32',
|
|
'q': 'intle:64', 'Q': 'uintle:64',
|
|
'f': 'floatle:32', 'd': 'floatle:64'}
|
|
|
|
# Size in bytes of all the pack codes.
|
|
PACK_CODE_SIZE = {'b': 1, 'B': 1, 'h': 2, 'H': 2, 'l': 4, 'L': 4,
|
|
'q': 8, 'Q': 8, 'f': 4, 'd': 8}
|
|
|
|
_tokenname_to_initialiser = {'hex': 'hex', '0x': 'hex', '0X': 'hex', 'oct': 'oct',
|
|
'0o': 'oct', '0O': 'oct', 'bin': 'bin', '0b': 'bin',
|
|
'0B': 'bin', 'bits': 'auto', 'bytes': 'bytes', 'pad': 'pad'}
|
|
|
|
def structparser(token):
|
|
"""Parse struct-like format string token into sub-token list."""
|
|
m = STRUCT_PACK_RE.match(token)
|
|
if not m:
|
|
return [token]
|
|
else:
|
|
endian = m.group('endian')
|
|
if endian is None:
|
|
return [token]
|
|
# Split the format string into a list of 'q', '4h' etc.
|
|
formatlist = re.findall(STRUCT_SPLIT_RE, m.group('fmt'))
|
|
# Now deal with mulitiplicative factors, 4h -> hhhh etc.
|
|
fmt = ''.join([f[-1] * int(f[:-1]) if len(f) != 1 else
|
|
f for f in formatlist])
|
|
if endian == '@':
|
|
# Native endianness
|
|
if byteorder == 'little':
|
|
endian = '<'
|
|
else:
|
|
assert byteorder == 'big'
|
|
endian = '>'
|
|
if endian == '<':
|
|
tokens = [REPLACEMENTS_LE[c] for c in fmt]
|
|
else:
|
|
assert endian == '>'
|
|
tokens = [REPLACEMENTS_BE[c] for c in fmt]
|
|
return tokens
|
|
|
|
def tokenparser(fmt, keys=None, token_cache={}):
|
|
"""Divide the format string into tokens and parse them.
|
|
|
|
Return stretchy token and list of [initialiser, length, value]
|
|
initialiser is one of: hex, oct, bin, uint, int, se, ue, 0x, 0o, 0b etc.
|
|
length is None if not known, as is value.
|
|
|
|
If the token is in the keyword dictionary (keys) then it counts as a
|
|
special case and isn't messed with.
|
|
|
|
tokens must be of the form: [factor*][initialiser][:][length][=value]
|
|
|
|
"""
|
|
try:
|
|
return token_cache[(fmt, keys)]
|
|
except KeyError:
|
|
token_key = (fmt, keys)
|
|
# Very inefficient expanding of brackets.
|
|
fmt = expand_brackets(fmt)
|
|
# Split tokens by ',' and remove whitespace
|
|
# The meta_tokens can either be ordinary single tokens or multiple
|
|
# struct-format token strings.
|
|
meta_tokens = (''.join(f.split()) for f in fmt.split(','))
|
|
return_values = []
|
|
stretchy_token = False
|
|
for meta_token in meta_tokens:
|
|
# See if it has a multiplicative factor
|
|
m = MULTIPLICATIVE_RE.match(meta_token)
|
|
if not m:
|
|
factor = 1
|
|
else:
|
|
factor = int(m.group('factor'))
|
|
meta_token = m.group('token')
|
|
# See if it's a struct-like format
|
|
tokens = structparser(meta_token)
|
|
ret_vals = []
|
|
for token in tokens:
|
|
if keys and token in keys:
|
|
# Don't bother parsing it, it's a keyword argument
|
|
ret_vals.append([token, None, None])
|
|
continue
|
|
value = length = None
|
|
if token == '':
|
|
continue
|
|
# Match literal tokens of the form 0x... 0o... and 0b...
|
|
m = LITERAL_RE.match(token)
|
|
if m:
|
|
name = m.group('name')
|
|
value = m.group('value')
|
|
ret_vals.append([name, length, value])
|
|
continue
|
|
# Match everything else:
|
|
m1 = TOKEN_RE.match(token)
|
|
if not m1:
|
|
# and if you don't specify a 'name' then the default is 'uint':
|
|
m2 = DEFAULT_UINT.match(token)
|
|
if not m2:
|
|
raise ValueError("Don't understand token '{0}'.".format(token))
|
|
if m1:
|
|
name = m1.group('name')
|
|
length = m1.group('len')
|
|
if m1.group('value'):
|
|
value = m1.group('value')
|
|
else:
|
|
assert m2
|
|
name = 'uint'
|
|
length = m2.group('len')
|
|
if m2.group('value'):
|
|
value = m2.group('value')
|
|
if name == 'bool':
|
|
if length is not None and length != '1':
|
|
raise ValueError("You can only specify one bit sized bool tokens or leave unspecified.")
|
|
length = 1
|
|
if length is None and name not in ('se', 'ue', 'sie', 'uie'):
|
|
stretchy_token = True
|
|
if length is not None:
|
|
# Try converting length to int, otherwise check it's a key.
|
|
try:
|
|
length = int(length)
|
|
if length < 0:
|
|
raise Error
|
|
# For the 'bytes' token convert length to bits.
|
|
if name == 'bytes':
|
|
length *= 8
|
|
except Error:
|
|
raise ValueError("Can't read a token with a negative length.")
|
|
except ValueError:
|
|
if not keys or length not in keys:
|
|
raise ValueError("Don't understand length '{0}' of token.".format(length))
|
|
ret_vals.append([name, length, value])
|
|
# This multiplies by the multiplicative factor, but this means that
|
|
# we can't allow keyword values as multipliers (e.g. n*uint:8).
|
|
# The only way to do this would be to return the factor in some fashion
|
|
# (we can't use the key's value here as it would mean that we couldn't
|
|
# sensibly continue to cache the function's results. (TODO).
|
|
return_values.extend(ret_vals * factor)
|
|
return_values = [tuple(x) for x in return_values]
|
|
if len(token_cache) < CACHE_SIZE:
|
|
token_cache[token_key] = stretchy_token, return_values
|
|
return stretchy_token, return_values
|
|
|
|
# Looks for first number*(
|
|
BRACKET_RE = re.compile(r'(?P<factor>\d+)\*\(')
|
|
|
|
def expand_brackets(s):
|
|
"""Remove whitespace and expand all brackets."""
|
|
s = ''.join(s.split())
|
|
while True:
|
|
start = s.find('(')
|
|
if start == -1:
|
|
break
|
|
count = 1 # Number of hanging open brackets
|
|
p = start + 1
|
|
while p < len(s):
|
|
if s[p] == '(':
|
|
count += 1
|
|
if s[p] == ')':
|
|
count -= 1
|
|
if not count:
|
|
break
|
|
p += 1
|
|
if count:
|
|
raise ValueError("Unbalanced parenthesis in '{0}'.".format(s))
|
|
if start == 0 or s[start - 1] != '*':
|
|
s = s[0:start] + s[start + 1:p] + s[p + 1:]
|
|
else:
|
|
m = BRACKET_RE.search(s)
|
|
if m:
|
|
factor = int(m.group('factor'))
|
|
matchstart = m.start('factor')
|
|
s = s[0:matchstart] + (factor - 1) * (s[start + 1:p] + ',') + s[start + 1:p] + s[p + 1:]
|
|
else:
|
|
raise ValueError("Failed to parse '{0}'.".format(s))
|
|
return s
|
|
|
|
|
|
# This converts a single octal digit to 3 bits.
|
|
OCT_TO_BITS = ['{0:03b}'.format(i) for i in xrange(8)]
|
|
|
|
# A dictionary of number of 1 bits contained in binary representation of any byte
|
|
BIT_COUNT = dict(zip(xrange(256), [bin(i).count('1') for i in xrange(256)]))
|
|
|
|
|
|
class Bits(object):
|
|
"""A container holding an immutable sequence of bits.
|
|
|
|
For a mutable container use the BitArray class instead.
|
|
|
|
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.
|
|
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-string.
|
|
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.
|
|
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.
|
|
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 the operators [], ==, !=, +, *, ~, <<, >>, &, |, ^.
|
|
|
|
Properties:
|
|
|
|
bin -- The bitstring as a binary string.
|
|
bool -- For single bit bitstrings, interpret as True or False.
|
|
bytes -- The bitstring as a bytes object.
|
|
float -- Interpret as a floating point number.
|
|
floatbe -- 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.
|
|
hex -- The bitstring as a hexadecimal string.
|
|
int -- 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 -- 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 -- 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.
|
|
|
|
"""
|
|
|
|
__slots__ = ('_datastore')
|
|
|
|
def __init__(self, auto=None, length=None, offset=None, **kwargs):
|
|
"""Either specify an 'auto' initialiser:
|
|
auto -- a string of comma separated tokens, an integer, a file object,
|
|
a bytearray, a boolean iterable, an array or another bitstring.
|
|
|
|
Or initialise via **kwargs with one (and only one) of:
|
|
bytes -- raw data as a string, for example read from a binary file.
|
|
bin -- binary string representation, e.g. '0b001010'.
|
|
hex -- hexadecimal string representation, e.g. '0x2ef'
|
|
oct -- octal string representation, e.g. '0o777'.
|
|
uint -- an unsigned integer.
|
|
int -- a signed integer.
|
|
float -- a floating point number.
|
|
uintbe -- an unsigned big-endian whole byte integer.
|
|
intbe -- a signed big-endian whole byte integer.
|
|
floatbe - a big-endian floating point number.
|
|
uintle -- an unsigned little-endian whole byte integer.
|
|
intle -- a signed little-endian whole byte integer.
|
|
floatle -- a little-endian floating point number.
|
|
uintne -- an unsigned native-endian whole byte integer.
|
|
intne -- a signed native-endian whole byte integer.
|
|
floatne -- a native-endian floating point number.
|
|
se -- a signed exponential-Golomb code.
|
|
ue -- an unsigned exponential-Golomb code.
|
|
sie -- a signed interleaved exponential-Golomb code.
|
|
uie -- an unsigned interleaved exponential-Golomb code.
|
|
bool -- a boolean (True or False).
|
|
filename -- a file which will be opened in binary read-only mode.
|
|
|
|
Other keyword arguments:
|
|
length -- length of the bitstring in bits, if needed and appropriate.
|
|
It must be supplied for all integer and float initialisers.
|
|
offset -- bit offset to the data. These offset bits are
|
|
ignored and this is mainly intended for use when
|
|
initialising using 'bytes' or 'filename'.
|
|
|
|
"""
|
|
pass
|
|
|
|
def __new__(cls, auto=None, length=None, offset=None, _cache={}, **kwargs):
|
|
# For instances auto-initialised with a string we intern the
|
|
# instance for re-use.
|
|
try:
|
|
if isinstance(auto, basestring):
|
|
try:
|
|
return _cache[auto]
|
|
except KeyError:
|
|
x = object.__new__(Bits)
|
|
try:
|
|
_, tokens = tokenparser(auto)
|
|
except ValueError as e:
|
|
raise CreationError(*e.args)
|
|
x._datastore = ConstByteStore(bytearray(0), 0, 0)
|
|
for token in tokens:
|
|
x._datastore._appendstore(Bits._init_with_token(*token)._datastore)
|
|
assert x._assertsanity()
|
|
if len(_cache) < CACHE_SIZE:
|
|
_cache[auto] = x
|
|
return x
|
|
if type(auto) == Bits:
|
|
return auto
|
|
except TypeError:
|
|
pass
|
|
x = super(Bits, cls).__new__(cls)
|
|
x._datastore = ConstByteStore(b'')
|
|
x._initialise(auto, length, offset, **kwargs)
|
|
return x
|
|
|
|
def _initialise(self, auto, length, offset, **kwargs):
|
|
if length is not None and length < 0:
|
|
raise CreationError("bitstring length cannot be negative.")
|
|
if offset is not None and offset < 0:
|
|
raise CreationError("offset must be >= 0.")
|
|
if auto is not None:
|
|
self._initialise_from_auto(auto, length, offset)
|
|
return
|
|
if not kwargs:
|
|
# No initialisers, so initialise with nothing or zero bits
|
|
if length is not None and length != 0:
|
|
data = bytearray((length + 7) // 8)
|
|
self._setbytes_unsafe(data, length, 0)
|
|
return
|
|
self._setbytes_unsafe(bytearray(0), 0, 0)
|
|
return
|
|
k, v = kwargs.popitem()
|
|
try:
|
|
init_without_length_or_offset[k](self, v)
|
|
if length is not None or offset is not None:
|
|
raise CreationError("Cannot use length or offset with this initialiser.")
|
|
except KeyError:
|
|
try:
|
|
init_with_length_only[k](self, v, length)
|
|
if offset is not None:
|
|
raise CreationError("Cannot use offset with this initialiser.")
|
|
except KeyError:
|
|
if offset is None:
|
|
offset = 0
|
|
try:
|
|
init_with_length_and_offset[k](self, v, length, offset)
|
|
except KeyError:
|
|
raise CreationError("Unrecognised keyword '{0}' used to initialise.", k)
|
|
|
|
def _initialise_from_auto(self, auto, length, offset):
|
|
if offset is None:
|
|
offset = 0
|
|
self._setauto(auto, length, offset)
|
|
return
|
|
|
|
def __iter__(self):
|
|
return iter(self._datastore)
|
|
|
|
def __copy__(self):
|
|
"""Return a new copy of the Bits for the copy module."""
|
|
# Note that if you want a new copy (different ID), use _copy instead.
|
|
# The copy can return self as it's immutable.
|
|
return self
|
|
|
|
def __lt__(self, other):
|
|
raise TypeError("unorderable type: {0}".format(type(self).__name__))
|
|
|
|
def __gt__(self, other):
|
|
raise TypeError("unorderable type: {0}".format(type(self).__name__))
|
|
|
|
def __le__(self, other):
|
|
raise TypeError("unorderable type: {0}".format(type(self).__name__))
|
|
|
|
def __ge__(self, other):
|
|
raise TypeError("unorderable type: {0}".format(type(self).__name__))
|
|
|
|
def __add__(self, bs):
|
|
"""Concatenate bitstrings and return new bitstring.
|
|
|
|
bs -- the bitstring to append.
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
if bs.len <= self.len:
|
|
s = self._copy()
|
|
s._append(bs)
|
|
else:
|
|
s = bs._copy()
|
|
s = self.__class__(s)
|
|
s._prepend(self)
|
|
return s
|
|
|
|
def __radd__(self, bs):
|
|
"""Append current bitstring to bs and return new bitstring.
|
|
|
|
bs -- the string for the 'auto' initialiser that will be appended to.
|
|
|
|
"""
|
|
bs = self._converttobitstring(bs)
|
|
return bs.__add__(self)
|
|
|
|
def __getitem__(self, key):
|
|
"""Return a new bitstring representing a slice of the current bitstring.
|
|
|
|
Indices are in units of the step parameter (default 1 bit).
|
|
Stepping is used to specify the number of bits in each item.
|
|
|
|
>>> print BitArray('0b00110')[1:4]
|
|
'0b011'
|
|
>>> print BitArray('0x00112233')[1:3:8]
|
|
'0x1122'
|
|
|
|
"""
|
|
length = self.len
|
|
if isinstance(key, slice):
|
|
step = key.step if key.step is not None else 1
|
|
if step != 1:
|
|
# convert to binary string and use string slicing
|
|
bs = self.__class__()
|
|
if _lsb0:
|
|
start = length - key.start - 1 if key.start is not None else None
|
|
stop = length - key.stop - 1 if key.stop is not None else None
|
|
bs._setbin_unsafe(self._getbin().__getitem__(slice(start, stop, -step))[::-1])
|
|
else:
|
|
bs._setbin_unsafe(self._getbin().__getitem__(key))
|
|
return bs
|
|
start, stop = 0, length
|
|
if key.start is not None:
|
|
start = key.start
|
|
if key.start < 0:
|
|
start += stop
|
|
if key.stop is not None:
|
|
stop = key.stop
|
|
if key.stop < 0:
|
|
stop += length
|
|
start = max(start, 0)
|
|
stop = min(stop, length)
|
|
if start < stop:
|
|
return self._slice(start, stop)
|
|
else:
|
|
return self.__class__()
|
|
else:
|
|
# single element
|
|
if key < 0:
|
|
key += length
|
|
if not 0 <= key < length:
|
|
raise IndexError("Slice index out of range.")
|
|
# Single bit, return True or False
|
|
return self._datastore.getbit(key)
|
|
|
|
def __len__(self):
|
|
"""Return the length of the bitstring in bits."""
|
|
return self._getlength()
|
|
|
|
def __str__(self):
|
|
"""Return approximate string representation of bitstring for printing.
|
|
|
|
Short strings will be given wholly in hexadecimal or binary. Longer
|
|
strings may be part hexadecimal and part binary. Very long strings will
|
|
be truncated with '...'.
|
|
|
|
"""
|
|
length = self.len
|
|
if not length:
|
|
return ''
|
|
if length > MAX_CHARS * 4:
|
|
# Too long for hex. Truncate...
|
|
return ''.join(('0x', self._readhex(MAX_CHARS * 4, 0), '...'))
|
|
# If it's quite short and we can't do hex then use bin
|
|
if length < 32 and length % 4 != 0:
|
|
return '0b' + self.bin
|
|
# If we can use hex then do so
|
|
if not length % 4:
|
|
return '0x' + self.hex
|
|
# Otherwise first we do as much as we can in hex
|
|
# then add on 1, 2 or 3 bits on at the end
|
|
bits_at_end = length % 4
|
|
return ''.join(('0x', self._readhex(length - bits_at_end, 0),
|
|
', ', '0b',
|
|
self._readbin(bits_at_end, length - bits_at_end)))
|
|
|
|
def __repr__(self):
|
|
"""Return representation that could be used to recreate the bitstring.
|
|
|
|
If the returned string is too long it will be truncated. See __str__().
|
|
|
|
"""
|
|
length = self.len
|
|
if isinstance(self._datastore._rawarray, MmapByteArray):
|
|
offsetstring = ''
|
|
if self._datastore.byteoffset or self._offset:
|
|
offsetstring = ", offset=%d" % (self._datastore._rawarray.byteoffset * 8 + self._offset)
|
|
lengthstring = ", length=%d" % length
|
|
return "{0}(filename='{1}'{2}{3})".format(self.__class__.__name__,
|
|
self._datastore._rawarray.source.name, lengthstring, offsetstring)
|
|
else:
|
|
s = self.__str__()
|
|
lengthstring = ''
|
|
if s.endswith('...'):
|
|
lengthstring = " # length={0}".format(length)
|
|
return "{0}('{1}'){2}".format(self.__class__.__name__, s, lengthstring)
|
|
|
|
def __eq__(self, bs):
|
|
"""Return True if two bitstrings have the same binary representation.
|
|
|
|
>>> BitArray('0b1110') == '0xe'
|
|
True
|
|
|
|
"""
|
|
try:
|
|
bs = Bits(bs)
|
|
except TypeError:
|
|
return False
|
|
return equal(self._datastore, bs._datastore)
|
|
|
|
def __ne__(self, bs):
|
|
"""Return False if two bitstrings have the same binary representation.
|
|
|
|
>>> BitArray('0b111') == '0x7'
|
|
False
|
|
|
|
"""
|
|
return not self.__eq__(bs)
|
|
|
|
def __invert__(self):
|
|
"""Return bitstring with every bit inverted.
|
|
|
|
Raises Error if the bitstring is empty.
|
|
|
|
"""
|
|
if not self.len:
|
|
raise Error("Cannot invert empty bitstring.")
|
|
s = self._copy()
|
|
s._invert_all()
|
|
return s
|
|
|
|
def __lshift__(self, n):
|
|
"""Return bitstring with bits shifted by n to the left.
|
|
|
|
n -- the number of bits to shift. Must be >= 0.
|
|
|
|
"""
|
|
if n < 0:
|
|
raise ValueError("Cannot shift by a negative amount.")
|
|
if not self.len:
|
|
raise ValueError("Cannot shift an empty bitstring.")
|
|
n = min(n, self.len)
|
|
s = self._slice(n, self.len)
|
|
s._append(Bits(n))
|
|
return s
|
|
|
|
def __rshift__(self, n):
|
|
"""Return bitstring with bits shifted by n to the right.
|
|
|
|
n -- the number of bits to shift. Must be >= 0.
|
|
|
|
"""
|
|
if n < 0:
|
|
raise ValueError("Cannot shift by a negative amount.")
|
|
if not self.len:
|
|
raise ValueError("Cannot shift an empty bitstring.")
|
|
if not n:
|
|
return self._copy()
|
|
s = self.__class__(length=min(n, self.len))
|
|
s._append(self[:-n])
|
|
return s
|
|
|
|
def __mul__(self, n):
|
|
"""Return bitstring consisting of n concatenations of self.
|
|
|
|
Called for expression of the form 'a = b*3'.
|
|
n -- The number of concatenations. Must be >= 0.
|
|
|
|
"""
|
|
if n < 0:
|
|
raise ValueError("Cannot multiply by a negative integer.")
|
|
if not n:
|
|
return self.__class__()
|
|
s = self._copy()
|
|
s._imul(n)
|
|
return s
|
|
|
|
def __rmul__(self, n):
|
|
"""Return bitstring consisting of n concatenations of self.
|
|
|
|
Called for expressions of the form 'a = 3*b'.
|
|
n -- The number of concatenations. Must be >= 0.
|
|
|
|
"""
|
|
return self.__mul__(n)
|
|
|
|
def __and__(self, bs):
|
|
"""Bit-wise 'and' between two bitstrings. Returns new bitstring.
|
|
|
|
bs -- The bitstring to '&' with.
|
|
|
|
Raises ValueError if the two bitstrings have differing lengths.
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
if self.len != bs.len:
|
|
raise ValueError("Bitstrings must have the same length "
|
|
"for & operator.")
|
|
s = self._copy()
|
|
s._iand(bs)
|
|
return s
|
|
|
|
def __rand__(self, bs):
|
|
"""Bit-wise 'and' between two bitstrings. Returns new bitstring.
|
|
|
|
bs -- the bitstring to '&' with.
|
|
|
|
Raises ValueError if the two bitstrings have differing lengths.
|
|
|
|
"""
|
|
return self.__and__(bs)
|
|
|
|
def __or__(self, bs):
|
|
"""Bit-wise 'or' between two bitstrings. Returns new bitstring.
|
|
|
|
bs -- The bitstring to '|' with.
|
|
|
|
Raises ValueError if the two bitstrings have differing lengths.
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
if self.len != bs.len:
|
|
raise ValueError("Bitstrings must have the same length "
|
|
"for | operator.")
|
|
s = self._copy()
|
|
s._ior(bs)
|
|
return s
|
|
|
|
def __ror__(self, bs):
|
|
"""Bit-wise 'or' between two bitstrings. Returns new bitstring.
|
|
|
|
bs -- The bitstring to '|' with.
|
|
|
|
Raises ValueError if the two bitstrings have differing lengths.
|
|
|
|
"""
|
|
return self.__or__(bs)
|
|
|
|
def __xor__(self, bs):
|
|
"""Bit-wise 'xor' between two bitstrings. Returns new bitstring.
|
|
|
|
bs -- The bitstring to '^' with.
|
|
|
|
Raises ValueError if the two bitstrings have differing lengths.
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
if self.len != bs.len:
|
|
raise ValueError("Bitstrings must have the same length "
|
|
"for ^ operator.")
|
|
s = self._copy()
|
|
s._ixor(bs)
|
|
return s
|
|
|
|
def __rxor__(self, bs):
|
|
"""Bit-wise 'xor' between two bitstrings. Returns new bitstring.
|
|
|
|
bs -- The bitstring to '^' with.
|
|
|
|
Raises ValueError if the two bitstrings have differing lengths.
|
|
|
|
"""
|
|
return self.__xor__(bs)
|
|
|
|
def __contains__(self, bs):
|
|
"""Return whether bs is contained in the current bitstring.
|
|
|
|
bs -- The bitstring to search for.
|
|
|
|
"""
|
|
# Don't want to change pos
|
|
try:
|
|
pos = self._pos
|
|
except AttributeError:
|
|
pass
|
|
found = Bits.find(self, bs, bytealigned=False)
|
|
try:
|
|
self._pos = pos
|
|
except UnboundLocalError:
|
|
pass
|
|
return bool(found)
|
|
|
|
def __hash__(self):
|
|
"""Return an integer hash of the object."""
|
|
# We can't in general hash the whole bitstring (it could take hours!)
|
|
# So instead take some bits from the start and end.
|
|
if self.len <= 160:
|
|
# Use the whole bitstring.
|
|
shorter = self
|
|
else:
|
|
# Take 10 bytes from start and end
|
|
shorter = self[:80] + self[-80:]
|
|
h = 0
|
|
for byte in shorter.tobytes():
|
|
try:
|
|
h = (h << 4) + ord(byte)
|
|
except TypeError:
|
|
# Python 3
|
|
h = (h << 4) + byte
|
|
g = h & 0xf0000000
|
|
if g & (1 << 31):
|
|
h ^= (g >> 24)
|
|
h ^= g
|
|
return h % 1442968193
|
|
|
|
# This is only used in Python 2.x...
|
|
def __nonzero__(self):
|
|
"""Return True if any bits are set to 1, otherwise return False."""
|
|
return self.any(True)
|
|
|
|
# ...whereas this is used in Python 3.x
|
|
__bool__ = __nonzero__
|
|
|
|
def _assertsanity(self):
|
|
"""Check internal self consistency as a debugging aid."""
|
|
assert self.len >= 0
|
|
assert 0 <= self._offset, "offset={0}".format(self._offset)
|
|
assert (self.len + self._offset + 7) // 8 == self._datastore.bytelength + self._datastore.byteoffset, "len={0}, offset={1}, bytelength={2}, byteoffset={3}".format(self.len, self._offset, self._datastore.bytelength, self._datastore.byteoffset)
|
|
return True
|
|
|
|
@classmethod
|
|
def _init_with_token(cls, name, token_length, value):
|
|
if token_length is not None:
|
|
token_length = int(token_length)
|
|
if token_length == 0:
|
|
return cls()
|
|
# For pad token just return the length in zero bits
|
|
if name == 'pad':
|
|
return cls(token_length)
|
|
|
|
if value is None:
|
|
if token_length is None:
|
|
error = "Token has no value ({0}=???).".format(name)
|
|
else:
|
|
error = "Token has no value ({0}:{1}=???).".format(name, token_length)
|
|
raise ValueError(error)
|
|
try:
|
|
b = cls(**{_tokenname_to_initialiser[name]: value})
|
|
except KeyError:
|
|
if name in ('se', 'ue', 'sie', 'uie'):
|
|
b = cls(**{name: int(value)})
|
|
elif name in ('uint', 'int', 'uintbe', 'intbe', 'uintle', 'intle', 'uintne', 'intne'):
|
|
b = cls(**{name: int(value), 'length': token_length})
|
|
elif name in ('float', 'floatbe', 'floatle', 'floatne'):
|
|
b = cls(**{name: float(value), 'length': token_length})
|
|
elif name == 'bool':
|
|
if value in (1, 'True', '1'):
|
|
b = cls(bool=True)
|
|
elif value in (0, 'False', '0'):
|
|
b = cls(bool=False)
|
|
else:
|
|
raise CreationError("bool token can only be 'True' or 'False'.")
|
|
else:
|
|
raise CreationError("Can't parse token name {0}.", name)
|
|
if token_length is not None and b.len != token_length:
|
|
msg = "Token with length {0} packed with value of length {1} ({2}:{3}={4})."
|
|
raise CreationError(msg, token_length, b.len, name, token_length, value)
|
|
return b
|
|
|
|
def _clear(self):
|
|
"""Reset the bitstring to an empty state."""
|
|
self._datastore = ByteStore(bytearray(0))
|
|
|
|
def _setauto(self, s, length, offset):
|
|
"""Set bitstring from a bitstring, file, bool, integer, array, iterable or string."""
|
|
# As s can be so many different things it's important to do the checks
|
|
# in the correct order, as some types are also other allowed types.
|
|
# So basestring must be checked before Iterable
|
|
# and bytes/bytearray before Iterable but after basestring!
|
|
if isinstance(s, Bits):
|
|
if length is None:
|
|
length = s.len - offset
|
|
self._setbytes_unsafe(s._datastore.rawbytes, length, s._offset + offset)
|
|
return
|
|
|
|
if isinstance(s, io.BytesIO):
|
|
if offset is None:
|
|
offset = 0
|
|
if length is None:
|
|
length = s.seek(0, 2) * 8 - offset
|
|
byteoffset, offset = divmod(offset, 8)
|
|
bytelength = (length + byteoffset * 8 + offset + 7) // 8 - byteoffset
|
|
if length + byteoffset * 8 + offset > s.seek(0, 2) * 8:
|
|
raise CreationError("BytesIO object is not long enough for specified "
|
|
"length and offset.")
|
|
self._datastore = ConstByteStore(bytearray(s.getvalue()[byteoffset: byteoffset + bytelength]), length, offset)
|
|
return
|
|
|
|
if isinstance(s, file):
|
|
if offset is None:
|
|
offset = 0
|
|
if length is None:
|
|
length = os.path.getsize(s.name) * 8 - offset
|
|
byteoffset, offset = divmod(offset, 8)
|
|
bytelength = (length + byteoffset * 8 + offset + 7) // 8 - byteoffset
|
|
m = MmapByteArray(s, bytelength, byteoffset)
|
|
if length + byteoffset * 8 + offset > m.filelength * 8:
|
|
raise CreationError("File is not long enough for specified "
|
|
"length and offset.")
|
|
self._datastore = ConstByteStore(m, length, offset)
|
|
return
|
|
|
|
if length is not None:
|
|
raise CreationError("The length keyword isn't applicable to this initialiser.")
|
|
if offset:
|
|
raise CreationError("The offset keyword isn't applicable to this initialiser.")
|
|
if isinstance(s, basestring):
|
|
bs = self._converttobitstring(s)
|
|
assert bs._offset == 0
|
|
self._setbytes_unsafe(bs._datastore.rawbytes, bs.length, 0)
|
|
return
|
|
if isinstance(s, (bytes, bytearray)):
|
|
self._setbytes_unsafe(bytearray(s), len(s) * 8, 0)
|
|
return
|
|
if isinstance(s, array.array):
|
|
try:
|
|
b = s.tobytes()
|
|
except AttributeError:
|
|
b = s.tostring() # Python 2.7
|
|
self._setbytes_unsafe(bytearray(b), len(b) * 8, 0)
|
|
return
|
|
if isinstance(s, numbers.Integral):
|
|
# Initialise with s zero bits.
|
|
if s < 0:
|
|
msg = "Can't create bitstring of negative length {0}."
|
|
raise CreationError(msg, s)
|
|
data = bytearray((s + 7) // 8)
|
|
self._datastore = ByteStore(data, s, 0)
|
|
return
|
|
if isinstance(s, collectionsAbc.Iterable):
|
|
# Evaluate each item as True or False and set bits to 1 or 0.
|
|
self._setbin_unsafe(''.join(str(int(bool(x))) for x in s))
|
|
return
|
|
raise TypeError("Cannot initialise bitstring from {0}.".format(type(s)))
|
|
|
|
def _setfile(self, filename, length, offset):
|
|
"""Use file as source of bits."""
|
|
with open(filename, 'rb') as source:
|
|
if offset is None:
|
|
offset = 0
|
|
if length is None:
|
|
length = os.path.getsize(source.name) * 8 - offset
|
|
byteoffset, offset = divmod(offset, 8)
|
|
bytelength = (length + byteoffset * 8 + offset + 7) // 8 - byteoffset
|
|
m = MmapByteArray(source, bytelength, byteoffset)
|
|
if length + byteoffset * 8 + offset > m.filelength * 8:
|
|
raise CreationError("File is not long enough for specified "
|
|
"length and offset.")
|
|
self._datastore = ConstByteStore(m, length, offset)
|
|
|
|
def _setbytes_safe(self, data, length=None, offset=0):
|
|
"""Set the data from a string."""
|
|
data = bytearray(data)
|
|
if length is None:
|
|
# Use to the end of the data
|
|
length = len(data)*8 - offset
|
|
self._datastore = ByteStore(data, length, offset)
|
|
else:
|
|
if length + offset > len(data) * 8:
|
|
msg = "Not enough data present. Need {0} bits, have {1}."
|
|
raise CreationError(msg, length + offset, len(data) * 8)
|
|
if length == 0:
|
|
self._datastore = ByteStore(bytearray(0))
|
|
else:
|
|
self._datastore = ByteStore(data, length, offset)
|
|
|
|
def _setbytes_unsafe(self, data, length, offset):
|
|
"""Unchecked version of _setbytes_safe."""
|
|
self._datastore = type(self._datastore)(data[:], length, offset)
|
|
assert self._assertsanity()
|
|
|
|
def _readbytes(self, length, start):
|
|
"""Read bytes and return them. Note that length is in bits."""
|
|
assert length % 8 == 0
|
|
assert start + length <= self.len
|
|
if not (start + self._offset) % 8:
|
|
return bytes(self._datastore.getbyteslice((start + self._offset) // 8,
|
|
(start + self._offset + length) // 8))
|
|
return self._slice(start, start + length).tobytes()
|
|
|
|
def _getbytes(self):
|
|
"""Return the data as an ordinary string."""
|
|
if self.len % 8:
|
|
raise InterpretError("Cannot interpret as bytes unambiguously - "
|
|
"not multiple of 8 bits.")
|
|
return self._readbytes(self.len, 0)
|
|
|
|
def _setuint(self, uint, length=None):
|
|
"""Reset the bitstring to have given unsigned int interpretation."""
|
|
try:
|
|
if length is None:
|
|
# Use the whole length. Deliberately not using .len here.
|
|
length = self._datastore.bitlength
|
|
except AttributeError:
|
|
# bitstring doesn't have a _datastore as it hasn't been created!
|
|
pass
|
|
if length is None or length == 0:
|
|
raise CreationError("A non-zero length must be specified with a "
|
|
"uint initialiser.")
|
|
if uint >= (1 << length):
|
|
msg = "{0} is too large an unsigned integer for a bitstring of length {1}. "\
|
|
"The allowed range is [0, {2}]."
|
|
raise CreationError(msg, uint, length, (1 << length) - 1)
|
|
if uint < 0:
|
|
raise CreationError("uint cannot be initialsed by a negative number.")
|
|
s = hex(uint)[2:]
|
|
s = s.rstrip('L')
|
|
if len(s) & 1:
|
|
s = '0' + s
|
|
try:
|
|
data = bytes.fromhex(s)
|
|
except AttributeError:
|
|
# the Python 2.x way
|
|
data = binascii.unhexlify(s)
|
|
# Now add bytes as needed to get the right length.
|
|
extrabytes = ((length + 7) // 8) - len(data)
|
|
if extrabytes > 0:
|
|
data = b'\x00' * extrabytes + data
|
|
offset = 8 - (length % 8)
|
|
if offset == 8:
|
|
offset = 0
|
|
self._setbytes_unsafe(bytearray(data), length, offset)
|
|
|
|
def _readuint(self, length, start):
|
|
"""Read bits and interpret as an unsigned int."""
|
|
if not length:
|
|
raise InterpretError("Cannot interpret a zero length bitstring "
|
|
"as an integer.")
|
|
offset = self._offset
|
|
startbyte = (start + offset) // 8
|
|
endbyte = (start + offset + length - 1) // 8
|
|
|
|
b = binascii.hexlify(bytes(self._datastore.getbyteslice(startbyte, endbyte + 1)))
|
|
assert b
|
|
i = int(b, 16)
|
|
final_bits = 8 - ((start + offset + length) % 8)
|
|
if final_bits != 8:
|
|
i >>= final_bits
|
|
i &= (1 << length) - 1
|
|
return i
|
|
|
|
def _getuint(self):
|
|
"""Return data as an unsigned int."""
|
|
return self._readuint(self.len, 0)
|
|
|
|
def _setint(self, int_, length=None):
|
|
"""Reset the bitstring to have given signed int interpretation."""
|
|
# If no length given, and we've previously been given a length, use it.
|
|
if length is None and hasattr(self, 'len') and self.len != 0:
|
|
length = self.len
|
|
if length is None or length == 0:
|
|
raise CreationError("A non-zero length must be specified with an int initialiser.")
|
|
if int_ >= (1 << (length - 1)) or int_ < -(1 << (length - 1)):
|
|
raise CreationError("{0} is too large a signed integer for a bitstring of length {1}. "
|
|
"The allowed range is [{2}, {3}].", int_, length, -(1 << (length - 1)),
|
|
(1 << (length - 1)) - 1)
|
|
if int_ >= 0:
|
|
self._setuint(int_, length)
|
|
return
|
|
# Do the 2's complement thing. Add one, set to minus number, then flip bits.
|
|
self._setuint((-int_ - 1) ^ ((1 << length) - 1), length)
|
|
|
|
def _readint(self, length, start):
|
|
"""Read bits and interpret as a signed int"""
|
|
ui = self._readuint(length, start)
|
|
if not ui >> (length - 1):
|
|
# Top bit not set, number is positive
|
|
return ui
|
|
# Top bit is set, so number is negative
|
|
tmp = (~(ui - 1)) & ((1 << length) - 1)
|
|
return -tmp
|
|
|
|
def _getint(self):
|
|
"""Return data as a two's complement signed int."""
|
|
return self._readint(self.len, 0)
|
|
|
|
def _setuintbe(self, uintbe, length=None):
|
|
"""Set the bitstring to a big-endian unsigned int interpretation."""
|
|
if length is not None and length % 8 != 0:
|
|
raise CreationError("Big-endian integers must be whole-byte. "
|
|
"Length = {0} bits.", length)
|
|
self._setuint(uintbe, length)
|
|
|
|
def _readuintbe(self, length, start):
|
|
"""Read bits and interpret as a big-endian unsigned int."""
|
|
if length % 8:
|
|
raise InterpretError("Big-endian integers must be whole-byte. "
|
|
"Length = {0} bits.", length)
|
|
return self._readuint(length, start)
|
|
|
|
def _getuintbe(self):
|
|
"""Return data as a big-endian two's complement unsigned int."""
|
|
return self._readuintbe(self.len, 0)
|
|
|
|
def _setintbe(self, intbe, length=None):
|
|
"""Set bitstring to a big-endian signed int interpretation."""
|
|
if length is not None and length % 8 != 0:
|
|
raise CreationError("Big-endian integers must be whole-byte. "
|
|
"Length = {0} bits.", length)
|
|
self._setint(intbe, length)
|
|
|
|
def _readintbe(self, length, start):
|
|
"""Read bits and interpret as a big-endian signed int."""
|
|
if length % 8:
|
|
raise InterpretError("Big-endian integers must be whole-byte. "
|
|
"Length = {0} bits.", length)
|
|
return self._readint(length, start)
|
|
|
|
def _getintbe(self):
|
|
"""Return data as a big-endian two's complement signed int."""
|
|
return self._readintbe(self.len, 0)
|
|
|
|
def _setuintle(self, uintle, length=None):
|
|
if length is not None and length % 8 != 0:
|
|
raise CreationError("Little-endian integers must be whole-byte. "
|
|
"Length = {0} bits.", length)
|
|
self._setuint(uintle, length)
|
|
self._datastore._rawarray = self._datastore._rawarray[::-1]
|
|
|
|
def _readuintle(self, length, start):
|
|
"""Read bits and interpret as a little-endian unsigned int."""
|
|
if length % 8:
|
|
raise InterpretError("Little-endian integers must be whole-byte. "
|
|
"Length = {0} bits.", length)
|
|
assert start + length <= self.len
|
|
absolute_pos = start + self._offset
|
|
startbyte, offset = divmod(absolute_pos, 8)
|
|
val = 0
|
|
if not offset:
|
|
endbyte = (absolute_pos + length - 1) // 8
|
|
chunksize = 4 # for 'L' format
|
|
while endbyte - chunksize + 1 >= startbyte:
|
|
val <<= 8 * chunksize
|
|
val += struct.unpack('<L', bytes(self._datastore.getbyteslice(endbyte + 1 - chunksize, endbyte + 1)))[0]
|
|
endbyte -= chunksize
|
|
for b in xrange(endbyte, startbyte - 1, -1):
|
|
val <<= 8
|
|
val += self._datastore.getbyte(b)
|
|
else:
|
|
data = self._slice(start, start + length)
|
|
assert data.len % 8 == 0
|
|
data._reversebytes(0, self.len)
|
|
for b in bytearray(data.bytes):
|
|
val <<= 8
|
|
val += b
|
|
return val
|
|
|
|
def _getuintle(self):
|
|
return self._readuintle(self.len, 0)
|
|
|
|
def _setintle(self, intle, length=None):
|
|
if length is not None and length % 8 != 0:
|
|
raise CreationError("Little-endian integers must be whole-byte. "
|
|
"Length = {0} bits.", length)
|
|
self._setint(intle, length)
|
|
self._datastore._rawarray = self._datastore._rawarray[::-1]
|
|
|
|
def _readintle(self, length, start):
|
|
"""Read bits and interpret as a little-endian signed int."""
|
|
ui = self._readuintle(length, start)
|
|
if not ui >> (length - 1):
|
|
# Top bit not set, number is positive
|
|
return ui
|
|
# Top bit is set, so number is negative
|
|
tmp = (~(ui - 1)) & ((1 << length) - 1)
|
|
return -tmp
|
|
|
|
def _getintle(self):
|
|
return self._readintle(self.len, 0)
|
|
|
|
def _setfloat(self, f, length=None):
|
|
# If no length given, and we've previously been given a length, use it.
|
|
if length is None and hasattr(self, 'len') and self.len != 0:
|
|
length = self.len
|
|
if length is None or length == 0:
|
|
raise CreationError("A non-zero length must be specified with a "
|
|
"float initialiser.")
|
|
if length == 32:
|
|
b = struct.pack('>f', f)
|
|
elif length == 64:
|
|
b = struct.pack('>d', f)
|
|
else:
|
|
raise CreationError("floats can only be 32 or 64 bits long, "
|
|
"not {0} bits", length)
|
|
self._setbytes_unsafe(bytearray(b), length, 0)
|
|
|
|
def _readfloat(self, length, start):
|
|
"""Read bits and interpret as a float."""
|
|
if not (start + self._offset) % 8:
|
|
startbyte = (start + self._offset) // 8
|
|
if length == 32:
|
|
f, = struct.unpack('>f', bytes(self._datastore.getbyteslice(startbyte, startbyte + 4)))
|
|
elif length == 64:
|
|
f, = struct.unpack('>d', bytes(self._datastore.getbyteslice(startbyte, startbyte + 8)))
|
|
else:
|
|
if length == 32:
|
|
f, = struct.unpack('>f', self._readbytes(32, start))
|
|
elif length == 64:
|
|
f, = struct.unpack('>d', self._readbytes(64, start))
|
|
try:
|
|
return f
|
|
except NameError:
|
|
raise InterpretError("floats can only be 32 or 64 bits long, not {0} bits", length)
|
|
|
|
def _getfloat(self):
|
|
"""Interpret the whole bitstring as a float."""
|
|
return self._readfloat(self.len, 0)
|
|
|
|
def _setfloatle(self, f, length=None):
|
|
# If no length given, and we've previously been given a length, use it.
|
|
if length is None and hasattr(self, 'len') and self.len != 0:
|
|
length = self.len
|
|
if length is None or length == 0:
|
|
raise CreationError("A non-zero length must be specified with a "
|
|
"float initialiser.")
|
|
if length == 32:
|
|
b = struct.pack('<f', f)
|
|
elif length == 64:
|
|
b = struct.pack('<d', f)
|
|
else:
|
|
raise CreationError("floats can only be 32 or 64 bits long, "
|
|
"not {0} bits", length)
|
|
self._setbytes_unsafe(bytearray(b), length, 0)
|
|
|
|
def _readfloatle(self, length, start):
|
|
"""Read bits and interpret as a little-endian float."""
|
|
startbyte, offset = divmod(start + self._offset, 8)
|
|
if not offset:
|
|
if length == 32:
|
|
f, = struct.unpack('<f', bytes(self._datastore.getbyteslice(startbyte, startbyte + 4)))
|
|
elif length == 64:
|
|
f, = struct.unpack('<d', bytes(self._datastore.getbyteslice(startbyte, startbyte + 8)))
|
|
else:
|
|
if length == 32:
|
|
f, = struct.unpack('<f', self._readbytes(32, start))
|
|
elif length == 64:
|
|
f, = struct.unpack('<d', self._readbytes(64, start))
|
|
try:
|
|
return f
|
|
except NameError:
|
|
raise InterpretError("floats can only be 32 or 64 bits long, "
|
|
"not {0} bits", length)
|
|
|
|
def _getfloatle(self):
|
|
"""Interpret the whole bitstring as a little-endian float."""
|
|
return self._readfloatle(self.len, 0)
|
|
|
|
def _setue(self, i):
|
|
"""Initialise bitstring with unsigned exponential-Golomb code for integer i.
|
|
|
|
Raises CreationError if i < 0.
|
|
|
|
"""
|
|
if i < 0:
|
|
raise CreationError("Cannot use negative initialiser for unsigned "
|
|
"exponential-Golomb.")
|
|
if not i:
|
|
self._setbin_unsafe('1')
|
|
return
|
|
tmp = i + 1
|
|
leadingzeros = -1
|
|
while tmp > 0:
|
|
tmp >>= 1
|
|
leadingzeros += 1
|
|
remainingpart = i + 1 - (1 << leadingzeros)
|
|
binstring = '0' * leadingzeros + '1' + Bits(uint=remainingpart,
|
|
length=leadingzeros).bin
|
|
self._setbin_unsafe(binstring)
|
|
|
|
def _readue(self, pos):
|
|
"""Return interpretation of next bits as unsigned exponential-Golomb code.
|
|
|
|
Raises ReadError if the end of the bitstring is encountered while
|
|
reading the code.
|
|
|
|
"""
|
|
oldpos = pos
|
|
try:
|
|
while not self[pos]:
|
|
pos += 1
|
|
except IndexError:
|
|
raise ReadError("Read off end of bitstring trying to read code.")
|
|
leadingzeros = pos - oldpos
|
|
codenum = (1 << leadingzeros) - 1
|
|
if leadingzeros > 0:
|
|
if pos + leadingzeros + 1 > self.len:
|
|
raise ReadError("Read off end of bitstring trying to read code.")
|
|
codenum += self._readuint(leadingzeros, pos + 1)
|
|
pos += leadingzeros + 1
|
|
else:
|
|
assert codenum == 0
|
|
pos += 1
|
|
return codenum, pos
|
|
|
|
def _getue(self):
|
|
"""Return data as unsigned exponential-Golomb code.
|
|
|
|
Raises InterpretError if bitstring is not a single exponential-Golomb code.
|
|
|
|
"""
|
|
try:
|
|
value, newpos = self._readue(0)
|
|
if value is None or newpos != self.len:
|
|
raise ReadError
|
|
except ReadError:
|
|
raise InterpretError("Bitstring is not a single exponential-Golomb code.")
|
|
return value
|
|
|
|
def _setse(self, i):
|
|
"""Initialise bitstring with signed exponential-Golomb code for integer i."""
|
|
if i > 0:
|
|
u = (i * 2) - 1
|
|
else:
|
|
u = -2 * i
|
|
self._setue(u)
|
|
|
|
def _getse(self):
|
|
"""Return data as signed exponential-Golomb code.
|
|
|
|
Raises InterpretError if bitstring is not a single exponential-Golomb code.
|
|
|
|
"""
|
|
try:
|
|
value, newpos = self._readse(0)
|
|
if value is None or newpos != self.len:
|
|
raise ReadError
|
|
except ReadError:
|
|
raise InterpretError("Bitstring is not a single exponential-Golomb code.")
|
|
return value
|
|
|
|
def _readse(self, pos):
|
|
"""Return interpretation of next bits as a signed exponential-Golomb code.
|
|
|
|
Advances position to after the read code.
|
|
|
|
Raises ReadError if the end of the bitstring is encountered while
|
|
reading the code.
|
|
|
|
"""
|
|
codenum, pos = self._readue(pos)
|
|
m = (codenum + 1) // 2
|
|
if not codenum % 2:
|
|
return -m, pos
|
|
else:
|
|
return m, pos
|
|
|
|
def _setuie(self, i):
|
|
"""Initialise bitstring with unsigned interleaved exponential-Golomb code for integer i.
|
|
|
|
Raises CreationError if i < 0.
|
|
|
|
"""
|
|
if i < 0:
|
|
raise CreationError("Cannot use negative initialiser for unsigned "
|
|
"interleaved exponential-Golomb.")
|
|
self._setbin_unsafe('1' if i == 0 else '0' + '0'.join(bin(i + 1)[3:]) + '1')
|
|
|
|
def _readuie(self, pos):
|
|
"""Return interpretation of next bits as unsigned interleaved exponential-Golomb code.
|
|
|
|
Raises ReadError if the end of the bitstring is encountered while
|
|
reading the code.
|
|
|
|
"""
|
|
try:
|
|
codenum = 1
|
|
while not self[pos]:
|
|
pos += 1
|
|
codenum <<= 1
|
|
codenum += self[pos]
|
|
pos += 1
|
|
pos += 1
|
|
except IndexError:
|
|
raise ReadError("Read off end of bitstring trying to read code.")
|
|
codenum -= 1
|
|
return codenum, pos
|
|
|
|
def _getuie(self):
|
|
"""Return data as unsigned interleaved exponential-Golomb code.
|
|
|
|
Raises InterpretError if bitstring is not a single exponential-Golomb code.
|
|
|
|
"""
|
|
try:
|
|
value, newpos = self._readuie(0)
|
|
if value is None or newpos != self.len:
|
|
raise ReadError
|
|
except ReadError:
|
|
raise InterpretError("Bitstring is not a single interleaved exponential-Golomb code.")
|
|
return value
|
|
|
|
def _setsie(self, i):
|
|
"""Initialise bitstring with signed interleaved exponential-Golomb code for integer i."""
|
|
if not i:
|
|
self._setbin_unsafe('1')
|
|
else:
|
|
self._setuie(abs(i))
|
|
self._append(Bits([i < 0]))
|
|
|
|
def _getsie(self):
|
|
"""Return data as signed interleaved exponential-Golomb code.
|
|
|
|
Raises InterpretError if bitstring is not a single exponential-Golomb code.
|
|
|
|
"""
|
|
try:
|
|
value, newpos = self._readsie(0)
|
|
if value is None or newpos != self.len:
|
|
raise ReadError
|
|
except ReadError:
|
|
raise InterpretError("Bitstring is not a single interleaved exponential-Golomb code.")
|
|
return value
|
|
|
|
def _readsie(self, pos):
|
|
"""Return interpretation of next bits as a signed interleaved exponential-Golomb code.
|
|
|
|
Advances position to after the read code.
|
|
|
|
Raises ReadError if the end of the bitstring is encountered while
|
|
reading the code.
|
|
|
|
"""
|
|
codenum, pos = self._readuie(pos)
|
|
if not codenum:
|
|
return 0, pos
|
|
try:
|
|
if self[pos]:
|
|
return -codenum, pos + 1
|
|
else:
|
|
return codenum, pos + 1
|
|
except IndexError:
|
|
raise ReadError("Read off end of bitstring trying to read code.")
|
|
|
|
def _setbool(self, value):
|
|
# We deliberately don't want to have implicit conversions to bool here.
|
|
# If we did then it would be difficult to deal with the 'False' string.
|
|
if value in (1, 'True'):
|
|
self._setbytes_unsafe(bytearray(b'\x80'), 1, 0)
|
|
elif value in (0, 'False'):
|
|
self._setbytes_unsafe(bytearray(b'\x00'), 1, 0)
|
|
else:
|
|
raise CreationError('Cannot initialise boolean with {0}.', value)
|
|
|
|
def _getbool(self):
|
|
if self.length != 1:
|
|
msg = "For a bool interpretation a bitstring must be 1 bit long, not {0} bits."
|
|
raise InterpretError(msg, self.length)
|
|
return self[0]
|
|
|
|
def _readbool(self, pos):
|
|
return self[pos], pos + 1
|
|
|
|
def _setbin_safe(self, binstring):
|
|
"""Reset the bitstring to the value given in binstring."""
|
|
binstring = tidy_input_string(binstring)
|
|
# remove any 0b if present
|
|
binstring = binstring.replace('0b', '')
|
|
self._setbin_unsafe(binstring)
|
|
|
|
def _setbin_unsafe(self, binstring):
|
|
"""Same as _setbin_safe, but input isn't sanity checked. binstring mustn't start with '0b'."""
|
|
length = len(binstring)
|
|
# pad with zeros up to byte boundary if needed
|
|
boundary = ((length + 7) // 8) * 8
|
|
padded_binstring = binstring + '0' * (boundary - length)\
|
|
if len(binstring) < boundary else binstring
|
|
try:
|
|
bytelist = [int(padded_binstring[x:x + 8], 2)
|
|
for x in xrange(0, len(padded_binstring), 8)]
|
|
except ValueError:
|
|
raise CreationError("Invalid character in bin initialiser {0}.", binstring)
|
|
self._setbytes_unsafe(bytearray(bytelist), length, 0)
|
|
|
|
def _readbin(self, length, start):
|
|
"""Read bits and interpret as a binary string."""
|
|
if not length:
|
|
return ''
|
|
# Get the byte slice containing our bit slice
|
|
startbyte, startoffset = divmod(start + self._offset, 8)
|
|
endbyte = (start + self._offset + length - 1) // 8
|
|
b = self._datastore.getbyteslice(startbyte, endbyte + 1)
|
|
# Convert to a string of '0' and '1's (via a hex string an and int!)
|
|
c = "{:0{}b}".format(int(binascii.hexlify(b), 16), 8*len(b))
|
|
# Finally chop off any extra bits.
|
|
return c[startoffset:startoffset + length]
|
|
|
|
def _getbin(self):
|
|
"""Return interpretation as a binary string."""
|
|
return self._readbin(self.len, 0)
|
|
|
|
def _setoct(self, octstring):
|
|
"""Reset the bitstring to have the value given in octstring."""
|
|
octstring = tidy_input_string(octstring)
|
|
# remove any 0o if present
|
|
octstring = octstring.replace('0o', '')
|
|
binlist = []
|
|
for i in octstring:
|
|
try:
|
|
binlist.append(OCT_TO_BITS[int(i)])
|
|
except (ValueError, IndexError):
|
|
raise CreationError("Invalid symbol '{0}' in oct initialiser.", i)
|
|
|
|
self._setbin_unsafe(''.join(binlist))
|
|
|
|
def _readoct(self, length, start):
|
|
"""Read bits and interpret as an octal string."""
|
|
if length % 3:
|
|
raise InterpretError("Cannot convert to octal unambiguously - "
|
|
"not multiple of 3 bits.")
|
|
if not length:
|
|
return ''
|
|
# Get main octal bit by converting from int.
|
|
# Strip starting 0 or 0o depending on Python version.
|
|
end = oct(self._readuint(length, start))[LEADING_OCT_CHARS:]
|
|
if end.endswith('L'):
|
|
end = end[:-1]
|
|
middle = '0' * (length // 3 - len(end))
|
|
return middle + end
|
|
|
|
def _getoct(self):
|
|
"""Return interpretation as an octal string."""
|
|
return self._readoct(self.len, 0)
|
|
|
|
def _sethex(self, hexstring):
|
|
"""Reset the bitstring to have the value given in hexstring."""
|
|
hexstring = tidy_input_string(hexstring)
|
|
# remove any 0x if present
|
|
hexstring = hexstring.replace('0x', '')
|
|
length = len(hexstring)
|
|
if length % 2:
|
|
hexstring += '0'
|
|
try:
|
|
data = bytearray.fromhex(hexstring)
|
|
except ValueError:
|
|
raise CreationError("Invalid symbol in hex initialiser.")
|
|
self._setbytes_unsafe(data, length * 4, 0)
|
|
|
|
def _readhex(self, length, start):
|
|
"""Read bits and interpret as a hex string."""
|
|
if length % 4:
|
|
raise InterpretError("Cannot convert to hex unambiguously - "
|
|
"not multiple of 4 bits.")
|
|
if not length:
|
|
return ''
|
|
s = self._slice(start, start + length).tobytes()
|
|
try:
|
|
s = s.hex() # Available in Python 3.5+
|
|
except AttributeError:
|
|
# This monstrosity is the only thing I could get to work for both 2.6 and 3.1.
|
|
s = str(binascii.hexlify(s).decode('utf-8'))
|
|
# If there's one nibble too many then cut it off
|
|
return s[:-1] if (length // 4) % 2 else s
|
|
|
|
def _gethex(self):
|
|
"""Return the hexadecimal representation as a string prefixed with '0x'.
|
|
|
|
Raises an InterpretError if the bitstring's length is not a multiple of 4.
|
|
|
|
"""
|
|
return self._readhex(self.len, 0)
|
|
|
|
def _getoffset(self):
|
|
return self._datastore.offset
|
|
|
|
def _getlength(self):
|
|
"""Return the length of the bitstring in bits."""
|
|
return self._datastore.bitlength
|
|
|
|
def _ensureinmemory(self):
|
|
"""Ensure the data is held in memory, not in a file."""
|
|
self._setbytes_unsafe(self._datastore.getbyteslice(0, self._datastore.bytelength),
|
|
self.len, self._offset)
|
|
|
|
@classmethod
|
|
def _converttobitstring(cls, bs, offset=0, cache={}):
|
|
"""Convert bs to a bitstring and return it.
|
|
|
|
offset gives the suggested bit offset of first significant
|
|
bit, to optimise append etc.
|
|
|
|
"""
|
|
if isinstance(bs, Bits):
|
|
return bs
|
|
try:
|
|
return cache[(bs, offset)]
|
|
except KeyError:
|
|
if isinstance(bs, basestring):
|
|
b = cls()
|
|
try:
|
|
_, tokens = tokenparser(bs)
|
|
except ValueError as e:
|
|
raise CreationError(*e.args)
|
|
if tokens:
|
|
b._append(Bits._init_with_token(*tokens[0]))
|
|
b._datastore = offsetcopy(b._datastore, offset)
|
|
for token in tokens[1:]:
|
|
b._append(Bits._init_with_token(*token))
|
|
assert b._assertsanity()
|
|
assert b.len == 0 or b._offset == offset
|
|
if len(cache) < CACHE_SIZE:
|
|
cache[(bs, offset)] = b
|
|
return b
|
|
except TypeError:
|
|
# Unhashable type
|
|
pass
|
|
return cls(bs)
|
|
|
|
def _copy(self):
|
|
"""Create and return a new copy of the Bits (always in memory)."""
|
|
s_copy = self.__class__()
|
|
s_copy._setbytes_unsafe(self._datastore.getbyteslice(0, self._datastore.bytelength),
|
|
self.len, self._offset)
|
|
return s_copy
|
|
|
|
def _slice_lsb0(self, start, end):
|
|
"""Used internally to get a slice, without error checking (LSB0)."""
|
|
return self._slice_msb0(self.length - end, self.length - start)
|
|
|
|
def _slice_msb0(self, start, end):
|
|
"""Used internally to get a slice, without error checking."""
|
|
if end == start:
|
|
return self.__class__()
|
|
assert start < end, "start={0}, end={1}".format(start, end)
|
|
offset = self._offset
|
|
startbyte, newoffset = divmod(start + offset, 8)
|
|
endbyte = (end + offset - 1) // 8
|
|
bs = self.__class__()
|
|
bs._setbytes_unsafe(self._datastore.getbyteslice(startbyte, endbyte + 1), end - start, newoffset)
|
|
return bs
|
|
|
|
def _readtoken(self, name, pos, length):
|
|
"""Reads a token from the bitstring and returns the result."""
|
|
if length is not None and int(length) > self.length - pos:
|
|
raise ReadError("Reading off the end of the data. "
|
|
"Tried to read {0} bits when only {1} available.".format(int(length), self.length - pos))
|
|
try:
|
|
val = name_to_read[name](self, length, pos)
|
|
return val, pos + length
|
|
except KeyError:
|
|
if name == 'pad':
|
|
return None, pos + length
|
|
raise ValueError("Can't parse token {0}:{1}".format(name, length))
|
|
except TypeError:
|
|
# This is for the 'ue', 'se' and 'bool' tokens. They will also return the new pos.
|
|
return name_to_read[name](self, pos)
|
|
|
|
def _append(self, bs):
|
|
"""Append a bitstring to the current bitstring."""
|
|
self._datastore._appendstore(bs._datastore)
|
|
|
|
def _prepend(self, bs):
|
|
"""Prepend a bitstring to the current bitstring."""
|
|
self._datastore._prependstore(bs._datastore)
|
|
|
|
def _reverse(self):
|
|
"""Reverse all bits in-place."""
|
|
# Reverse the contents of each byte
|
|
n = [BYTE_REVERSAL_DICT[b] for b in self._datastore.rawbytes]
|
|
# Then reverse the order of the bytes
|
|
n.reverse()
|
|
# The new offset is the number of bits that were unused at the end.
|
|
newoffset = 8 - (self._offset + self.len) % 8
|
|
if newoffset == 8:
|
|
newoffset = 0
|
|
self._setbytes_unsafe(bytearray().join(n), self.length, newoffset)
|
|
|
|
def _truncateleft(self, bits):
|
|
"""Truncate bits from the LHS of the bitstring."""
|
|
assert 0 <= bits <= self.len
|
|
if not bits:
|
|
return
|
|
if bits == self.len:
|
|
self._clear()
|
|
return
|
|
bytepos, offset = divmod(self._offset + bits, 8)
|
|
self._setbytes_unsafe(self._datastore.getbyteslice(bytepos, self._datastore.bytelength), self.len - bits,
|
|
offset)
|
|
assert self._assertsanity()
|
|
|
|
def _truncateright(self, bits):
|
|
"""Truncate bits from the RHS of the bitstring."""
|
|
assert 0 <= bits <= self.len
|
|
if not bits:
|
|
return
|
|
if bits == self.len:
|
|
self._clear()
|
|
return
|
|
newlength_in_bytes = (self._offset + self.len - bits + 7) // 8
|
|
self._setbytes_unsafe(self._datastore.getbyteslice(0, newlength_in_bytes), self.len - bits,
|
|
self._offset)
|
|
assert self._assertsanity()
|
|
|
|
def _insert_lsb0(self, bs, pos):
|
|
"""Insert bs at pos (LSB0)."""
|
|
self._insert_msb0(bs, self.len - pos)
|
|
|
|
def _insert_msb0(self, bs, pos):
|
|
"""Insert bs at pos."""
|
|
assert 0 <= pos <= self.len
|
|
if pos > self.len // 2:
|
|
# Inserting nearer end, so cut off end.
|
|
end = self._slice(pos, self.len)
|
|
self._truncateright(self.len - pos)
|
|
self._append(bs)
|
|
self._append(end)
|
|
else:
|
|
# Inserting nearer start, so cut off start.
|
|
start = self._slice(0, pos)
|
|
self._truncateleft(pos)
|
|
self._prepend(bs)
|
|
self._prepend(start)
|
|
try:
|
|
self._pos = pos + bs.len
|
|
except AttributeError:
|
|
pass
|
|
assert self._assertsanity()
|
|
|
|
def _overwrite_lsb0(self, bs, pos):
|
|
"""Overwrite with bs at pos (LSB0)."""
|
|
self._overwrite_msb0(bs, self.len - pos - bs.len)
|
|
|
|
def _overwrite_msb0(self, bs, pos):
|
|
"""Overwrite with bs at pos."""
|
|
assert 0 <= pos < self.len
|
|
if bs is self:
|
|
# Just overwriting with self, so do nothing.
|
|
assert pos == 0
|
|
return
|
|
firstbytepos = (self._offset + pos) // 8
|
|
lastbytepos = (self._offset + pos + bs.len - 1) // 8
|
|
bytepos, bitoffset = divmod(self._offset + pos, 8)
|
|
if firstbytepos == lastbytepos:
|
|
mask = ((1 << bs.len) - 1) << (8 - bs.len - bitoffset)
|
|
self._datastore.setbyte(bytepos, self._datastore.getbyte(bytepos) & (~mask))
|
|
d = offsetcopy(bs._datastore, bitoffset)
|
|
self._datastore.setbyte(bytepos, self._datastore.getbyte(bytepos) | (d.getbyte(0) & mask))
|
|
else:
|
|
# Do first byte
|
|
mask = (1 << (8 - bitoffset)) - 1
|
|
self._datastore.setbyte(bytepos, self._datastore.getbyte(bytepos) & (~mask))
|
|
d = offsetcopy(bs._datastore, bitoffset)
|
|
self._datastore.setbyte(bytepos, self._datastore.getbyte(bytepos) | (d.getbyte(0) & mask))
|
|
# Now do all the full bytes
|
|
self._datastore.setbyteslice(firstbytepos + 1, lastbytepos, d.getbyteslice(1, lastbytepos - firstbytepos))
|
|
# and finally the last byte
|
|
bitsleft = (self._offset + pos + bs.len) % 8
|
|
if not bitsleft:
|
|
bitsleft = 8
|
|
mask = (1 << (8 - bitsleft)) - 1
|
|
self._datastore.setbyte(lastbytepos, self._datastore.getbyte(lastbytepos) & mask)
|
|
self._datastore.setbyte(lastbytepos,
|
|
self._datastore.getbyte(lastbytepos) | (d.getbyte(d.bytelength - 1) & ~mask))
|
|
assert self._assertsanity()
|
|
|
|
def _delete_lsb0(self, bits, pos):
|
|
"""Delete bits at pos (LSB0)."""
|
|
self._delete_msb0(bits, self.len - pos - bits)
|
|
|
|
def _delete_msb0(self, bits, pos):
|
|
"""Delete bits at pos."""
|
|
assert 0 <= pos <= self.len
|
|
assert pos + bits <= self.len, "pos={}, bits={}, len={}".format(pos, bits, self.len)
|
|
if not pos:
|
|
# Cutting bits off at the start.
|
|
self._truncateleft(bits)
|
|
return
|
|
if pos + bits == self.len:
|
|
# Cutting bits off at the end.
|
|
self._truncateright(bits)
|
|
return
|
|
if pos > self.len - pos - bits:
|
|
# More bits before cut point than after it, so do bit shifting
|
|
# on the final bits.
|
|
end = self._slice_msb0(pos + bits, self.len)
|
|
assert self.len - pos > 0
|
|
self._truncateright(self.len - pos)
|
|
self._append(end)
|
|
return
|
|
# More bits after the cut point than before it.
|
|
start = self._slice_msb0(0, pos)
|
|
self._truncateleft(pos + bits)
|
|
self._prepend(start)
|
|
return
|
|
|
|
def _reversebytes(self, start, end):
|
|
"""Reverse bytes in-place."""
|
|
# Make the start occur on a byte boundary
|
|
# TODO: We could be cleverer here to avoid changing the offset.
|
|
newoffset = 8 - (start % 8)
|
|
if newoffset == 8:
|
|
newoffset = 0
|
|
self._datastore = offsetcopy(self._datastore, newoffset)
|
|
# Now just reverse the byte data
|
|
toreverse = bytearray(self._datastore.getbyteslice((newoffset + start) // 8, (newoffset + end) // 8))
|
|
toreverse.reverse()
|
|
self._datastore.setbyteslice((newoffset + start) // 8, (newoffset + end) // 8, toreverse)
|
|
|
|
def _set(self, pos):
|
|
"""Set bit at pos to 1."""
|
|
assert 0 <= pos < self.len
|
|
self._datastore.setbit(pos)
|
|
|
|
def _unset(self, pos):
|
|
"""Set bit at pos to 0."""
|
|
assert 0 <= pos < self.len
|
|
self._datastore.unsetbit(pos)
|
|
|
|
def _invert(self, pos):
|
|
"""Flip bit at pos 1<->0."""
|
|
assert 0 <= pos < self.len
|
|
self._datastore.invertbit(pos)
|
|
|
|
def _invert_all(self):
|
|
"""Invert every bit."""
|
|
for p in xrange(self._datastore.byteoffset, self._datastore.byteoffset + self._datastore.bytelength):
|
|
self._datastore._rawarray[p] = 256 + ~self._datastore._rawarray[p]
|
|
|
|
def _ilshift(self, n):
|
|
"""Shift bits by n to the left in place. Return self."""
|
|
assert 0 < n <= self.len
|
|
self._append(Bits(n))
|
|
self._truncateleft(n)
|
|
return self
|
|
|
|
def _irshift(self, n):
|
|
"""Shift bits by n to the right in place. Return self."""
|
|
assert 0 < n <= self.len
|
|
self._prepend(Bits(n))
|
|
self._truncateright(n)
|
|
return self
|
|
|
|
def _imul(self, n):
|
|
"""Concatenate n copies of self in place. Return self."""
|
|
assert n >= 0
|
|
if not n:
|
|
self._clear()
|
|
return self
|
|
m = 1
|
|
old_len = self.len
|
|
while m * 2 < n:
|
|
self._append(self)
|
|
m *= 2
|
|
self._append(self[0:(n - m) * old_len])
|
|
return self
|
|
|
|
def _inplace_logical_helper(self, bs, f):
|
|
"""Helper function containing most of the __ior__, __iand__, __ixor__ code."""
|
|
# Give the two bitstrings the same offset (modulo 8)
|
|
self_byteoffset, self_bitoffset = divmod(self._offset, 8)
|
|
bs_byteoffset, bs_bitoffset = divmod(bs._offset, 8)
|
|
if bs_bitoffset != self_bitoffset:
|
|
if not self_bitoffset:
|
|
bs._datastore = offsetcopy(bs._datastore, 0)
|
|
else:
|
|
self._datastore = offsetcopy(self._datastore, bs_bitoffset)
|
|
a = self._datastore.rawbytes
|
|
b = bs._datastore.rawbytes
|
|
for i in xrange(len(a)):
|
|
a[i] = f(a[i + self_byteoffset], b[i + bs_byteoffset])
|
|
return self
|
|
|
|
def _ior(self, bs):
|
|
return self._inplace_logical_helper(bs, operator.ior)
|
|
|
|
def _iand(self, bs):
|
|
return self._inplace_logical_helper(bs, operator.iand)
|
|
|
|
def _ixor(self, bs):
|
|
return self._inplace_logical_helper(bs, operator.xor)
|
|
|
|
def _readbits(self, length, start):
|
|
"""Read some bits from the bitstring and return newly constructed bitstring."""
|
|
return self._slice(start, start + length)
|
|
|
|
def _validate_slice(self, start, end):
|
|
"""Validate start and end and return them as positive bit positions."""
|
|
if start is None:
|
|
start = 0
|
|
elif start < 0:
|
|
start += self.len
|
|
if end is None:
|
|
end = self.len
|
|
elif end < 0:
|
|
end += self.len
|
|
if not 0 <= end <= self.len:
|
|
raise ValueError("end is not a valid position in the bitstring.")
|
|
if not 0 <= start <= self.len:
|
|
raise ValueError("start is not a valid position in the bitstring.")
|
|
if end < start:
|
|
raise ValueError("end must not be less than start.")
|
|
return start, end
|
|
|
|
def unpack(self, fmt, **kwargs):
|
|
"""Interpret the whole bitstring using fmt and return list.
|
|
|
|
fmt -- A single string or a list of strings with comma separated tokens
|
|
describing how to interpret the bits in the bitstring. Items
|
|
can also be integers, for reading new bitstring of the given length.
|
|
kwargs -- A dictionary or keyword-value pairs - the keywords used in the
|
|
format string will be replaced with their given value.
|
|
|
|
Raises ValueError if the format is not understood. If not enough bits
|
|
are available then all bits to the end of the bitstring will be used.
|
|
|
|
See the docstring for 'read' for token examples.
|
|
|
|
"""
|
|
return self._readlist(fmt, 0, **kwargs)[0]
|
|
|
|
def _readlist(self, fmt, pos, **kwargs):
|
|
tokens = []
|
|
stretchy_token = None
|
|
if isinstance(fmt, basestring):
|
|
fmt = [fmt]
|
|
# Replace integers with 'bits' tokens
|
|
for i, f in enumerate(fmt):
|
|
if isinstance(f, numbers.Integral):
|
|
fmt[i] = "bits:{0}".format(f)
|
|
for f_item in fmt:
|
|
stretchy, tkns = tokenparser(f_item, tuple(sorted(kwargs.keys())))
|
|
if stretchy:
|
|
if stretchy_token:
|
|
raise Error("It's not possible to have more than one 'filler' token.")
|
|
stretchy_token = stretchy
|
|
tokens.extend(tkns)
|
|
if not stretchy_token:
|
|
lst = []
|
|
for name, length, _ in tokens:
|
|
if length in kwargs:
|
|
length = kwargs[length]
|
|
if name == 'bytes':
|
|
length *= 8
|
|
if name in kwargs and length is None:
|
|
# Using default 'uint' - the name is really the length.
|
|
value, pos = self._readtoken('uint', pos, kwargs[name])
|
|
lst.append(value)
|
|
continue
|
|
value, pos = self._readtoken(name, pos, length)
|
|
if value is not None: # Don't append pad tokens
|
|
lst.append(value)
|
|
return lst, pos
|
|
stretchy_token = False
|
|
bits_after_stretchy_token = 0
|
|
for token in tokens:
|
|
name, length, _ = token
|
|
if length in kwargs:
|
|
length = kwargs[length]
|
|
if name == 'bytes':
|
|
length *= 8
|
|
if name in kwargs and length is None:
|
|
# Default 'uint'.
|
|
length = kwargs[name]
|
|
if stretchy_token:
|
|
if name in ('se', 'ue', 'sie', 'uie'):
|
|
raise Error("It's not possible to parse a variable"
|
|
"length token after a 'filler' token.")
|
|
else:
|
|
if length is None:
|
|
raise Error("It's not possible to have more than "
|
|
"one 'filler' token.")
|
|
bits_after_stretchy_token += length
|
|
if length is None and name not in ('se', 'ue', 'sie', 'uie'):
|
|
assert not stretchy_token
|
|
stretchy_token = token
|
|
bits_left = self.len - pos
|
|
return_values = []
|
|
for token in tokens:
|
|
name, length, _ = token
|
|
if token is stretchy_token:
|
|
# Set length to the remaining bits
|
|
length = max(bits_left - bits_after_stretchy_token, 0)
|
|
if length in kwargs:
|
|
length = kwargs[length]
|
|
if name == 'bytes':
|
|
length *= 8
|
|
if name in kwargs and length is None:
|
|
# Default 'uint'
|
|
length = kwargs[name]
|
|
if length is not None:
|
|
bits_left -= length
|
|
value, pos = self._readtoken(name, pos, length)
|
|
if value is not None:
|
|
return_values.append(value)
|
|
return return_values, pos
|
|
|
|
def _findbytes(self, bytes_, start, end, bytealigned):
|
|
"""Quicker version of find when everything's whole byte
|
|
and byte aligned.
|
|
|
|
"""
|
|
assert self._datastore.offset == 0
|
|
assert bytealigned is True
|
|
# Extract data bytes from bitstring to be found.
|
|
bytepos = (start + 7) // 8
|
|
found = False
|
|
p = bytepos
|
|
finalpos = end // 8
|
|
increment = max(1024, len(bytes_) * 10)
|
|
buffersize = increment + len(bytes_)
|
|
while p < finalpos:
|
|
# Read in file or from memory in overlapping chunks and search the chunks.
|
|
buf = bytearray(self._datastore.getbyteslice(p, min(p + buffersize, finalpos)))
|
|
pos = buf.find(bytes_)
|
|
if pos != -1:
|
|
found = True
|
|
p += pos
|
|
break
|
|
p += increment
|
|
if not found:
|
|
return ()
|
|
return (p * 8,)
|
|
|
|
def _findregex(self, reg_ex, start, end, bytealigned):
|
|
"""Find first occurrence of a compiled regular expression.
|
|
|
|
Note that this doesn't support arbitrary regexes, in particular they
|
|
must match a known length.
|
|
|
|
"""
|
|
p = start
|
|
length = len(reg_ex.pattern)
|
|
# We grab overlapping chunks of the binary representation and
|
|
# do an ordinary string search within that.
|
|
increment = max(4096, length * 10)
|
|
buffersize = increment + length
|
|
while p < end:
|
|
buf = self._readbin(min(buffersize, end - p), p)
|
|
# Test using regular expressions...
|
|
m = reg_ex.search(buf)
|
|
if m:
|
|
pos = m.start()
|
|
# pos = buf.find(targetbin)
|
|
# if pos != -1:
|
|
# if bytealigned then we only accept byte aligned positions.
|
|
if not bytealigned or (p + pos) % 8 == 0:
|
|
return (p + pos,)
|
|
if bytealigned:
|
|
# Advance to just beyond the non-byte-aligned match and try again...
|
|
p += pos + 1
|
|
continue
|
|
p += increment
|
|
# Not found, return empty tuple
|
|
return ()
|
|
|
|
def _find_lsb0(self, bs, start=None, end=None, bytealigned=None):
|
|
bs = Bits(bs)
|
|
p = self.rfind(bs, start, end, bytealigned)
|
|
if p:
|
|
return (self.len - p[0] - bs.length,)
|
|
|
|
def _find_msb0(self, bs, start=None, end=None, bytealigned=None):
|
|
"""Find first occurrence of substring bs.
|
|
|
|
Returns a single item tuple with the bit position if found, or an
|
|
empty tuple if not found. The bit position (pos property) will
|
|
also be set to the start of the substring if it is found.
|
|
|
|
bs -- The bitstring to find.
|
|
start -- The bit position to start the search. Defaults to 0.
|
|
end -- The bit position one past the last bit to search.
|
|
Defaults to self.len.
|
|
bytealigned -- If True the bitstring will only be
|
|
found on byte boundaries.
|
|
|
|
Raises ValueError if bs is empty, if start < 0, if end > self.len or
|
|
if end < start.
|
|
|
|
>>> BitArray('0xc3e').find('0b1111')
|
|
(6,)
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
if not bs.len:
|
|
raise ValueError("Cannot find an empty bitstring.")
|
|
start, end = self._validate_slice(start, end)
|
|
if bytealigned is None:
|
|
bytealigned = globals()['bytealigned']
|
|
if bytealigned and not bs.len % 8 and not self._datastore.offset:
|
|
p = self._findbytes(bs.bytes, start, end, bytealigned)
|
|
else:
|
|
p = self._findregex(re.compile(bs._getbin()), start, end, bytealigned)
|
|
# If called from a class that has a pos, set it
|
|
try:
|
|
self._pos = p[0]
|
|
except (AttributeError, IndexError):
|
|
pass
|
|
return p
|
|
|
|
def findall(self, bs, start=None, end=None, count=None, bytealigned=None):
|
|
"""Find all occurrences of bs. Return generator of bit positions.
|
|
|
|
bs -- The bitstring to find.
|
|
start -- The bit position to start the search. Defaults to 0.
|
|
end -- The bit position one past the last bit to search.
|
|
Defaults to self.len.
|
|
count -- The maximum number of occurrences to find.
|
|
bytealigned -- If True the bitstring will only be found on
|
|
byte boundaries.
|
|
|
|
Raises ValueError if bs is empty, if start < 0, if end > self.len or
|
|
if end < start.
|
|
|
|
Note that all occurrences of bs are found, even if they overlap.
|
|
|
|
"""
|
|
if count is not None and count < 0:
|
|
raise ValueError("In findall, count must be >= 0.")
|
|
bs = Bits(bs)
|
|
start, end = self._validate_slice(start, end)
|
|
if bytealigned is None:
|
|
bytealigned = globals()['bytealigned']
|
|
c = 0
|
|
if bytealigned and not bs.len % 8 and not self._datastore.offset:
|
|
# Use the quick find method
|
|
f = self._findbytes
|
|
x = bs._getbytes()
|
|
else:
|
|
f = self._findregex
|
|
x = re.compile(bs._getbin())
|
|
while True:
|
|
|
|
p = f(x, start, end, bytealigned)
|
|
if not p:
|
|
break
|
|
if count is not None and c >= count:
|
|
return
|
|
c += 1
|
|
try:
|
|
self._pos = p[0]
|
|
except AttributeError:
|
|
pass
|
|
yield p[0]
|
|
if bytealigned:
|
|
start = p[0] + 8
|
|
else:
|
|
start = p[0] + 1
|
|
if start >= end:
|
|
break
|
|
return
|
|
|
|
def rfind(self, bs, start=None, end=None, bytealigned=None):
|
|
"""Find final occurrence of substring bs.
|
|
|
|
Returns a single item tuple with the bit position if found, or an
|
|
empty tuple if not found. The bit position (pos property) will
|
|
also be set to the start of the substring if it is found.
|
|
|
|
bs -- The bitstring to find.
|
|
start -- The bit position to end the reverse search. Defaults to 0.
|
|
end -- The bit position one past the first bit to reverse search.
|
|
Defaults to self.len.
|
|
bytealigned -- If True the bitstring will only be found on byte
|
|
boundaries.
|
|
|
|
Raises ValueError if bs is empty, if start < 0, if end > self.len or
|
|
if end < start.
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
start, end = self._validate_slice(start, end)
|
|
if bytealigned is None:
|
|
bytealigned = globals()['bytealigned']
|
|
if not bs.len:
|
|
raise ValueError("Cannot find an empty bitstring.")
|
|
# Search chunks starting near the end and then moving back
|
|
# until we find bs.
|
|
increment = max(8192, bs.len * 80)
|
|
buffersize = min(increment + bs.len, end - start)
|
|
pos = max(start, end - buffersize)
|
|
while True:
|
|
found = list(self.findall(bs, start=pos, end=pos + buffersize,
|
|
bytealigned=bytealigned))
|
|
if not found:
|
|
if pos == start:
|
|
return ()
|
|
pos = max(start, pos - increment)
|
|
continue
|
|
return (found[-1],)
|
|
|
|
def cut(self, bits, start=None, end=None, count=None):
|
|
"""Return bitstring generator by cutting into bits sized chunks.
|
|
|
|
bits -- The size in bits of the bitstring chunks to generate.
|
|
start -- The bit position to start the first cut. Defaults to 0.
|
|
end -- The bit position one past the last bit to use in the cut.
|
|
Defaults to self.len.
|
|
count -- If specified then at most count items are generated.
|
|
Default is to cut as many times as possible.
|
|
|
|
"""
|
|
start, end = self._validate_slice(start, end)
|
|
if count is not None and count < 0:
|
|
raise ValueError("Cannot cut - count must be >= 0.")
|
|
if bits <= 0:
|
|
raise ValueError("Cannot cut - bits must be >= 0.")
|
|
c = 0
|
|
while count is None or c < count:
|
|
c += 1
|
|
nextchunk = self._slice(start, min(start + bits, end))
|
|
if nextchunk.len != bits:
|
|
return
|
|
assert nextchunk._assertsanity()
|
|
yield nextchunk
|
|
start += bits
|
|
return
|
|
|
|
def split(self, delimiter, start=None, end=None, count=None,
|
|
bytealigned=None):
|
|
"""Return bitstring generator by splittling using a delimiter.
|
|
|
|
The first item returned is the initial bitstring before the delimiter,
|
|
which may be an empty bitstring.
|
|
|
|
delimiter -- The bitstring used as the divider.
|
|
start -- The bit position to start the split. Defaults to 0.
|
|
end -- The bit position one past the last bit to use in the split.
|
|
Defaults to self.len.
|
|
count -- If specified then at most count items are generated.
|
|
Default is to split as many times as possible.
|
|
bytealigned -- If True splits will only occur on byte boundaries.
|
|
|
|
Raises ValueError if the delimiter is empty.
|
|
|
|
"""
|
|
delimiter = Bits(delimiter)
|
|
if not delimiter.len:
|
|
raise ValueError("split delimiter cannot be empty.")
|
|
start, end = self._validate_slice(start, end)
|
|
if bytealigned is None:
|
|
bytealigned = globals()['bytealigned']
|
|
if count is not None and count < 0:
|
|
raise ValueError("Cannot split - count must be >= 0.")
|
|
if count == 0:
|
|
return
|
|
if bytealigned and not delimiter.len % 8 and not self._datastore.offset:
|
|
# Use the quick find method
|
|
f = self._findbytes
|
|
x = delimiter._getbytes()
|
|
else:
|
|
f = self._findregex
|
|
x = re.compile(delimiter._getbin())
|
|
found = f(x, start, end, bytealigned)
|
|
if not found:
|
|
# Initial bits are the whole bitstring being searched
|
|
yield self._slice(start, end)
|
|
return
|
|
# yield the bytes before the first occurrence of the delimiter, even if empty
|
|
yield self._slice(start, found[0])
|
|
startpos = pos = found[0]
|
|
c = 1
|
|
while count is None or c < count:
|
|
pos += delimiter.len
|
|
found = f(x, pos, end, bytealigned)
|
|
if not found:
|
|
# No more occurrences, so return the rest of the bitstring
|
|
yield self._slice(startpos, end)
|
|
return
|
|
c += 1
|
|
yield self._slice(startpos, found[0])
|
|
startpos = pos = found[0]
|
|
# Have generated count bitstrings, so time to quit.
|
|
return
|
|
|
|
def join(self, sequence):
|
|
"""Return concatenation of bitstrings joined by self.
|
|
|
|
sequence -- A sequence of bitstrings.
|
|
|
|
"""
|
|
s = self.__class__()
|
|
i = iter(sequence)
|
|
try:
|
|
s._append(Bits(next(i)))
|
|
while True:
|
|
n = next(i)
|
|
s._append(self)
|
|
s._append(Bits(n))
|
|
except StopIteration:
|
|
pass
|
|
return s
|
|
|
|
def tobytes(self):
|
|
"""Return the bitstring as bytes, padding with zero bits if needed.
|
|
|
|
Up to seven zero bits will be added at the end to byte align.
|
|
|
|
"""
|
|
d = offsetcopy(self._datastore, 0).rawbytes
|
|
# Need to ensure that unused bits at end are set to zero
|
|
unusedbits = 8 - self.len % 8
|
|
if unusedbits != 8:
|
|
d[-1] &= (0xff << unusedbits)
|
|
return bytes(d)
|
|
|
|
def tofile(self, f):
|
|
"""Write the bitstring to a file object, padding with zero bits if needed.
|
|
|
|
Up to seven zero bits will be added at the end to byte align.
|
|
|
|
"""
|
|
# If the bitstring is file based then we don't want to read it all
|
|
# in to memory.
|
|
chunksize = 1024 * 1024 # 1 MB chunks
|
|
if not self._offset:
|
|
a = 0
|
|
bytelen = self._datastore.bytelength
|
|
p = self._datastore.getbyteslice(a, min(a + chunksize, bytelen - 1))
|
|
while len(p) == chunksize:
|
|
f.write(p)
|
|
a += chunksize
|
|
p = self._datastore.getbyteslice(a, min(a + chunksize, bytelen - 1))
|
|
f.write(p)
|
|
# Now the final byte, ensuring that unused bits at end are set to 0.
|
|
bits_in_final_byte = self.len % 8
|
|
if not bits_in_final_byte:
|
|
bits_in_final_byte = 8
|
|
f.write(self[-bits_in_final_byte:].tobytes())
|
|
else:
|
|
# Really quite inefficient...
|
|
a = 0
|
|
b = a + chunksize * 8
|
|
while b <= self.len:
|
|
f.write(self._slice(a, b)._getbytes())
|
|
a += chunksize * 8
|
|
b += chunksize * 8
|
|
if a != self.len:
|
|
f.write(self._slice(a, self.len).tobytes())
|
|
|
|
def startswith(self, prefix, start=None, end=None):
|
|
"""Return whether the current bitstring starts with prefix.
|
|
|
|
prefix -- The bitstring to search for.
|
|
start -- The bit position to start from. Defaults to 0.
|
|
end -- The bit position to end at. Defaults to self.len.
|
|
|
|
"""
|
|
prefix = Bits(prefix)
|
|
start, end = self._validate_slice(start, end)
|
|
if end < start + prefix.len:
|
|
return False
|
|
end = start + prefix.len
|
|
return self._slice(start, end) == prefix
|
|
|
|
def endswith(self, suffix, start=None, end=None):
|
|
"""Return whether the current bitstring ends with suffix.
|
|
|
|
suffix -- The bitstring to search for.
|
|
start -- The bit position to start from. Defaults to 0.
|
|
end -- The bit position to end at. Defaults to self.len.
|
|
|
|
"""
|
|
suffix = Bits(suffix)
|
|
start, end = self._validate_slice(start, end)
|
|
if start + suffix.len > end:
|
|
return False
|
|
start = end - suffix.len
|
|
return self._slice(start, end) == suffix
|
|
|
|
def all(self, value, pos=None):
|
|
"""Return True if one or many bits are all set to value.
|
|
|
|
value -- If value is True then checks for bits set to 1, otherwise
|
|
checks for bits set to 0.
|
|
pos -- An iterable of bit positions. Negative numbers are treated in
|
|
the same way as slice indices. Defaults to the whole bitstring.
|
|
|
|
"""
|
|
value = bool(value)
|
|
length = self.len
|
|
if pos is None:
|
|
pos = xrange(self.len)
|
|
for p in pos:
|
|
if p < 0:
|
|
p += length
|
|
if not 0 <= p < length:
|
|
raise IndexError("Bit position {0} out of range.".format(p))
|
|
if not self._datastore.getbit(p) is value:
|
|
return False
|
|
return True
|
|
|
|
def any(self, value, pos=None):
|
|
"""Return True if any of one or many bits are set to value.
|
|
|
|
value -- If value is True then checks for bits set to 1, otherwise
|
|
checks for bits set to 0.
|
|
pos -- An iterable of bit positions. Negative numbers are treated in
|
|
the same way as slice indices. Defaults to the whole bitstring.
|
|
|
|
"""
|
|
value = bool(value)
|
|
length = self.len
|
|
if pos is None:
|
|
pos = xrange(self.len)
|
|
for p in pos:
|
|
if p < 0:
|
|
p += length
|
|
if not 0 <= p < length:
|
|
raise IndexError("Bit position {0} out of range.".format(p))
|
|
if self._datastore.getbit(p) is value:
|
|
return True
|
|
return False
|
|
|
|
def count(self, value):
|
|
"""Return count of total number of either zero or one bits.
|
|
|
|
value -- If True then bits set to 1 are counted, otherwise bits set
|
|
to 0 are counted.
|
|
|
|
>>> Bits('0xef').count(1)
|
|
7
|
|
|
|
"""
|
|
if not self.len:
|
|
return 0
|
|
# count the number of 1s (from which it's easy to work out the 0s).
|
|
# Don't count the final byte yet.
|
|
count = sum(BIT_COUNT[self._datastore.getbyte(i)] for i in xrange(self._datastore.bytelength - 1))
|
|
# adjust for bits at start that aren't part of the bitstring
|
|
if self._offset:
|
|
count -= BIT_COUNT[self._datastore.getbyte(0) >> (8 - self._offset)]
|
|
# and count the last 1 - 8 bits at the end.
|
|
endbits = self._datastore.bytelength * 8 - (self._offset + self.len)
|
|
count += BIT_COUNT[self._datastore.getbyte(self._datastore.bytelength - 1) >> endbits]
|
|
return count if value else self.len - count
|
|
|
|
# Create native-endian functions as aliases depending on the byteorder
|
|
if byteorder == 'little':
|
|
_setfloatne = _setfloatle
|
|
_readfloatne = _readfloatle
|
|
_getfloatne = _getfloatle
|
|
_setuintne = _setuintle
|
|
_readuintne = _readuintle
|
|
_getuintne = _getuintle
|
|
_setintne = _setintle
|
|
_readintne = _readintle
|
|
_getintne = _getintle
|
|
else:
|
|
_setfloatne = _setfloat
|
|
_readfloatne = _readfloat
|
|
_getfloatne = _getfloat
|
|
_setuintne = _setuintbe
|
|
_readuintne = _readuintbe
|
|
_getuintne = _getuintbe
|
|
_setintne = _setintbe
|
|
_readintne = _readintbe
|
|
_getintne = _getintbe
|
|
|
|
_offset = property(_getoffset)
|
|
|
|
len = property(_getlength,
|
|
doc="""The length of the bitstring in bits. Read only.
|
|
""")
|
|
length = property(_getlength,
|
|
doc="""The length of the bitstring in bits. Read only.
|
|
""")
|
|
bool = property(_getbool,
|
|
doc="""The bitstring as a bool (True or False). Read only.
|
|
""")
|
|
hex = property(_gethex,
|
|
doc="""The bitstring as a hexadecimal string. Read only.
|
|
""")
|
|
bin = property(_getbin,
|
|
doc="""The bitstring as a binary string. Read only.
|
|
""")
|
|
oct = property(_getoct,
|
|
doc="""The bitstring as an octal string. Read only.
|
|
""")
|
|
bytes = property(_getbytes,
|
|
doc="""The bitstring as a bytes object. Read only.
|
|
""")
|
|
int = property(_getint,
|
|
doc="""The bitstring as a two's complement signed int. Read only.
|
|
""")
|
|
uint = property(_getuint,
|
|
doc="""The bitstring as a two's complement unsigned int. Read only.
|
|
""")
|
|
float = property(_getfloat,
|
|
doc="""The bitstring as a floating point number. Read only.
|
|
""")
|
|
intbe = property(_getintbe,
|
|
doc="""The bitstring as a two's complement big-endian signed int. Read only.
|
|
""")
|
|
uintbe = property(_getuintbe,
|
|
doc="""The bitstring as a two's complement big-endian unsigned int. Read only.
|
|
""")
|
|
floatbe = property(_getfloat,
|
|
doc="""The bitstring as a big-endian floating point number. Read only.
|
|
""")
|
|
intle = property(_getintle,
|
|
doc="""The bitstring as a two's complement little-endian signed int. Read only.
|
|
""")
|
|
uintle = property(_getuintle,
|
|
doc="""The bitstring as a two's complement little-endian unsigned int. Read only.
|
|
""")
|
|
floatle = property(_getfloatle,
|
|
doc="""The bitstring as a little-endian floating point number. Read only.
|
|
""")
|
|
intne = property(_getintne,
|
|
doc="""The bitstring as a two's complement native-endian signed int. Read only.
|
|
""")
|
|
uintne = property(_getuintne,
|
|
doc="""The bitstring as a two's complement native-endian unsigned int. Read only.
|
|
""")
|
|
floatne = property(_getfloatne,
|
|
doc="""The bitstring as a native-endian floating point number. Read only.
|
|
""")
|
|
ue = property(_getue,
|
|
doc="""The bitstring as an unsigned exponential-Golomb code. Read only.
|
|
""")
|
|
se = property(_getse,
|
|
doc="""The bitstring as a signed exponential-Golomb code. Read only.
|
|
""")
|
|
uie = property(_getuie,
|
|
doc="""The bitstring as an unsigned interleaved exponential-Golomb code. Read only.
|
|
""")
|
|
sie = property(_getsie,
|
|
doc="""The bitstring as a signed interleaved exponential-Golomb code. Read only.
|
|
""")
|
|
|
|
|
|
# Dictionary that maps token names to the function that reads them.
|
|
name_to_read = {'uint': Bits._readuint,
|
|
'uintle': Bits._readuintle,
|
|
'uintbe': Bits._readuintbe,
|
|
'uintne': Bits._readuintne,
|
|
'int': Bits._readint,
|
|
'intle': Bits._readintle,
|
|
'intbe': Bits._readintbe,
|
|
'intne': Bits._readintne,
|
|
'float': Bits._readfloat,
|
|
'floatbe': Bits._readfloat, # floatbe is a synonym for float
|
|
'floatle': Bits._readfloatle,
|
|
'floatne': Bits._readfloatne,
|
|
'hex': Bits._readhex,
|
|
'oct': Bits._readoct,
|
|
'bin': Bits._readbin,
|
|
'bits': Bits._readbits,
|
|
'bytes': Bits._readbytes,
|
|
'ue': Bits._readue,
|
|
'se': Bits._readse,
|
|
'uie': Bits._readuie,
|
|
'sie': Bits._readsie,
|
|
'bool': Bits._readbool,
|
|
}
|
|
|
|
# Dictionaries for mapping init keywords with init functions.
|
|
init_with_length_and_offset = {'bytes': Bits._setbytes_safe,
|
|
'filename': Bits._setfile,
|
|
}
|
|
|
|
init_with_length_only = {'uint': Bits._setuint,
|
|
'int': Bits._setint,
|
|
'float': Bits._setfloat,
|
|
'uintbe': Bits._setuintbe,
|
|
'intbe': Bits._setintbe,
|
|
'floatbe': Bits._setfloat,
|
|
'uintle': Bits._setuintle,
|
|
'intle': Bits._setintle,
|
|
'floatle': Bits._setfloatle,
|
|
'uintne': Bits._setuintne,
|
|
'intne': Bits._setintne,
|
|
'floatne': Bits._setfloatne,
|
|
}
|
|
|
|
init_without_length_or_offset = {'bin': Bits._setbin_safe,
|
|
'hex': Bits._sethex,
|
|
'oct': Bits._setoct,
|
|
'ue': Bits._setue,
|
|
'se': Bits._setse,
|
|
'uie': Bits._setuie,
|
|
'sie': Bits._setsie,
|
|
'bool': Bits._setbool,
|
|
}
|
|
|
|
|
|
class BitArray(Bits):
|
|
"""A container holding a mutable sequence of bits.
|
|
|
|
Subclass of the immutable Bits class. Inherits all of its
|
|
methods (except __hash__) and adds mutating methods.
|
|
|
|
Mutating methods:
|
|
|
|
append() -- Append a bitstring.
|
|
byteswap() -- Change byte endianness in-place.
|
|
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.
|
|
|
|
Methods inherited from Bits:
|
|
|
|
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.
|
|
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-string.
|
|
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.
|
|
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.
|
|
tobytes() -- Return bitstring as bytes, padding if needed.
|
|
tofile() -- Write bitstring to file, padding if needed.
|
|
unpack() -- Interpret bits using format string.
|
|
|
|
Special methods:
|
|
|
|
Mutating operators are available: [], <<=, >>=, +=, *=, &=, |= and ^=
|
|
in addition to the inherited [], ==, !=, +, *, ~, <<, >>, &, | and ^.
|
|
|
|
Properties:
|
|
|
|
bin -- The bitstring as a binary string.
|
|
bool -- For single bit bitstrings, interpret as True or False.
|
|
bytepos -- The current byte position in the bitstring.
|
|
bytes -- The bitstring as a bytes object.
|
|
float -- Interpret as a floating point number.
|
|
floatbe -- 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.
|
|
hex -- The bitstring as a hexadecimal string.
|
|
int -- 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 -- The bitstring as an octal string.
|
|
pos -- The current bit position in the bitstring.
|
|
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 -- 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.
|
|
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
# As BitArray objects are mutable, we shouldn't allow them to be hashed.
|
|
__hash__ = None
|
|
|
|
def __init__(self, auto=None, length=None, offset=None, **kwargs):
|
|
"""Either specify an 'auto' initialiser:
|
|
auto -- a string of comma separated tokens, an integer, a file object,
|
|
a bytearray, a boolean iterable or another bitstring.
|
|
|
|
Or initialise via **kwargs with one (and only one) of:
|
|
bytes -- raw data as a string, for example read from a binary file.
|
|
bin -- binary string representation, e.g. '0b001010'.
|
|
hex -- hexadecimal string representation, e.g. '0x2ef'
|
|
oct -- octal string representation, e.g. '0o777'.
|
|
uint -- an unsigned integer.
|
|
int -- a signed integer.
|
|
float -- a floating point number.
|
|
uintbe -- an unsigned big-endian whole byte integer.
|
|
intbe -- a signed big-endian whole byte integer.
|
|
floatbe - a big-endian floating point number.
|
|
uintle -- an unsigned little-endian whole byte integer.
|
|
intle -- a signed little-endian whole byte integer.
|
|
floatle -- a little-endian floating point number.
|
|
uintne -- an unsigned native-endian whole byte integer.
|
|
intne -- a signed native-endian whole byte integer.
|
|
floatne -- a native-endian floating point number.
|
|
se -- a signed exponential-Golomb code.
|
|
ue -- an unsigned exponential-Golomb code.
|
|
sie -- a signed interleaved exponential-Golomb code.
|
|
uie -- an unsigned interleaved exponential-Golomb code.
|
|
bool -- a boolean (True or False).
|
|
filename -- a file which will be opened in binary read-only mode.
|
|
|
|
Other keyword arguments:
|
|
length -- length of the bitstring in bits, if needed and appropriate.
|
|
It must be supplied for all integer and float initialisers.
|
|
offset -- bit offset to the data. These offset bits are
|
|
ignored and this is intended for use when
|
|
initialising using 'bytes' or 'filename'.
|
|
|
|
"""
|
|
# For mutable BitArrays we always read in files to memory:
|
|
if not isinstance(self._datastore, ByteStore):
|
|
self._ensureinmemory()
|
|
|
|
def __new__(cls, auto=None, length=None, offset=None, **kwargs):
|
|
x = super(BitArray, cls).__new__(cls)
|
|
y = Bits.__new__(BitArray, auto, length, offset, **kwargs)
|
|
x._datastore = ByteStore(y._datastore._rawarray[:],
|
|
y._datastore.bitlength,
|
|
y._datastore.offset)
|
|
return x
|
|
|
|
def __iadd__(self, bs):
|
|
"""Append bs to current bitstring. Return self.
|
|
|
|
bs -- the bitstring to append.
|
|
|
|
"""
|
|
self.append(bs)
|
|
return self
|
|
|
|
def __copy__(self):
|
|
"""Return a new copy of the BitArray."""
|
|
s_copy = BitArray()
|
|
if not isinstance(self._datastore, ByteStore):
|
|
# Let them both point to the same (invariant) array.
|
|
# If either gets modified then at that point they'll be read into memory.
|
|
s_copy._datastore = self._datastore
|
|
else:
|
|
s_copy._datastore = copy.copy(self._datastore)
|
|
return s_copy
|
|
|
|
def __setitem__(self, key, value):
|
|
try:
|
|
# A slice
|
|
start, step = 0, 1
|
|
if key.step is not None:
|
|
step = key.step
|
|
except AttributeError:
|
|
# single element
|
|
if key < 0:
|
|
key += self.len
|
|
if not 0 <= key < self.len:
|
|
raise IndexError("Slice index out of range.")
|
|
if isinstance(value, numbers.Integral):
|
|
if not value:
|
|
self._unset(key)
|
|
return
|
|
if value in (1, -1):
|
|
self._set(key)
|
|
return
|
|
raise ValueError("Cannot set a single bit with integer {0}.".format(value))
|
|
value = Bits(value)
|
|
if value.len == 1:
|
|
# TODO: this can't be optimal
|
|
if value[0]:
|
|
self._set(key)
|
|
else:
|
|
self._unset(key)
|
|
else:
|
|
self._delete(1, key)
|
|
self._insert(value, key)
|
|
return
|
|
else:
|
|
if step != 1:
|
|
# convert to binary string and use string slicing
|
|
# TODO: Horribly inefficient
|
|
temp = list(self._getbin())
|
|
v = list(Bits(value)._getbin())
|
|
temp.__setitem__(key, v)
|
|
self._setbin_unsafe(''.join(temp))
|
|
return
|
|
|
|
# If value is an integer then we want to set the slice to that
|
|
# value rather than initialise a new bitstring of that length.
|
|
if not isinstance(value, numbers.Integral):
|
|
try:
|
|
# TODO: Better way than calling constructor here?
|
|
value = Bits(value)
|
|
except TypeError:
|
|
raise TypeError("Bitstring, integer or string expected. "
|
|
"Got {0}.".format(type(value)))
|
|
if key.start is not None:
|
|
start = key.start
|
|
if key.start < 0:
|
|
start += self.len
|
|
if start < 0:
|
|
start = 0
|
|
stop = self.len
|
|
if key.stop is not None:
|
|
stop = key.stop
|
|
if key.stop < 0:
|
|
stop += self.len
|
|
if start > stop:
|
|
# The standard behaviour for lists is to just insert at the
|
|
# start position if stop < start and step == 1.
|
|
stop = start
|
|
if isinstance(value, numbers.Integral):
|
|
if value >= 0:
|
|
value = self.__class__(uint=value, length=stop - start)
|
|
else:
|
|
value = self.__class__(int=value, length=stop - start)
|
|
stop = min(stop, self.len)
|
|
start = max(start, 0)
|
|
start = min(start, stop)
|
|
if (stop - start) == value.len:
|
|
if not value.len:
|
|
return
|
|
if step >= 0:
|
|
self._overwrite(value, start)
|
|
else:
|
|
self._overwrite(value.__getitem__(slice(None, None, 1)), start)
|
|
else:
|
|
# TODO: A delete then insert is wasteful - it could do unneeded shifts.
|
|
# Could be either overwrite + insert or overwrite + delete.
|
|
self._delete(stop - start, start)
|
|
if step >= 0:
|
|
self._insert(value, start)
|
|
else:
|
|
self._insert(value.__getitem__(slice(None, None, 1)), start)
|
|
# pos is now after the inserted piece.
|
|
return
|
|
|
|
def __delitem__(self, key):
|
|
"""Delete item or range.
|
|
|
|
Indices are in units of the step parameter (default 1 bit).
|
|
Stepping is used to specify the number of bits in each item.
|
|
|
|
>>> a = BitArray('0x001122')
|
|
>>> del a[1:2:8]
|
|
>>> print a
|
|
0x0022
|
|
|
|
"""
|
|
try:
|
|
# A slice
|
|
start = 0
|
|
step = key.step if key.step is not None else 1
|
|
except AttributeError:
|
|
# single element
|
|
if key < 0:
|
|
key += self.len
|
|
if not 0 <= key < self.len:
|
|
raise IndexError("Slice index out of range.")
|
|
self._delete(1, key)
|
|
return
|
|
else:
|
|
if step != 1:
|
|
# convert to binary string and use string slicing
|
|
# TODO: Horribly inefficient
|
|
temp = list(self._getbin())
|
|
temp.__delitem__(key)
|
|
self._setbin_unsafe(''.join(temp))
|
|
return
|
|
stop = key.stop
|
|
if key.start is not None:
|
|
start = key.start
|
|
if key.start < 0:
|
|
start += self.len
|
|
if start < 0:
|
|
start = 0
|
|
stop = self.len
|
|
if key.stop is not None:
|
|
stop = key.stop
|
|
if key.stop < 0:
|
|
stop += self.len
|
|
if start > stop:
|
|
return
|
|
stop = min(stop, self.len)
|
|
start = max(start, 0)
|
|
start = min(start, stop)
|
|
self._delete(stop - start, start)
|
|
return
|
|
|
|
def __ilshift__(self, n):
|
|
"""Shift bits by n to the left in place. Return self.
|
|
|
|
n -- the number of bits to shift. Must be >= 0.
|
|
|
|
"""
|
|
if n < 0:
|
|
raise ValueError("Cannot shift by a negative amount.")
|
|
if not self.len:
|
|
raise ValueError("Cannot shift an empty bitstring.")
|
|
if not n:
|
|
return self
|
|
n = min(n, self.len)
|
|
return self._ilshift(n)
|
|
|
|
def __irshift__(self, n):
|
|
"""Shift bits by n to the right in place. Return self.
|
|
|
|
n -- the number of bits to shift. Must be >= 0.
|
|
|
|
"""
|
|
if n < 0:
|
|
raise ValueError("Cannot shift by a negative amount.")
|
|
if not self.len:
|
|
raise ValueError("Cannot shift an empty bitstring.")
|
|
if not n:
|
|
return self
|
|
n = min(n, self.len)
|
|
return self._irshift(n)
|
|
|
|
def __imul__(self, n):
|
|
"""Concatenate n copies of self in place. Return self.
|
|
|
|
Called for expressions of the form 'a *= 3'.
|
|
n -- The number of concatenations. Must be >= 0.
|
|
|
|
"""
|
|
if n < 0:
|
|
raise ValueError("Cannot multiply by a negative integer.")
|
|
return self._imul(n)
|
|
|
|
def __ior__(self, bs):
|
|
bs = Bits(bs)
|
|
if self.len != bs.len:
|
|
raise ValueError("Bitstrings must have the same length "
|
|
"for |= operator.")
|
|
return self._ior(bs)
|
|
|
|
def __iand__(self, bs):
|
|
bs = Bits(bs)
|
|
if self.len != bs.len:
|
|
raise ValueError("Bitstrings must have the same length "
|
|
"for &= operator.")
|
|
return self._iand(bs)
|
|
|
|
def __ixor__(self, bs):
|
|
bs = Bits(bs)
|
|
if self.len != bs.len:
|
|
raise ValueError("Bitstrings must have the same length "
|
|
"for ^= operator.")
|
|
return self._ixor(bs)
|
|
|
|
def replace(self, old, new, start=None, end=None, count=None,
|
|
bytealigned=None):
|
|
"""Replace all occurrences of old with new in place.
|
|
|
|
Returns number of replacements made.
|
|
|
|
old -- The bitstring to replace.
|
|
new -- The replacement bitstring.
|
|
start -- Any occurrences that start before this will not be replaced.
|
|
Defaults to 0.
|
|
end -- Any occurrences that finish after this will not be replaced.
|
|
Defaults to self.len.
|
|
count -- The maximum number of replacements to make. Defaults to
|
|
replace all occurrences.
|
|
bytealigned -- If True replacements will only be made on byte
|
|
boundaries.
|
|
|
|
Raises ValueError if old is empty or if start or end are
|
|
out of range.
|
|
|
|
"""
|
|
old = Bits(old)
|
|
new = Bits(new)
|
|
if not old.len:
|
|
raise ValueError("Empty bitstring cannot be replaced.")
|
|
start, end = self._validate_slice(start, end)
|
|
if bytealigned is None:
|
|
bytealigned = globals()['bytealigned']
|
|
# Adjust count for use in split()
|
|
if count is not None:
|
|
count += 1
|
|
sections = self.split(old, start, end, count, bytealigned)
|
|
lengths = [s.len for s in sections]
|
|
if len(lengths) == 1:
|
|
# Didn't find anything to replace.
|
|
return 0 # no replacements done
|
|
if new is self:
|
|
# Prevent self assignment woes
|
|
new = copy.copy(self)
|
|
positions = [lengths[0] + start]
|
|
for l in lengths[1:-1]:
|
|
# Next position is the previous one plus the length of the next section.
|
|
positions.append(positions[-1] + l)
|
|
# We have all the positions that need replacements. We do them
|
|
# in reverse order so that they won't move around as we replace.
|
|
positions.reverse()
|
|
try:
|
|
# Need to calculate new pos, if this is a bitstream
|
|
newpos = self._pos
|
|
for p in positions:
|
|
self[p:p + old.len] = new
|
|
if old.len != new.len:
|
|
diff = new.len - old.len
|
|
for p in positions:
|
|
if p >= newpos:
|
|
continue
|
|
if p + old.len <= newpos:
|
|
newpos += diff
|
|
else:
|
|
newpos = p
|
|
self._pos = newpos
|
|
except AttributeError:
|
|
for p in positions:
|
|
self[p:p + old.len] = new
|
|
assert self._assertsanity()
|
|
return len(lengths) - 1
|
|
|
|
def insert(self, bs, pos=None):
|
|
"""Insert bs at bit position pos.
|
|
|
|
bs -- The bitstring to insert.
|
|
pos -- The bit position to insert at.
|
|
|
|
Raises ValueError if pos < 0 or pos > self.len.
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
if not bs.len:
|
|
return self
|
|
if bs is self:
|
|
bs = self.__copy__()
|
|
if pos is None:
|
|
try:
|
|
pos = self._pos
|
|
except AttributeError:
|
|
raise TypeError("insert require a bit position for this type.")
|
|
if pos < 0:
|
|
pos += self.len
|
|
if not 0 <= pos <= self.len:
|
|
raise ValueError("Invalid insert position.")
|
|
self._insert(bs, pos)
|
|
|
|
def overwrite(self, bs, pos=None):
|
|
"""Overwrite with bs at bit position pos.
|
|
|
|
bs -- The bitstring to overwrite with.
|
|
pos -- The bit position to begin overwriting from.
|
|
|
|
Raises ValueError if pos < 0 or pos + bs.len > self.len
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
if not bs.len:
|
|
return
|
|
if pos is None:
|
|
try:
|
|
pos = self._pos
|
|
except AttributeError:
|
|
raise TypeError("overwrite require a bit position for this type.")
|
|
if pos < 0:
|
|
pos += self.len
|
|
if pos < 0 or pos + bs.len > self.len:
|
|
raise ValueError("Overwrite exceeds boundary of bitstring.")
|
|
self._overwrite(bs, pos)
|
|
try:
|
|
self._pos = pos + bs.len
|
|
except AttributeError:
|
|
pass
|
|
|
|
def append(self, bs):
|
|
"""Append a bitstring to the current bitstring.
|
|
|
|
bs -- The bitstring to append.
|
|
|
|
"""
|
|
# The offset is a hint to make bs easily appendable.
|
|
bs = self._converttobitstring(bs, offset=(self.len + self._offset) % 8)
|
|
self._append(bs)
|
|
|
|
def prepend(self, bs):
|
|
"""Prepend a bitstring to the current bitstring.
|
|
|
|
bs -- The bitstring to prepend.
|
|
|
|
"""
|
|
bs = Bits(bs)
|
|
self._prepend(bs)
|
|
|
|
def reverse(self, start=None, end=None):
|
|
"""Reverse bits in-place.
|
|
|
|
start -- Position of first bit to reverse. Defaults to 0.
|
|
end -- One past the position of the last bit to reverse.
|
|
Defaults to self.len.
|
|
|
|
Using on an empty bitstring will have no effect.
|
|
|
|
Raises ValueError if start < 0, end > self.len or end < start.
|
|
|
|
"""
|
|
start, end = self._validate_slice(start, end)
|
|
if start == 0 and end == self.len:
|
|
self._reverse()
|
|
return
|
|
s = self._slice(start, end)
|
|
s._reverse()
|
|
self[start:end] = s
|
|
|
|
def set(self, value, pos=None):
|
|
"""Set one or many bits to 1 or 0.
|
|
|
|
value -- If True bits are set to 1, otherwise they are set to 0.
|
|
pos -- Either a single bit position or an iterable of bit positions.
|
|
Negative numbers are treated in the same way as slice indices.
|
|
Defaults to the entire bitstring.
|
|
|
|
Raises IndexError if pos < -self.len or pos >= self.len.
|
|
|
|
"""
|
|
f = self._set if value else self._unset
|
|
if pos is None:
|
|
pos = xrange(self.len)
|
|
try:
|
|
length = self.len
|
|
for p in pos:
|
|
if p < 0:
|
|
p += length
|
|
if not 0 <= p < length:
|
|
raise IndexError("Bit position {0} out of range.".format(p))
|
|
f(p)
|
|
except TypeError:
|
|
# Single pos
|
|
if pos < 0:
|
|
pos += self.len
|
|
if not 0 <= pos < length:
|
|
raise IndexError("Bit position {0} out of range.".format(pos))
|
|
f(pos)
|
|
|
|
def invert(self, pos=None):
|
|
"""Invert one or many bits from 0 to 1 or vice versa.
|
|
|
|
pos -- Either a single bit position or an iterable of bit positions.
|
|
Negative numbers are treated in the same way as slice indices.
|
|
|
|
Raises IndexError if pos < -self.len or pos >= self.len.
|
|
|
|
"""
|
|
if pos is None:
|
|
self._invert_all()
|
|
return
|
|
if not isinstance(pos, collectionsAbc.Iterable):
|
|
pos = (pos,)
|
|
length = self.len
|
|
|
|
for p in pos:
|
|
if p < 0:
|
|
p += length
|
|
if not 0 <= p < length:
|
|
raise IndexError("Bit position {0} out of range.".format(p))
|
|
self._invert(p)
|
|
|
|
def ror(self, bits, start=None, end=None):
|
|
"""Rotate bits to the right in-place.
|
|
|
|
bits -- The number of bits to rotate by.
|
|
start -- Start of slice to rotate. Defaults to 0.
|
|
end -- End of slice to rotate. Defaults to self.len.
|
|
|
|
Raises ValueError if bits < 0.
|
|
|
|
"""
|
|
if not self.len:
|
|
raise Error("Cannot rotate an empty bitstring.")
|
|
if bits < 0:
|
|
raise ValueError("Cannot rotate right by negative amount.")
|
|
start, end = self._validate_slice(start, end)
|
|
bits %= (end - start)
|
|
if not bits:
|
|
return
|
|
rhs = self._slice(end - bits, end)
|
|
self._delete(bits, end - bits)
|
|
self._insert(rhs, start)
|
|
|
|
def rol(self, bits, start=None, end=None):
|
|
"""Rotate bits to the left in-place.
|
|
|
|
bits -- The number of bits to rotate by.
|
|
start -- Start of slice to rotate. Defaults to 0.
|
|
end -- End of slice to rotate. Defaults to self.len.
|
|
|
|
Raises ValueError if bits < 0.
|
|
|
|
"""
|
|
if not self.len:
|
|
raise Error("Cannot rotate an empty bitstring.")
|
|
if bits < 0:
|
|
raise ValueError("Cannot rotate left by negative amount.")
|
|
start, end = self._validate_slice(start, end)
|
|
bits %= (end - start)
|
|
if not bits:
|
|
return
|
|
lhs = self._slice(start, start + bits)
|
|
self._delete(bits, start)
|
|
self._insert(lhs, end - bits)
|
|
|
|
def byteswap(self, fmt=None, start=None, end=None, repeat=True):
|
|
"""Change the endianness in-place. Return number of repeats of fmt done.
|
|
|
|
fmt -- A compact structure string, an integer number of bytes or
|
|
an iterable of integers. Defaults to 0, which byte reverses the
|
|
whole bitstring.
|
|
start -- Start bit position, defaults to 0.
|
|
end -- End bit position, defaults to self.len.
|
|
repeat -- If True (the default) the byte swapping pattern is repeated
|
|
as much as possible.
|
|
|
|
"""
|
|
start, end = self._validate_slice(start, end)
|
|
if fmt is None or fmt == 0:
|
|
# reverse all of the whole bytes.
|
|
bytesizes = [(end - start) // 8]
|
|
elif isinstance(fmt, numbers.Integral):
|
|
if fmt < 0:
|
|
raise ValueError("Improper byte length {0}.".format(fmt))
|
|
bytesizes = [fmt]
|
|
elif isinstance(fmt, basestring):
|
|
m = STRUCT_PACK_RE.match(fmt)
|
|
if not m:
|
|
raise ValueError("Cannot parse format string {0}.".format(fmt))
|
|
# Split the format string into a list of 'q', '4h' etc.
|
|
formatlist = re.findall(STRUCT_SPLIT_RE, m.group('fmt'))
|
|
# Now deal with multiplicative factors, 4h -> hhhh etc.
|
|
bytesizes = []
|
|
for f in formatlist:
|
|
if len(f) == 1:
|
|
bytesizes.append(PACK_CODE_SIZE[f])
|
|
else:
|
|
bytesizes.extend([PACK_CODE_SIZE[f[-1]]] * int(f[:-1]))
|
|
elif isinstance(fmt, collectionsAbc.Iterable):
|
|
bytesizes = fmt
|
|
for bytesize in bytesizes:
|
|
if not isinstance(bytesize, numbers.Integral) or bytesize < 0:
|
|
raise ValueError("Improper byte length {0}.".format(bytesize))
|
|
else:
|
|
raise TypeError("Format must be an integer, string or iterable.")
|
|
|
|
repeats = 0
|
|
totalbitsize = 8 * sum(bytesizes)
|
|
if not totalbitsize:
|
|
return 0
|
|
if repeat:
|
|
# Try to repeat up to the end of the bitstring.
|
|
finalbit = end
|
|
else:
|
|
# Just try one (set of) byteswap(s).
|
|
finalbit = start + totalbitsize
|
|
for patternend in xrange(start + totalbitsize, finalbit + 1, totalbitsize):
|
|
bytestart = patternend - totalbitsize
|
|
for bytesize in bytesizes:
|
|
byteend = bytestart + bytesize * 8
|
|
self._reversebytes(bytestart, byteend)
|
|
bytestart += bytesize * 8
|
|
repeats += 1
|
|
return repeats
|
|
|
|
def clear(self):
|
|
"""Remove all bits, reset to zero length."""
|
|
self._clear()
|
|
|
|
def copy(self):
|
|
"""Return a copy of the bitstring."""
|
|
return self._copy()
|
|
|
|
int = property(Bits._getint, Bits._setint,
|
|
doc="""The bitstring as a two's complement signed int. Read and write.
|
|
""")
|
|
uint = property(Bits._getuint, Bits._setuint,
|
|
doc="""The bitstring as a two's complement unsigned int. Read and write.
|
|
""")
|
|
float = property(Bits._getfloat, Bits._setfloat,
|
|
doc="""The bitstring as a floating point number. Read and write.
|
|
""")
|
|
intbe = property(Bits._getintbe, Bits._setintbe,
|
|
doc="""The bitstring as a two's complement big-endian signed int. Read and write.
|
|
""")
|
|
uintbe = property(Bits._getuintbe, Bits._setuintbe,
|
|
doc="""The bitstring as a two's complement big-endian unsigned int. Read and write.
|
|
""")
|
|
floatbe = property(Bits._getfloat, Bits._setfloat,
|
|
doc="""The bitstring as a big-endian floating point number. Read and write.
|
|
""")
|
|
intle = property(Bits._getintle, Bits._setintle,
|
|
doc="""The bitstring as a two's complement little-endian signed int. Read and write.
|
|
""")
|
|
uintle = property(Bits._getuintle, Bits._setuintle,
|
|
doc="""The bitstring as a two's complement little-endian unsigned int. Read and write.
|
|
""")
|
|
floatle = property(Bits._getfloatle, Bits._setfloatle,
|
|
doc="""The bitstring as a little-endian floating point number. Read and write.
|
|
""")
|
|
intne = property(Bits._getintne, Bits._setintne,
|
|
doc="""The bitstring as a two's complement native-endian signed int. Read and write.
|
|
""")
|
|
uintne = property(Bits._getuintne, Bits._setuintne,
|
|
doc="""The bitstring as a two's complement native-endian unsigned int. Read and write.
|
|
""")
|
|
floatne = property(Bits._getfloatne, Bits._setfloatne,
|
|
doc="""The bitstring as a native-endian floating point number. Read and write.
|
|
""")
|
|
ue = property(Bits._getue, Bits._setue,
|
|
doc="""The bitstring as an unsigned exponential-Golomb code. Read and write.
|
|
""")
|
|
se = property(Bits._getse, Bits._setse,
|
|
doc="""The bitstring as a signed exponential-Golomb code. Read and write.
|
|
""")
|
|
uie = property(Bits._getuie, Bits._setuie,
|
|
doc="""The bitstring as an unsigned interleaved exponential-Golomb code. Read and write.
|
|
""")
|
|
sie = property(Bits._getsie, Bits._setsie,
|
|
doc="""The bitstring as a signed interleaved exponential-Golomb code. Read and write.
|
|
""")
|
|
hex = property(Bits._gethex, Bits._sethex,
|
|
doc="""The bitstring as a hexadecimal string. Read and write.
|
|
""")
|
|
bin = property(Bits._getbin, Bits._setbin_safe,
|
|
doc="""The bitstring as a binary string. Read and write.
|
|
""")
|
|
oct = property(Bits._getoct, Bits._setoct,
|
|
doc="""The bitstring as an octal string. Read and write.
|
|
""")
|
|
bool = property(Bits._getbool, Bits._setbool,
|
|
doc="""The bitstring as a bool (True or False). Read and write.
|
|
""")
|
|
bytes = property(Bits._getbytes, Bits._setbytes_safe,
|
|
doc="""The bitstring as a ordinary string. Read and write.
|
|
""")
|
|
|
|
|
|
|
|
class ConstBitStream(Bits):
|
|
"""A container or stream holding an immutable sequence of bits.
|
|
|
|
For a mutable container use the BitStream class instead.
|
|
|
|
Methods inherited from Bits:
|
|
|
|
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.
|
|
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-string.
|
|
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.
|
|
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.
|
|
tobytes() -- Return bitstring as bytes, padding if needed.
|
|
tofile() -- Write bitstring to file, padding if needed.
|
|
unpack() -- Interpret bits using format string.
|
|
|
|
Other 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.
|
|
|
|
Special methods:
|
|
|
|
Also available are the operators [], ==, !=, +, *, ~, <<, >>, &, |, ^.
|
|
|
|
Properties:
|
|
|
|
bin -- The bitstring as a binary string.
|
|
bool -- For single bit bitstrings, interpret as True or False.
|
|
bytepos -- The current byte position in the bitstring.
|
|
bytes -- The bitstring as a bytes object.
|
|
float -- Interpret as a floating point number.
|
|
floatbe -- 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.
|
|
hex -- The bitstring as a hexadecimal string.
|
|
int -- 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 -- The bitstring as an octal string.
|
|
pos -- The current bit position in the bitstring.
|
|
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 -- 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.
|
|
|
|
"""
|
|
|
|
__slots__ = ('_pos')
|
|
|
|
def __init__(self, auto=None, length=None, offset=None, **kwargs):
|
|
"""Either specify an 'auto' initialiser:
|
|
auto -- a string of comma separated tokens, an integer, a file object,
|
|
a bytearray, a boolean iterable or another bitstring.
|
|
|
|
Or initialise via **kwargs with one (and only one) of:
|
|
bytes -- raw data as a string, for example read from a binary file.
|
|
bin -- binary string representation, e.g. '0b001010'.
|
|
hex -- hexadecimal string representation, e.g. '0x2ef'
|
|
oct -- octal string representation, e.g. '0o777'.
|
|
uint -- an unsigned integer.
|
|
int -- a signed integer.
|
|
float -- a floating point number.
|
|
uintbe -- an unsigned big-endian whole byte integer.
|
|
intbe -- a signed big-endian whole byte integer.
|
|
floatbe - a big-endian floating point number.
|
|
uintle -- an unsigned little-endian whole byte integer.
|
|
intle -- a signed little-endian whole byte integer.
|
|
floatle -- a little-endian floating point number.
|
|
uintne -- an unsigned native-endian whole byte integer.
|
|
intne -- a signed native-endian whole byte integer.
|
|
floatne -- a native-endian floating point number.
|
|
se -- a signed exponential-Golomb code.
|
|
ue -- an unsigned exponential-Golomb code.
|
|
sie -- a signed interleaved exponential-Golomb code.
|
|
uie -- an unsigned interleaved exponential-Golomb code.
|
|
bool -- a boolean (True or False).
|
|
filename -- a file which will be opened in binary read-only mode.
|
|
|
|
Other keyword arguments:
|
|
length -- length of the bitstring in bits, if needed and appropriate.
|
|
It must be supplied for all integer and float initialisers.
|
|
offset -- bit offset to the data. These offset bits are
|
|
ignored and this is intended for use when
|
|
initialising using 'bytes' or 'filename'.
|
|
|
|
"""
|
|
self._pos = 0
|
|
|
|
def __new__(cls, auto=None, length=None, offset=None, **kwargs):
|
|
x = super(ConstBitStream, cls).__new__(cls)
|
|
x._initialise(auto, length, offset, **kwargs)
|
|
return x
|
|
|
|
def _setbytepos(self, bytepos):
|
|
"""Move to absolute byte-aligned position in stream."""
|
|
self._setbitpos(bytepos * 8)
|
|
|
|
def _getbytepos(self):
|
|
"""Return the current position in the stream in bytes. Must be byte aligned."""
|
|
if self._pos % 8:
|
|
raise ByteAlignError("Not byte aligned in _getbytepos().")
|
|
return self._pos // 8
|
|
|
|
def _setbitpos(self, pos):
|
|
"""Move to absolute postion bit in bitstream."""
|
|
if pos < 0:
|
|
raise ValueError("Bit position cannot be negative.")
|
|
if pos > self.len:
|
|
raise ValueError("Cannot seek past the end of the data.")
|
|
self._pos = pos
|
|
|
|
def _getbitpos(self):
|
|
"""Return the current position in the stream in bits."""
|
|
return self._pos
|
|
|
|
def _clear(self):
|
|
Bits._clear(self)
|
|
self._pos = 0
|
|
|
|
def __copy__(self):
|
|
"""Return a new copy of the ConstBitStream for the copy module."""
|
|
# Note that if you want a new copy (different ID), use _copy instead.
|
|
# The copy can use the same datastore as it's immutable.
|
|
s = ConstBitStream()
|
|
s._datastore = self._datastore
|
|
# Reset the bit position, don't copy it.
|
|
s._pos = 0
|
|
return s
|
|
|
|
def __add__(self, bs):
|
|
"""Concatenate bitstrings and return new bitstring.
|
|
|
|
bs -- the bitstring to append.
|
|
|
|
"""
|
|
s = Bits.__add__(self, bs)
|
|
s._pos = 0
|
|
return s
|
|
|
|
def read(self, fmt):
|
|
"""Interpret next bits according to the format string and return result.
|
|
|
|
fmt -- Token string describing how to interpret the next bits.
|
|
|
|
Token examples: 'int:12' : 12 bits as a signed integer
|
|
'uint:8' : 8 bits as an unsigned integer
|
|
'float:64' : 8 bytes as a big-endian float
|
|
'intbe:16' : 2 bytes as a big-endian signed integer
|
|
'uintbe:16' : 2 bytes as a big-endian unsigned integer
|
|
'intle:32' : 4 bytes as a little-endian signed integer
|
|
'uintle:32' : 4 bytes as a little-endian unsigned integer
|
|
'floatle:64': 8 bytes as a little-endian float
|
|
'intne:24' : 3 bytes as a native-endian signed integer
|
|
'uintne:24' : 3 bytes as a native-endian unsigned integer
|
|
'floatne:32': 4 bytes as a native-endian float
|
|
'hex:80' : 80 bits as a hex string
|
|
'oct:9' : 9 bits as an octal string
|
|
'bin:1' : single bit binary string
|
|
'ue' : next bits as unsigned exp-Golomb code
|
|
'se' : next bits as signed exp-Golomb code
|
|
'uie' : next bits as unsigned interleaved exp-Golomb code
|
|
'sie' : next bits as signed interleaved exp-Golomb code
|
|
'bits:5' : 5 bits as a bitstring
|
|
'bytes:10' : 10 bytes as a bytes object
|
|
'bool' : 1 bit as a bool
|
|
'pad:3' : 3 bits of padding to ignore - returns None
|
|
|
|
fmt may also be an integer, which will be treated like the 'bits' token.
|
|
|
|
The position in the bitstring is advanced to after the read items.
|
|
|
|
Raises ReadError if not enough bits are available.
|
|
Raises ValueError if the format is not understood.
|
|
|
|
"""
|
|
if isinstance(fmt, numbers.Integral):
|
|
if fmt < 0:
|
|
raise ValueError("Cannot read negative amount.")
|
|
if fmt > self.len - self._pos:
|
|
raise ReadError("Cannot read {0} bits, only {1} available.",
|
|
fmt, self.len - self._pos)
|
|
bs = self._slice(self._pos, self._pos + fmt)
|
|
self._pos += fmt
|
|
return bs
|
|
p = self._pos
|
|
_, token = tokenparser(fmt)
|
|
if len(token) != 1:
|
|
self._pos = p
|
|
raise ValueError("Format string should be a single token, not {0} "
|
|
"tokens - use readlist() instead.".format(len(token)))
|
|
name, length, _ = token[0]
|
|
if length is None:
|
|
length = self.len - self._pos
|
|
value, self._pos = self._readtoken(name, self._pos, length)
|
|
return value
|
|
|
|
def readlist(self, fmt, **kwargs):
|
|
"""Interpret next bits according to format string(s) and return list.
|
|
|
|
fmt -- A single string or list of strings with comma separated tokens
|
|
describing how to interpret the next bits in the bitstring. Items
|
|
can also be integers, for reading new bitstring of the given length.
|
|
kwargs -- A dictionary or keyword-value pairs - the keywords used in the
|
|
format string will be replaced with their given value.
|
|
|
|
The position in the bitstring is advanced to after the read items.
|
|
|
|
Raises ReadError is not enough bits are available.
|
|
Raises ValueError if the format is not understood.
|
|
|
|
See the docstring for 'read' for token examples. 'pad' tokens are skipped
|
|
and not added to the returned list.
|
|
|
|
>>> h, b1, b2 = s.readlist('hex:20, bin:5, bin:3')
|
|
>>> i, bs1, bs2 = s.readlist(['uint:12', 10, 10])
|
|
|
|
"""
|
|
value, self._pos = self._readlist(fmt, self._pos, **kwargs)
|
|
return value
|
|
|
|
def readto(self, bs, bytealigned=None):
|
|
"""Read up to and including next occurrence of bs and return result.
|
|
|
|
bs -- The bitstring to find. An integer is not permitted.
|
|
bytealigned -- If True the bitstring will only be
|
|
found on byte boundaries.
|
|
|
|
Raises ValueError if bs is empty.
|
|
Raises ReadError if bs is not found.
|
|
|
|
"""
|
|
if isinstance(bs, numbers.Integral):
|
|
raise ValueError("Integers cannot be searched for")
|
|
bs = Bits(bs)
|
|
oldpos = self._pos
|
|
p = self.find(bs, self._pos, bytealigned=bytealigned)
|
|
if not p:
|
|
raise ReadError("Substring not found")
|
|
self._pos += bs.len
|
|
return self._slice(oldpos, self._pos)
|
|
|
|
def peek(self, fmt):
|
|
"""Interpret next bits according to format string and return result.
|
|
|
|
fmt -- Token string describing how to interpret the next bits.
|
|
|
|
The position in the bitstring is not changed. If not enough bits are
|
|
available then all bits to the end of the bitstring will be used.
|
|
|
|
Raises ReadError if not enough bits are available.
|
|
Raises ValueError if the format is not understood.
|
|
|
|
See the docstring for 'read' for token examples.
|
|
|
|
"""
|
|
pos_before = self._pos
|
|
value = self.read(fmt)
|
|
self._pos = pos_before
|
|
return value
|
|
|
|
def peeklist(self, fmt, **kwargs):
|
|
"""Interpret next bits according to format string(s) and return list.
|
|
|
|
fmt -- One or more strings with comma separated tokens describing
|
|
how to interpret the next bits in the bitstring.
|
|
kwargs -- A dictionary or keyword-value pairs - the keywords used in the
|
|
format string will be replaced with their given value.
|
|
|
|
The position in the bitstring is not changed. If not enough bits are
|
|
available then all bits to the end of the bitstring will be used.
|
|
|
|
Raises ReadError if not enough bits are available.
|
|
Raises ValueError if the format is not understood.
|
|
|
|
See the docstring for 'read' for token examples.
|
|
|
|
"""
|
|
pos = self._pos
|
|
return_values = self.readlist(fmt, **kwargs)
|
|
self._pos = pos
|
|
return return_values
|
|
|
|
def bytealign(self):
|
|
"""Align to next byte and return number of skipped bits.
|
|
|
|
Raises ValueError if the end of the bitstring is reached before
|
|
aligning to the next byte.
|
|
|
|
"""
|
|
skipped = (8 - (self._pos % 8)) % 8
|
|
self.pos += self._offset + skipped
|
|
assert self._assertsanity()
|
|
return skipped
|
|
|
|
pos = property(_getbitpos, _setbitpos,
|
|
doc="""The position in the bitstring in bits. Read and write.
|
|
""")
|
|
bitpos = property(_getbitpos, _setbitpos,
|
|
doc="""The position in the bitstring in bits. Read and write.
|
|
""")
|
|
bytepos = property(_getbytepos, _setbytepos,
|
|
doc="""The position in the bitstring in bytes. Read and write.
|
|
""")
|
|
|
|
|
|
|
|
|
|
|
|
class BitStream(ConstBitStream, BitArray):
|
|
"""A container or stream holding a mutable sequence of bits
|
|
|
|
Subclass of the ConstBitStream and BitArray classes. Inherits all of
|
|
their methods.
|
|
|
|
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.
|
|
append() -- Append a bitstring.
|
|
bytealign() -- Align to next byte boundary.
|
|
byteswap() -- Change byte endianness in-place.
|
|
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-string.
|
|
find() -- Find a sub-bitstring in the current bitstring.
|
|
findall() -- Find all occurrences of a sub-bitstring in the current bitstring.
|
|
insert() -- Insert a bitstring.
|
|
invert() -- Flip bit(s) between one and zero.
|
|
join() -- Join bitstrings together using current bitstring.
|
|
overwrite() -- Overwrite a section with a new bitstring.
|
|
peek() -- Peek at and interpret next bits as a single item.
|
|
peeklist() -- Peek at and interpret next bits as a list of items.
|
|
prepend() -- Prepend a bitstring.
|
|
read() -- Read and interpret next bits as a single item.
|
|
readlist() -- Read and interpret next bits as a list of items.
|
|
replace() -- Replace occurrences of one bitstring with another.
|
|
reverse() -- Reverse bits in-place.
|
|
rfind() -- Seek backwards to find a sub-bitstring.
|
|
rol() -- Rotate bits to the left.
|
|
ror() -- Rotate bits to the right.
|
|
set() -- Set bit(s) to 1 or 0.
|
|
split() -- Create generator of chunks split by a delimiter.
|
|
startswith() -- Return whether the bitstring starts with a sub-bitstring.
|
|
tobytes() -- Return bitstring as bytes, padding if needed.
|
|
tofile() -- Write bitstring to file, padding if needed.
|
|
unpack() -- Interpret bits using format string.
|
|
|
|
Special methods:
|
|
|
|
Mutating operators are available: [], <<=, >>=, +=, *=, &=, |= and ^=
|
|
in addition to [], ==, !=, +, *, ~, <<, >>, &, | and ^.
|
|
|
|
Properties:
|
|
|
|
bin -- The bitstring as a binary string.
|
|
bool -- For single bit bitstrings, interpret as True or False.
|
|
bytepos -- The current byte position in the bitstring.
|
|
bytes -- The bitstring as a bytes object.
|
|
float -- Interpret as a floating point number.
|
|
floatbe -- 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.
|
|
hex -- The bitstring as a hexadecimal string.
|
|
int -- 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 -- The bitstring as an octal string.
|
|
pos -- The current bit position in the bitstring.
|
|
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 -- 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.
|
|
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
# As BitStream objects are mutable, we shouldn't allow them to be hashed.
|
|
__hash__ = None
|
|
|
|
def __init__(self, auto=None, length=None, offset=None, **kwargs):
|
|
"""Either specify an 'auto' initialiser:
|
|
auto -- a string of comma separated tokens, an integer, a file object,
|
|
a bytearray, a boolean iterable or another bitstring.
|
|
|
|
Or initialise via **kwargs with one (and only one) of:
|
|
bytes -- raw data as a string, for example read from a binary file.
|
|
bin -- binary string representation, e.g. '0b001010'.
|
|
hex -- hexadecimal string representation, e.g. '0x2ef'
|
|
oct -- octal string representation, e.g. '0o777'.
|
|
uint -- an unsigned integer.
|
|
int -- a signed integer.
|
|
float -- a floating point number.
|
|
uintbe -- an unsigned big-endian whole byte integer.
|
|
intbe -- a signed big-endian whole byte integer.
|
|
floatbe - a big-endian floating point number.
|
|
uintle -- an unsigned little-endian whole byte integer.
|
|
intle -- a signed little-endian whole byte integer.
|
|
floatle -- a little-endian floating point number.
|
|
uintne -- an unsigned native-endian whole byte integer.
|
|
intne -- a signed native-endian whole byte integer.
|
|
floatne -- a native-endian floating point number.
|
|
se -- a signed exponential-Golomb code.
|
|
ue -- an unsigned exponential-Golomb code.
|
|
sie -- a signed interleaved exponential-Golomb code.
|
|
uie -- an unsigned interleaved exponential-Golomb code.
|
|
bool -- a boolean (True or False).
|
|
filename -- a file which will be opened in binary read-only mode.
|
|
|
|
Other keyword arguments:
|
|
length -- length of the bitstring in bits, if needed and appropriate.
|
|
It must be supplied for all integer and float initialisers.
|
|
offset -- bit offset to the data. These offset bits are
|
|
ignored and this is intended for use when
|
|
initialising using 'bytes' or 'filename'.
|
|
|
|
"""
|
|
self._pos = 0
|
|
# For mutable BitStreams we always read in files to memory:
|
|
if not isinstance(self._datastore, (ByteStore, ConstByteStore)):
|
|
self._ensureinmemory()
|
|
|
|
def __new__(cls, auto=None, length=None, offset=None, **kwargs):
|
|
x = super(BitStream, cls).__new__(cls)
|
|
y = ConstBitStream.__new__(BitStream, auto, length, offset, **kwargs)
|
|
x._datastore = ByteStore(y._datastore._rawarray[:],
|
|
y._datastore.bitlength,
|
|
y._datastore.offset)
|
|
return x
|
|
|
|
def __copy__(self):
|
|
"""Return a new copy of the BitStream."""
|
|
s_copy = BitStream()
|
|
s_copy._pos = 0
|
|
if not isinstance(self._datastore, ByteStore):
|
|
# Let them both point to the same (invariant) array.
|
|
# If either gets modified then at that point they'll be read into memory.
|
|
s_copy._datastore = self._datastore
|
|
else:
|
|
s_copy._datastore = ByteStore(self._datastore._rawarray[:],
|
|
self._datastore.bitlength,
|
|
self._datastore.offset)
|
|
return s_copy
|
|
|
|
def prepend(self, bs):
|
|
"""Prepend a bitstring to the current bitstring.
|
|
|
|
bs -- The bitstring to prepend.
|
|
|
|
"""
|
|
bs = self._converttobitstring(bs)
|
|
self._prepend(bs)
|
|
self._pos += bs.len
|
|
|
|
|
|
def pack(fmt, *values, **kwargs):
|
|
"""Pack the values according to the format string and return a new BitStream.
|
|
|
|
fmt -- A single string or a list of strings with comma separated tokens
|
|
describing how to create the BitStream.
|
|
values -- Zero or more values to pack according to the format.
|
|
kwargs -- A dictionary or keyword-value pairs - the keywords used in the
|
|
format string will be replaced with their given value.
|
|
|
|
Token examples: 'int:12' : 12 bits as a signed integer
|
|
'uint:8' : 8 bits as an unsigned integer
|
|
'float:64' : 8 bytes as a big-endian float
|
|
'intbe:16' : 2 bytes as a big-endian signed integer
|
|
'uintbe:16' : 2 bytes as a big-endian unsigned integer
|
|
'intle:32' : 4 bytes as a little-endian signed integer
|
|
'uintle:32' : 4 bytes as a little-endian unsigned integer
|
|
'floatle:64': 8 bytes as a little-endian float
|
|
'intne:24' : 3 bytes as a native-endian signed integer
|
|
'uintne:24' : 3 bytes as a native-endian unsigned integer
|
|
'floatne:32': 4 bytes as a native-endian float
|
|
'hex:80' : 80 bits as a hex string
|
|
'oct:9' : 9 bits as an octal string
|
|
'bin:1' : single bit binary string
|
|
'ue' / 'uie': next bits as unsigned exp-Golomb code
|
|
'se' / 'sie': next bits as signed exp-Golomb code
|
|
'bits:5' : 5 bits as a bitstring object
|
|
'bytes:10' : 10 bytes as a bytes object
|
|
'bool' : 1 bit as a bool
|
|
'pad:3' : 3 zero bits as padding
|
|
|
|
>>> s = pack('uint:12, bits', 100, '0xffe')
|
|
>>> t = pack(['bits', 'bin:3'], s, '111')
|
|
>>> u = pack('uint:8=a, uint:8=b, uint:55=a', a=6, b=44)
|
|
|
|
"""
|
|
tokens = []
|
|
if isinstance(fmt, basestring):
|
|
fmt = [fmt]
|
|
try:
|
|
for f_item in fmt:
|
|
_, tkns = tokenparser(f_item, tuple(sorted(kwargs.keys())))
|
|
tokens.extend(tkns)
|
|
except ValueError as e:
|
|
raise CreationError(*e.args)
|
|
value_iter = iter(values)
|
|
s = BitStream()
|
|
try:
|
|
for name, length, value in tokens:
|
|
# If the value is in the kwd dictionary then it takes precedence.
|
|
if value in kwargs:
|
|
value = kwargs[value]
|
|
# If the length is in the kwd dictionary then use that too.
|
|
if length in kwargs:
|
|
length = kwargs[length]
|
|
# Also if we just have a dictionary name then we want to use it
|
|
if name in kwargs and length is None and value is None:
|
|
s.append(kwargs[name])
|
|
continue
|
|
if length is not None:
|
|
length = int(length)
|
|
if value is None and name != 'pad':
|
|
# Take the next value from the ones provided
|
|
value = next(value_iter)
|
|
s._append(BitStream._init_with_token(name, length, value))
|
|
except StopIteration:
|
|
raise CreationError("Not enough parameters present to pack according to the "
|
|
"format. {0} values are needed.", len(tokens))
|
|
try:
|
|
next(value_iter)
|
|
except StopIteration:
|
|
# Good, we've used up all the *values.
|
|
return s
|
|
raise CreationError("Too many parameters present to pack according to the format.")
|
|
|
|
# Whether to label the Least Significant Bit as bit 0. Default is False. Experimental feature.
|
|
_lsb0 = False
|
|
|
|
def _switch_lsb0_methods():
|
|
if _lsb0:
|
|
ConstByteStore.getbit = ConstByteStore._getbit_lsb0
|
|
Bits.find = Bits._find_lsb0
|
|
Bits._slice = Bits._slice_lsb0
|
|
BitArray._overwrite = BitArray._overwrite_lsb0
|
|
BitArray._insert = BitArray._insert_lsb0
|
|
BitArray._delete = BitArray._delete_lsb0
|
|
ByteStore.setbit = ByteStore._setbit_lsb0
|
|
ByteStore.unsetbit = ByteStore._unsetbit_lsb0
|
|
ByteStore.invertbit = ByteStore._invertbit_lsb0
|
|
else:
|
|
ConstByteStore.getbit = ConstByteStore._getbit_msb0
|
|
Bits.find = Bits._find_msb0
|
|
Bits._slice = Bits._slice_msb0
|
|
BitArray._overwrite = BitArray._overwrite_msb0
|
|
BitArray._insert = BitArray._insert_msb0
|
|
BitArray._delete = BitArray._delete_msb0
|
|
ByteStore.setbit = ByteStore._setbit_msb0
|
|
ByteStore.unsetbit = ByteStore._unsetbit_msb0
|
|
ByteStore.invertbit = ByteStore._invertbit_msb0
|
|
|
|
def set_lsb0(v=True):
|
|
"""Experimental method changing the bit numbering so that the least significant bit is bit 0"""
|
|
global _lsb0
|
|
_lsb0 = bool(v)
|
|
_switch_lsb0_methods()
|
|
|
|
def set_msb0(v=True):
|
|
"""Experimental method to reset the bit numbering so that the most significant bit is bit 0"""
|
|
global _lsb0
|
|
_lsb0 = not bool(v)
|
|
_switch_lsb0_methods()
|
|
|
|
_switch_lsb0_methods()
|
|
|
|
# Aliases for backward compatibility
|
|
ConstBitArray = Bits
|
|
BitString = BitStream
|
|
|
|
__all__ = ['ConstBitArray', 'ConstBitStream', 'BitStream', 'BitArray',
|
|
'Bits', 'BitString', 'pack', 'Error', 'ReadError', 'InterpretError',
|
|
'ByteAlignError', 'CreationError', 'bytealigned', 'set_lsb0', 'set_msb0']
|
|
|
|
if __name__ == '__main__':
|
|
"""Create and interpret a bitstring from command-line parameters.
|
|
|
|
Command-line parameters are concatenated and a bitstring created
|
|
from them. If the final parameter is either an interpretation string
|
|
or ends with a '.' followed by an interpretation string then that
|
|
interpretation of the bitstring will be used when printing it.
|
|
|
|
Typical usage might be invoking the Python module from a console
|
|
as a one-off calculation:
|
|
|
|
$ python -m bitstring int:16=-400
|
|
0xfe70
|
|
$ python -m bitstring float:32=0.2 bin
|
|
00111110010011001100110011001101
|
|
$ python -m bitstring 0xff 3*0b01,0b11 uint
|
|
65367
|
|
$ python -m bitstring hex=01, uint:12=352.hex
|
|
01160
|
|
|
|
This feature is experimental and is subject to change or removal.
|
|
"""
|
|
|
|
# check if final parameter is an interpretation string
|
|
fp = sys.argv[-1]
|
|
if fp in name_to_read.keys():
|
|
# concatenate all other parameters and interpret using the final one
|
|
b1 = Bits(','.join(sys.argv[1: -1]))
|
|
print(b1._readtoken(fp, 0, b1.__len__())[0])
|
|
else:
|
|
# does final parameter end with a dot then an interpretation string?
|
|
interp = fp[fp.rfind('.') + 1:]
|
|
if interp in name_to_read.keys():
|
|
sys.argv[-1] = fp[:fp.rfind('.')]
|
|
b1 = Bits(','.join(sys.argv[1:]))
|
|
print(b1._readtoken(interp, 0, b1.__len__())[0])
|
|
else:
|
|
# No interpretation - just use default print
|
|
b1 = Bits(','.join(sys.argv[1:]))
|
|
print(b1)
|