Home       Trees       Indices       Help   
Package lepl :: Package bin :: Module bits :: Class BitString
[hide private]
[frames] | no frames]

Class BitString

source code

A sequence of bits, of arbitrary length. Has similar semantics to strings, in that a single index is itself a BitString (of unit length).

This is intended as a standard fmt for arbitrary binary data, to help with conversion between other types. In other words, convert to and from this, and then chain conversions.

BitStr are stored as a contiguous sequence in an array of bytes. Both bits and bytes are "little endian" - this allows arbitrary lengths of bits, at arbitrary offsets, to be given values without worrying about alignment.

The bit sequence starts at bit 'offset' in the first byte and there are a total of 'length' bits. The number of bytes stored is the minimum implied by those two values, with zero padding.

Instance Methods [hide private]
 
__init__(self, value=None, length=0, offset=0)
value is a bytes() instance that contains the data.		 source code
 
bytes(self, offset=0)
Return a series of bytes values, which encode the data for len(self) bits when offset=0 (with final padding in the last byte if necessary).		 source code
 
bits(self)
Return a series of bits (encoded as booleans) that contain the contents.		 source code
 
__str__(self)
For 64 bits or less, show bits grouped by byte (octet), with bytes and bits running from left to right.		 source code
 
__repr__(self)
An explicit display of internal state, including padding and offset.		 source code
 
__len__(self) source code
 
zero(self)
Are all bits zero?		 source code
 
offset(self)
The internal offset.		 source code
 
__iter__(self) source code
 
__add__(self, other)
Combine two sequences, appending then together.		 source code
 
to_bytes(self, offset=0)
Return a bytes() object, right-padded with zero bits of necessary.		 source code
 
to_int(self, big_endian=False)
Convert the entire bit sequence (of any size) to an integer.		 source code
 
to_str(self, encoding=None, errors='strict')
Convert to string.		 source code
 
__int__(self) source code
 
__index__(self) source code
 
__invert__(self) source code
 
__getitem__(self, index) source code
 
__eq__(self, other) source code
 
__hash__(self)
hash(x)		 source code

Inherited from object: __delattr__, __format__, __getattribute__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

Static Methods [hide private]
 
from_byte(value)
Create a BitString from a byte.		 source code
 
from_int32(value, big_endian=None)
Create a BitString from a 32 bit integer.		 source code
 
from_int64(value, big_endian=None)
Create a BitString from a 64 bit integer.		 source code
 
from_int(value, length=None, big_endian=None)
Value can be an int, or a string with a leading or trailing tag.		 source code
 
from_sequence(value, unpack=lambda x: x)
Unpack is called for each item in turn (so should be, say, from_byte).		 source code
 
from_bytearray(value)
Create a BitString from a bytearray.		 source code
 
from_str(value, encoding=None, errors=STRICT)
Create a BitString from a string.		 source code
Class Variables [hide private]
  __swap = swap_table()
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, value=None, length=0, offset=0)
(Constructor)

source code 

value is a bytes() instance that contains the data.

length is the number of valid bits. If given as a float it is the number of bytes (bits = int(float) * 8 + decimal(float) * 10)

offset is the index of the first valid bit in the value.

Overrides: object.__init__

bytes(self, offset=0)

source code 

Return a series of bytes values, which encode the data for len(self) bits when offset=0 (with final padding in the last byte if necessary). It is the caller's responsibility to discard any trailing bits.

When 0 < offset < 8 then the data are zero-padded by offset bits first.

__str__(self)
(Informal representation operator)

source code 

For 64 bits or less, show bits grouped by byte (octet), with bytes and bits running from left to right. This is a "picture" of the bits.

For more than 64 bits, give a hex encoding of bytes (right padded with zeros), shown in big-endian fmt.

In both cases, the length in bits is given after a trailing slash.

Whatever the internal offset, values are displayed with no initial padding.

Overrides: object.__str__

__repr__(self)
(Representation operator)

source code 
An explicit display of internal state, including padding and offset.
Overrides: object.__repr__

offset(self)

source code 
The internal offset. This is not useful as an external API, but helps with debugging.

to_int(self, big_endian=False)

source code 

Convert the entire bit sequence (of any size) to an integer.

Big endian conversion is only possible if the bits form a whole number of bytes.

__hash__(self)
(Hashing function)

source code 
hash(x)
Overrides: object.__hash__
(inherited documentation)

from_int(value, length=None, big_endian=None)
Static Method

source code 

Value can be an int, or a string with a leading or trailing tag. A plain int, or no tag, or leading tag, is byte little-endian by default.

Length and big-endianness are inferred from the fmt for values given as strings, but explicit parameters override these. If no length is given, and none can be inferred, 32 bits is assumed (bit length cannot be inferred for decimal values, even as strings).

The interpretation of big-endian values depends on the base and is either very intuitive and useful, or completely stupid. Use at your own risk.

Big-endian hex values must specify an exact number of bytes (even number of hex digits). Each separate byte is assigned a value according to big-endian semantics, but with a byte small-endian order is used. This is consistent with the standard conventions for network data. So, for example, 1234x0 gives two bytes. The first contains the value 0x12, the second the value 0x34.

Big-endian binary values are taken to be a "picture" of the bits, with the array reading from left to right. So 0011b0 specifies four bits, starting with two zeroes.

Big-endian decimal and octal values are treated as hex values.


   Home       Trees       Indices       Help   
Generated by Epydoc 3.0.1 on Sat Jun 9 21:50:51 2012 http://epydoc.sourceforge.net