Description

Bit vectors.

This class implements bit vectors with run-time sizes and a rich set of operations that can be restricted to a contiguous subset of bits. The primary goal of this class is not to provide the utmost performance, but rather a rich, easy-to-use interface. For example,

In general, each method has a number of overloaded varieties: if a BitRange is not specified it generally means the entire bit vector; if a second bit vector is not specified for binary operations it generally means use this vector for both operands. Non-const operations modify this vector in place, and most of them also return a reference so that they can be easily chained:

bv.clear().set(BitRange(24,31)); // clear all bits, then set bits 24-31

When performing an operation that has two operands, the operands are generally permitted to both refer to the same vector, and the range arguments are permitted to overlap in that vector. When this occurs, the semantics are as if a temporary copy was made, then the operation was performed on the temporary copy, then the result was written back to the destination.

BitVector objects manage their own data, but if one needs to operate on an array that is already allocated then the function templates in the BitVectorSupport name space can be used.

Member Function Documentation

Reads a bit vector from the string and returns the result. The input string has an optional suffix ("h" for hexadecimal) or optioanl prefix ("0x" for hexadecimal, "0b" or binary, or "0" for octal). It does not have both; if a suffix is present then the parser does not search for a prefix. Lack of both prefix and suffix implies decimal format. Any recognized suffix or prefix is stripped from the value, and the number of valid digits is counted and used to calculate the width of the resulting bit vector. For instance, if three octal digits are found (not counting the "0" prefix) then the resulting bit vector will have nine bits – three per digit. The string is then passed to fromBinary, fromOctal, fromDecimal, or fromHex for parsing.

Changes the size of a vector, measured in bits, by either adding or removing bits from the most-significant side of this vector. If new bits are added they are each given the value newBits. Increasing the size of a vector may cause it to reallocate and copy its internal data structures.

Clears bits by assigning false to each bit in the specified range. The convention is that "clear" means to assign false to a bit and should not be confused with the STL usage of the word, namely to erase all values from a container. To erase all bits from a vector, use resize(0).

Clears bits by assigning false to all bits in this vector. The convention is that "clear" means to assign false to to a bit and should not be confused with the STL usage of the word, namely to erase all values from a container. To erase all bits from a vector, use resize(0).

Copies bits from other specified by from into this vector specified by to. The ranges must be the same size and must be valid for their respective vectors. The other vector is permitted to be the same vector as this, in which case from is also permitted to overlap with to.

Swaps bits between range1 of this vector and range2 of the other vector. Both ranges must be the same size and must be valid for their respective vectors. The other vector is permitted to be the same vector as this, but range1 and range2 are not permitted to overlap.

Returns the index for the least significant bit that has the value true in the specified range. The range must be valid for this vector. If the range has no such bits, including the case when the range is empty, then nothing is returned.

Returns the index for the least significant bit that has the value false in the specified range. The range must be valid for this vector. If the range has no such bits, including the case when the range is empty, then nothing is returned.

Returns the index for the most significant bit that has the value true in the specified range. The range must be valid for this vector. If the range has no such bits, including the case when the range is empty, then nothing is returned.

Returns the index for the most significant bit that has the value false in the specified range. The range must be valid for this vector. If the range has no such bits, including the case when the range is empty, then nothing is returned.

Finds the most significant bit that differs between range1 of this vector and range2 of the other vector and returns its offset from the beginning of the ranges. Both ranges must be the same size and must be valid for their respective vectors. If no bits differ, including the case when both ranges are empty, then nothing is returned. The other vector is permitted to be the same as this vector, in which case the ranges are also permitted to overlap.

Note that the return value is not a vector index, but rather an offset with respect to the starting index in each of the ranges.

Finds the most significant bit that differs between the two specified ranges of this vector and returns its offset from the beginning of the ranges. Both ranges must be the same size and must be valid for this vector. If no bits differ, including the case when both ranges are empty, then nothing is returned. The ranges are permitted to overlap.

Note that the return value is not a vector index, but rather an offset with respect to the starting index in each of the ranges.

Finds the most significant bit that differs between this vector and the other vector and return its index. Both vectors must be the same size. If no bits differ, including the case when this vector is empty, then nothing is returned.

Finds the least significant bit that differs between range1 of this vector and range2 of the other vector and returns its offset from the beginning of the ranges. Both ranges must be the same size and must be valid for their respective vectors. If no bits differ, including the case when both ranges are empty, then nothing is returned. The other vector is permitted to be the same as this vector, in which case the ranges are also permitted to overlap.

Note that the return value is not a vector index, but rather an offset with respect to the starting index in each of the ranges.

Finds the least significant bit that differs between the two specified ranges of this vector and returns its offset from the beginning of the ranges. Both ranges must be the same size and must be valid for this vector. If no bits differ, including the case when both ranges are empty, then nothing is returned. The ranges are permitted to overlap.

Note that the return value is not a vector index, but rather an offset with respect to the starting index in each of the ranges.

Finds the least significant bit that differs between this vector and the other vector and return its index. Both vectors must be the same size. If no bits differ, including the case when this vector is empty, then nothing is returned.

Shifts the bits in the specified range of this vector left (to more significant positions) by nShift bits. Bits shifted off the left of the range are discarded; new bits shifted into the right of the range are introduced with the value newBits. The range must be valid for this vector. If nShift is zero or the range is empty then no operation is performed. Specifying an nShift value equal to or greater than the size of the range has the same effect as filling the range with newBits (see also, set and clear, which are probably more efficient).

Shifts all bits of this vector left (to more significant positions) by nShift bits. Bits shifted off the left of this vector are discarded; new bits shifted into the right of this vector are introduced with the value newBits. If nShift is zero or the vector is empty then no operation is performed. Specifying an nShift value equal to or greater than the size of this vector has the same effect as filling the vector with newBits (see also, set and clear, which are probably more efficient).

Shifts the bits in the specified range of this vector right (to less significant positions) by nShift bits. Bits shifted off the right of the range are discarded; new bits shifted into the left of the range are introduced with the value newBits. The range must be valid for this vector. If nShift is zero or the range is empty then no operation is performed. Specifying an nShift value equal to or greater than the size of the range has the same effect as filling the range with newBits (see also, set and clear, which are probably more efficient).

Shifts all bits of this vector right (to less significant positions) by nShift bits. Bits shifted off the right of this vector are discarded; new bits shifted into the left of this vector are introduced with the value newBits. If nShift is zero or the vector is empty then no operation is performed. Specifying an nShift value equal to or greater than the size of this vector has the same effect as filling the vector with newBits (see also, set and clear, which are probably more efficient).

Shifts the bits in the specified range of this vector right (to less significant positions) by nShift bits. Bits shifted off the right of the range are discarded; new bits shifted into the left of the range are introduced with the same value as the original most-significant bit of the range. The range must be valid for this vector. If nShift is zero or the range is empty or a singleton then no operation is performed. Specifying an nShift value equal to or greater than the size of the range has the same effect as filling the range with its original most-significant bit (see also, set and clear, which are probably more efficient).

Shifts the bits in this vector right (to less significant positions) by nShift bits. Bits shifted off the right of this vector are discarded; new bits shifted into the left of this vector are introduced with the same value as the original most-significant bit of this vector. If nShift is zero or the vector is empty or only a single bit then no operation is performed. Specifying an nShift value equal to or greater than the size of this vector has the same effect as filling the vector with its original most-significant bit (see also, set and clear, which are probably more efficient).

Rotates the bits in the specified range to the right (to less significant positions) by shifting right and reintroducing the bits shifted off the right end into the left end. The range must be valid for this vector. If nShift is zero modulo the range size, or the range is empty, then no operation is performed.

Rotates all bits in this vector to the right (to less significant positions) by shifting right and reintroducing the bits shifted off the right end into the left end. If nShift is zero modulo this vector size, or this vector is empty, then no operation is performed.

Rotates the bits in the specified range to the left (to more significant positions) by shifting left and reintroducing the bits shifted off the left end into the right end. The range must be valid for this vector. If nShift is zero modulo the range size, or the range is empty, then no operation is performed.

Rotates all bits in this vector to the left (to more significant positions) by shifting left and reintroducing the bits shifted off the left end into the right end. If nShift is zero modulo this vector size, or this vector is empty, then no operation is performed.

Treats range1 of this vector as an integer and adds one to it, storing the result back into this vector. The range must be valid for this vector. Returns true if all bits were originally set and the result is all clear (i.e., returns the carry-out value) .

Treats the entire vector as an integer and adds one to it, storing the result back into the vector. Returns true if all bits were originally set and the result is all clear (i.e., returns the carry-out value).

Treats range1 of this vector as an integer and subtracts one from it, storing the result back into this vector. The range must be valid for this vector. Returns true if all bits were originally clear and the result is all set (i.e., returns the overflow bit) .

Treats the entire vector as an integer and subtracts one from it, storing the result back into the vector. Returns true if all bits were originally clear and the result is all set (i.e., returns the overflow bit).

Treats range1 of this vector and range2 of the other vector as integers, sums them, and stores the result in range1 of this vector. The ranges must be valid for their respective vectors, and both ranges must be the same size. The other vector is permitted to be the same vector as this, in which case the ranges are also permitted to overlap. Returns the final carry-out value which is not stored in the result.

Treats range1 and range2 of this vector as integers, sums them, and stores the result in range1. The ranges must be valid for this vector and both ranges must be the same size. The are permitted to overlap. Returns the final carry-out value which is not stored in the result.

Treats this vector and the other vector as integers, sums them, and stores the result in this vector. Both vectors must be the same size. The other vector is permitted to be the same as this vector, in which case it numerically doubles the value (like a left shift by one bit). Returns the final carry-out value which is not stored in the result.

Treats range1 of this vector and range2 of the other vector as integers, subtracts other from this, and stores the result in range1 of this vector. The ranges must be valid for their respective vectors, and both ranges must be the same size. The other vector is permitted to be the same vector as this, in which case the ranges are also permitted to overlap. Returns false only when an overflow occurs (i.e., the integer interpretation of this vector is unsigned-greater-than the integer from the other vector). If the vectors are interpreted as two's complement signed integers then an overflow is indicated when both operands have the same sign and the result has a different sign.

Treats range1 and range2 of this vector as integers, subtracts the integer in range2 from the integer in range1, and stores the result in range1 of this vector. The ranges must be valid for this vector, and both ranges must be the same size. The ranges are permitted to overlap. Returns false only when an overflow occurs (i.e., the integer interpretation of range1 is unsigned-greater-than the integer from range2). If the ranges are interpreted as containing two's complement signed integers then an overflow is indicated when both operands have the same sign and the result has a different sign.

Treats this vector and the other vector as integers, subtracts other from this, and stores the result in this vector. Both vectors must be the same size. The other vector is permitted to be the same as this vector, in which case this vector is filled with zero.

Copies bits from range2 of the other vector to range1 of this vector while sign extending. That is, if the destination is larger than the source, the most significant bit of the source is repeated to fill the high order bits of the destination. Both ranges must be valid for their respective vectors. The other vector is permitted to be the same as this vector, in which case the ranges are also permitted to overlap.

Copies bits from range2 of this vector to range1 of this vector while sign extending. That is, if the destination is larger than the source, the most significant bit of the source is repeated to fill the high order bits of the destination. Both ranges must be valid for this vector, and are permitted to overlap.

Copies bits from the other vector to this vector while sign extending. That is, if the destination is larger than the source, the most significant bit of the source is repeated to fill the high order bits of the destination.

Computes the bit-wise AND of range1 from this vector and range2 of the other vector, storing the result in range1. The ranges must be valid for their respective vectors and must be the same size. The other vector is permitted to refer to this vector, in which case the ranges are also permitted to overlap.

Computes the bit-wise OR of range1 from this vector and range2 of the other vector, storing the result in range1. The ranges must be valid for their respective vectors and must be the same size. The other vector is permitted to refer to this vector, in which case the ranges are also permitted to overlap.

Computes the bit-wise XOR of range1 from this vector and range2 of the other vector, storing the result in range1. The ranges must be valid for their respective vectors and must be the same size. The other vector is permitted to refer to this vector, in which case the ranges are also permitted to overlap.

Compares range1 from this vector with range2 from the other vector as integers and returns a value whose sign indicates the ordering relationship between the two ranges. Returns negative if the range1 value is less than the range2 value, returns zero if they are equal, and returns positive if the range1 value is greater than the range2 value. The ranges must be valid for their respective vectors, and need not be the same size (the smaller range will be temporarily zero extended on its most significant end). An empty range is treated as zero. The other vector is permitted to refer to this vector, in which case the ranges are also permitted to overlap.

Compares range1 and range2 from this vector as integers and returns a value whose sign indicates the ordering relationship between the two ranges. Returns negative if the range1 value is less than the range2 value, returns zero if they are equal, and returns positive if the range1 value is greater than the range2 value. The ranges must be valid for this vector, and need not be the same size (the smaller range will be temporarily zero extended on its most significant end). An empty range is interpreted as zero. The ranges are permitted to overlap.

Compares the bits of this vector with the bits of other as integers and returns a value whose sign indicates the ordering relationship between the two ranges. Returns negative if this value is less than the other value, returns zero if they are equal, and returns positive if this value is greater than the other value. The vectors need not be the same size (the smaller vector will be temporarily zero extended on its most significant end). An empty vector is treated as zero.

Compares range1 from this vector with range2 from the other vector as signed, two's complement integers and returns a value whose sign indicates the ordering relationship between the two ranges. Returns negative if the range1 value is less than the range2 value, returns zero if they are equal, and returns positive if the range1 value is greater than the range2 value. The ranges must be valid for their respective vectors, and need not be the same size (the smaller range will be temporarily zero extended on its most significant end). An empty range is treated as zero. The other vector is permitted to refer to this vector, in which case the ranges are also permitted to overlap.

Compares range1 and range2 from this vector as signed, two's complement integers and returns a value whose sign indicates the ordering relationship between the two ranges. Returns negative if the range1 value is less than the range2 value, returns zero if they are equal, and returns positive if the range1 value is greater than the range2 value. The ranges must be valid for this vector, and need not be the same size (the smaller range will be temporarily zero extended on its most significant end). An empty range is interpreted as zero. The ranges are permitted to overlap.

Compares the bits of this vector with the bits of other as signed, two's complement integers and returns a value whose sign indicates the ordering relationship between the two ranges. Returns negative if this value is less than the other value, returns zero if they are equal, and returns positive if this value is greater than the other value. The vectors need not be the same size (the smaller vector will be temporarily zero extended on its most significant end). An empty vector is treated as zero.

Returns the bits of the specified range by interpreting them as an unsigned integer. The range must be valid for this vector. If the range contains more than 64 bits then only the low-order 64 bits are considered.

Returns a string which is the hexadecimal representation of the bits in the specified range. The range must be valid for this vector. No prefix or suffix is added (e.g., no leading "0x" or trailing "h"). The number of digits in the return value is the minimum required to explicitly represent each bit of the range, including leading zeros; an empty range will return an empty string. The returned string is lower case.

Returns a string which is the hexadecimal representation of the bits in this vector. No prefix or suffix is added (e.g., no leading "0x" or trailing "h"). The number of digits in the return value is the minimum required to explicitly represent each bit of the vector, including leading zeros; an empty vector will return an empty string. The returned string is lower case.

Returns a string which is the octal representation of the bits in the specified range. The range must be valid for this vector. No prefix or suffix is added (e.g., no extra leading "0" or trailing "o"). The number of digits in the return value is the minimum required to explicitly represent each bit of the range, including leading zeros; an empty range will return an empty string.

Returns a string which is the octal representation of the bits in this vector. No prefix or suffix is added (e.g., no leading "0" or trailing "o"). The number of digits in the return value is the minimum required to explicitly represent each bit of the vector, including leading zeros; an empty vector will return an empty string.

Returns a string which is the binary representation of the bits in the specified range. The range must be valid for this vector. No prefix or suffix is added (e.g., no extra leading or trailing "b"). The number of digits in the return value is the minimum required to explicitly represent each bit of the range, including leading zeros; an empty range will return an empty string.

Returns a string which is the binary representation of the bits in this vector. No prefix or suffix is added (e.g., no leading or trailing "b"). The number of digits in the return value is the minimum required to explicitly represent each bit of the vector, including leading zeros; an empty vector will return an empty string.

Assigns the specified value to the bits indicated by range of this vector. If the range contains fewer than 64 bits then only the low order bits of value are used; if the range contains more than 64 bits then the high-order bits are cleared. The range must be a valid range for this vector.

Assigns the specified value to this vector. If this vector contains fewer than 64 bits then only the low order bits of value are used; if this vector contains more than 64 bits then the high-order bits are cleared. The size of this vector is not changed by this operation.

Assigns the specified value, represented in decimal, to the specified range of this vector. The input string must contain only valid decimal digits '0' through '9' or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. The range must be valid for this vector. If the number of supplied digits is larger than what is required to initialize the specified range then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire range then the high order bits of the range are cleared.

Assigns the specified value, represented in decimal, to this vector. The input string must contain only valid decimal digits '0' through '9' or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. If the number of supplied digits is larger than what is required to initialize this vector then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire vector then the high order bits of the vector are cleared. The size of this vector is not changed by this operation.

Assigns the specified value, represented in hexadecimal, to the specified range of this vector. The input string must contain only valid hexadecimal digits '0' through '9', 'a' through 'f', and 'A' through 'F', or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. The range must be valid for this vector. If the number of supplied digits is larger than what is required to initialize the specified range then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire range then the high order bits of the range are cleared.

Assigns the specified value, represented in hexadecimal, to this vector. The input string must contain only valid hexadecimal digits '0' through '9', 'a' through 'f', and 'A' through 'F', or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. If the number of supplied digits is larger than what is required to initialize this vector then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire vector then the high order bits of the vector are cleared. The size of this vector is not changed by this operation.

Assigns the specified value, represented in octal, to the specified range of this vector. The input string must contain only valid octal digits '0' through '7' or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. The range must be valid for this vector. If the number of supplied digits is larger than what is required to initialize the specified range then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire range then the high order bits of the range are cleared.

Assigns the specified value, represented in octal, to this vector. The input string must contain only valid octal digits '0' through '7' or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. If the number of supplied digits is larger than what is required to initialize this vector then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire vector then the high order bits of the vector are cleared. The size of this vector is not changed by this operation.

Assigns the specified value, represented in binary, to the specified range of this vector. The input string must contain only valid binary digits '0' and '1' or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. The range must be valid for this vector. If the number of supplied digits is larger than what is required to initialize the specified range then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire range then the high order bits of the range are cleared.

Assigns the specified value, represented in binary, to this vector. The input string must contain only valid binary digits '0' and '1' or the underscore character (to make long strings more readable), or else an std::runtime_error is thrown. If the number of supplied digits is larger than what is required to initialize this vector then the extra data is discarded. On the other hand, if the length of the string is insufficient to initialize the entire vector then the high order bits of the vector are cleared. The size of this vector is not changed by this operation.