BitString Class Reference

The BitString class provides a way to access arbitrarily sized data at a bit level.

Constructors
BitString()Constructs an empty bit string.
BitString(BitString const &source)Constructs a copy.
BitString(const char * data, size_t length, unsigned start_index = 0)Constructs a bit string of the data and length provided. length is in bits. start_index is the starting bit index within data.
explicit BitString(unsigned bits)Constructs a bit string of bits length and initializes them to 0. If bits is 0, an empty bit string is created.
BitString(Encoding base, const char * str)Constructs a bit string converted from a string. The string is interpreted using the encoding scheme scheme. Example: 
BitString bs1(BitString::Binary, "110011001");
BitString bs2(BitString::Hex, "ABCDEF012345");
BitString bs3(BitString::Ascii7, "hello world!");
BitString bs4(BitString::Ascii8, "hello world!");
In the example above, bs3 will treat each character of "hello world!" as 7 bits, whereas the bs4 bit string will treat each character as 8 bits.
BitString(int base, const char * str)Constructs a bit string converted from a string. This is a convenience function. The base can only be 2 or 16.
BitString(const char * str)Constructs a bit string converted from a string. This is a convenience function. The string is interpreted using the encoding scheme specified by the first character of the string: '#' implies ASCII hex, '@' implies ASCII binary. If neither character is supplied, then the string is interpreted as ASCII hex. All whitespace will be removed. Example: 
BitString bs1("#ABCDEF012345");     // interpret as ASCII hex
BitString bs2("@110011001");        // interpret as ASCII binary
BitString bs1("ABCDEF012345");      // interpret as ASCII hex

BitString bs1("AB CD EF 01 23 45"); // interpret as ASCII hex
BitString bs1("hello!");            // error, results in bs1.empty() == true
Methods
BitString & append(BitString const &str)Concatenates two bit strings. The resulting string is returned, allowing multiple appends to be appended to each other (e.g. "a.append(b).append(c).append(e)").
const char * ascii() constReturn an ASCII string, treating each 8 bits as a character. The return value will be valid until this bitstring remains in scope or ascii() is called again.
const char * ascii7() constReturn an ASCII string, treating each 7 bits as a character.
bool at(unsigned index, bool * ok = 0) constReturns the value of the bit at index index as a boolean. If ok is provided, then it will be set to true if index is in range.
const char * ccp() constReturn a character pointer to the data. The returned character pointer will point to contiguous memory where the data of the bitstring can be found. Any bits following the first length() bits are undefined. This is a logically const method. If the internal representation of the bit string happens to be contiguous and byte aligned, then the address is returned (complexity of O(1)). Otherwise, the internal data will have to be manipulated (i.e. moved -- complexity of O(n)). The returned pointer will point to valid data as long as no other non-const operations are performed on the data and the bit string remains in scope.
void clear()Clear the bit string (making it empty).
bool empty() constReturns true if the bit string is empty.
BitString & insert(BitString const &str, unsigned index)Insert a bit string before index. The bit string will be prepended if index is 0. It will be appended if index is length().
unsigned length() constReturns length of string in bits. Returns 0 if this is an empty bit string.
BitString & minimize()Remove all leading 0 bits.
BitString & padLeft(unsigned width = 8)Expand the bit string's length to a multiple of width bits, left padding with zeroes. Returns a reference to self.
BitString & padRight(unsigned width = 8)Expand the bit string's length to a multiple of width bits, right padding with zeroes. Returns a reference to self.
unsigned index() constReturns the current index. This is used by peek(), read(), etc.
BitString read(size_t length)Returns length bits as another bit string. The next read() or peek() will begin at length + 1 bits. An empty bit string is returned if length is 0, length is greater than the length of the bit string, or the bit string is null.
BitString peek(size_t length) constSame as read(), but the internal bit index is not updated, leaving the bit string in the exact same state it was before this method is called.
bool seek(int offset, int whence = 0)Moves the index ahead offset. If offset goes beyond the end of the string, the seek is not done and false is returned. If whence is positive, 0, or negative, the offset is relative to the start of the bit string, the current position, or the end of the bit string, respectively. The default is relative.
unsigned remaining() constThis is a convenience method. It is the same as length() - index().
void replace(int index, BitString const & bs)Replace the bitstring starting at index index with bs. The bitstring does not grow in size.
bool set(unsigned index)Set a bit to 1 at index index. Returns false if index is out of range.
bool reset(unsigned index)Reset a bit to 0 at index index. Returns false if index is out of range.
void resize(size_t length)Either truncates the bit string or right pads with 0s in order to make the length equal to length.
BitString substr(size_t begin_index, size_t length) constReturns a section of the bit string as another bit string. Returns an empty string if the requested bit string is out of range, or this is an empty string. This method is logically const.
const char * toBinString() constReturns a string of '1' and '0' characters.
char * toBinString(char * dest, size_t length) constReturns a string of '1' and '0' characters.
const char * toHexString() constReturns a string of [0-9A-F] characters. The string will be zero padded on the right to make it byte aligned.
char * toHexString(char * dest, size_t length) constReturns a string of [0-9A-F] characters. The string will be zero padded on the right to make it byte aligned.
Operators
bool operator==(BitString const &source) constEquality. Compare.
bool operator==(const char * source) constEquality. The input string is interpreted the same way the corresponding constructor is.
bool operator!=(BitString const &source) constNot Equality.
bool operator!=(const char * source) constNot Equality.
BitString &operator=(BitString const &source)Assignment.

Detail

The interface has similarities to both a character string and a file, although the fundamental unit is a bit and not a character.

Each bit string has a current index. The index() and seek() methods are used to access and modify the current index. The read() and peek() methods return substrings relative to the current index.

The substr() method is used to return a substring, and the append() method is used to concatenate two bit strings together.

The ccp() method returns a constant character pointer. This is the binary representation of the bit string.

A bit string is an implicitly shared and reference counted object. This means most operations do not entail copying of data.

All length references are in bits.