ConstBitStream Class Reference

Inheritance diagram for ConstBitStream:

Public Member Functions
def	__init__ (self, auto=None, length=None, offset=None, **kwargs)
def	__new__ (cls, auto=None, length=None, offset=None, **kwargs)
def	__copy__ (self)
def	__add__ (self, bs)
def	read (self, fmt)
def	readlist (self, fmt, **kwargs)
def	readto (self, bs, bytealigned=None)
def	peek (self, fmt)
def	peeklist (self, fmt, **kwargs)
def	bytealign (self)

Protected Member Functions
def	_setbytepos (self, bytepos)
def	_getbytepos (self)
def	_setbitpos (self, pos)
def	_getbitpos (self)
def	_clear (self)

Protected Attributes
	_pos

Properties
property	pos
property	bitpos
property	bytepos

Static Private Attributes
tuple	__slots__ = ('_pos')

Detailed Description

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.

Definition at line 3699 of file bitstring.py.

Constructor & Destructor Documentation

__init__()

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'.

Reimplemented from Bits.

Reimplemented in BitStream.

Definition at line 3764 of file bitstring.py.

    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
 

Member Function Documentation

__add__()

def __add__	(		self,
			bs
	)

Concatenate bitstrings and return new bitstring.

bs -- the bitstring to append.

Reimplemented from Bits.

Definition at line 3844 of file bitstring.py.

    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
 

__copy__()

def __copy__

(

self

)

Return a new copy of the ConstBitStream for the copy module.

Reimplemented from Bits.

Reimplemented in BitStream.

Definition at line 3834 of file bitstring.py.

    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
 

__new__()

def __new__	(		cls,
			auto = None,
			length = None,
			offset = None,
		**	kwargs
	)

Reimplemented from Bits.

Definition at line 3803 of file bitstring.py.

    def __new__(cls, auto=None, length=None, offset=None, **kwargs):
        x = super(ConstBitStream, cls).__new__(cls)
        x._initialise(auto, length, offset, **kwargs)
        return x
 

_clear()

def _clear (   self )

protected

Reset the bitstring to an empty state.

Reimplemented from Bits.

Definition at line 3830 of file bitstring.py.

    def _clear(self):
        Bits._clear(self)
        self._pos = 0
 

_getbitpos()

def _getbitpos (   self )

protected

Return the current position in the stream in bits.

Definition at line 3826 of file bitstring.py.

    def _getbitpos(self):
        """Return the current position in the stream in bits."""
        return self._pos
 

_getbytepos()

def _getbytepos (   self )

protected

Return the current position in the stream in bytes. Must be byte aligned.

Definition at line 3812 of file bitstring.py.

    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
 

_setbitpos()

def _setbitpos (   self,   pos  )

protected

Move to absolute postion bit in bitstream.

Definition at line 3818 of file bitstring.py.

    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
 

_setbytepos()

def _setbytepos (   self,   bytepos  )

protected

Move to absolute byte-aligned position in stream.

Definition at line 3808 of file bitstring.py.

    def _setbytepos(self, bytepos):
        """Move to absolute byte-aligned position in stream."""
        self._setbitpos(bytepos * 8)
 

bytealign()

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.

Definition at line 3997 of file bitstring.py.

    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
 

peek()

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.

Definition at line 3956 of file bitstring.py.

    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
 

peeklist()

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.

Definition at line 3975 of file bitstring.py.

    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
 

read()

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.

Definition at line 3854 of file bitstring.py.

    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
 

readlist()

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])

Definition at line 3911 of file bitstring.py.

    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
 

readto()

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.

Definition at line 3935 of file bitstring.py.

    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)
 

Member Data Documentation

__slots__

tuple __slots__ = ('_pos')

staticprivate

Definition at line 3762 of file bitstring.py.

_pos

_pos

protected

Definition at line 3801 of file bitstring.py.

Property Documentation

bitpos

property bitpos

static

Initial value:

=  property(_getbitpos, _setbitpos,
                      doc=)

Definition at line 4012 of file bitstring.py.

bytepos

property bytepos

static

Initial value:

=  property(_getbytepos, _setbytepos,
                       doc=)

Definition at line 4015 of file bitstring.py.

pos

property pos

static

Initial value:

=  property(_getbitpos, _setbitpos,
                   doc=)

Definition at line 4009 of file bitstring.py.

---

The documentation for this class was generated from the following file:

• trg/scripts/bitstring.py