[#BloombergLP-bdlb-BitStringUtil]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlb.adoc[bdlb]::BitStringUtil
:relfileprefix: ../../
:mrdocs:

This `struct` provides a namespace for a suite of static functions to manipulate and access sequences of bits stored in an array of `uint64_t` (also known as a "bit string"; see {The "Bit String" Pseudo‐Type}).

== Synopsis

Declared in `<bdlb_bitstringutil.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
struct BitStringUtil;
----

== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/BitStringUtil/_04enum.adoc[`Unnamed enum`] 
| Bit‐string utility constants.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/BitStringUtil/andEqual.adoc[`andEqual`] 
| Bitwise AND the specified `numBits` of the specified `dstBitString` starting at the specified `dstIndex` with the `numBits` of the specified `srcBitString` starting at the specified `srcIndex`, and write the result over the bits that were read from `dstBitString`. The behavior is undefined unless `dstBitString` has a length of at least `dstIndex + numBits` and `srcBitString` has a length of at least `srcIndex + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/areEqual-0a.adoc[`areEqual`] 
| `areEqual` overloads
| xref:BloombergLP/bdlb/BitStringUtil/assign-01.adoc[`assign`] 
| `assign` overloads
| xref:BloombergLP/bdlb/BitStringUtil/assign0-04.adoc[`assign0`] 
| `assign0` overloads
| xref:BloombergLP/bdlb/BitStringUtil/assign1-07.adoc[`assign1`] 
| `assign1` overloads
| xref:BloombergLP/bdlb/BitStringUtil/assignBits.adoc[`assignBits`] 
| Assign the low‐order specified `numBits` from the specified `srcValue` to the `numBits` starting at the specified `index` in the specified `bitString`. The behavior is undefined unless `numBits <= k_BITS_PER_UINT64` and `bitString` has a capacity of at least `index + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/bit.adoc[`bit`] 
| Return the bit value at the specified `index` in the specified `bitString`. The behavior is undefined unless `index` is less than the length of `bitString`.
| xref:BloombergLP/bdlb/BitStringUtil/bits.adoc[`bits`] 
| Return the specified `numBits` beginning at the specified `index` in the specified `bitString` as the low‐order bits of the returned value. The behavior is undefined unless `numBits <= k_BITS_PER_UINT64` and `bitString` has a length of at least `index + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/copy.adoc[`copy`] 
| Copy to the specified `dstBitString`, beginning at the specified `dstIndex`, the specified `numBits` beginning at the specified `srcIndex` in the specified `srcBitString`. This function works correctly regardless of whether the source and destination ranges overlap. The behavior is undefined unless `dstBitString` has a capacity of at least `dstIndex + numBits` and `srcBitString` has a length of at least `srcIndex + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/copyRaw.adoc[`copyRaw`] 
| Copy to the specified `dstBitString`, beginning at the specified `dstIndex`, the specified `numBits` beginning at the specified `srcIndex` in the specified `srcBitString`. The behavior is undefined unless `dstBitString` has a capacity of at least `dstIndex + numBits`, `srcBitString` has a length of at least `srcIndex + numBits`, and the source and destination ranges either do not overlap, or the destination range is equal to the source range, or the start of the destination range is below the start of the source range.
| xref:BloombergLP/bdlb/BitStringUtil/find0AtMaxIndex-03.adoc[`find0AtMaxIndex`] 
| `find0AtMaxIndex` overloads
| xref:BloombergLP/bdlb/BitStringUtil/find0AtMinIndex-05.adoc[`find0AtMinIndex`] 
| `find0AtMinIndex` overloads
| xref:BloombergLP/bdlb/BitStringUtil/find1AtMaxIndex-09.adoc[`find1AtMaxIndex`] 
| `find1AtMaxIndex` overloads
| xref:BloombergLP/bdlb/BitStringUtil/find1AtMinIndex-05.adoc[`find1AtMinIndex`] 
| `find1AtMinIndex` overloads
| xref:BloombergLP/bdlb/BitStringUtil/insert.adoc[`insert`] 
| Insert the specified `numBits`, each having the specified `value`, into the specified `bitString` having the specified `initialLength`, beginning at the specified `dstIndex`. Bits at or above `dstIndex` are shifted up by `numBits` index positions and the length of `bitString` is increased by `numBits`. The behavior is undefined unless `dstIndex <= initialLength` and `bitString` has a capacity of at least `initialLength + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/insert0.adoc[`insert0`] 
| Insert the specified `numBits` 0 bits into the specified `bitString` having the specified `initialLength` beginning at the specified `dstIndex`. Bits at or above `dstIndex` are shifted up by `numBits` index positions and the length of `bitString` is increased by `numBits`. The behavior is undefined unless `dstIndex <= initialLength` and `bitString` has a capacity of at least `initialLength + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/insert1.adoc[`insert1`] 
| Insert the specified `numBits` 1 bits into the specified `bitString` having the specified `initialLength` beginning at the specified `dstIndex`. Bits at or above `dstIndex` are shifted up by `numBits` index positions and the length of `bitString` is increased by `numBits`. The behavior is undefined unless `dstIndex <= initialLength` and `bitString` has a capacity of at least `initialLength + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/insertRaw.adoc[`insertRaw`] 
| Insert the specified `numBits` into the specified `bitString` having the specified `initialLength` beginning at the specified `dstIndex`. Bits at or above `dstIndex` are shifted up by `numBits` index positions and the length of `bitString` is increased by `numBits`. The values of the inserted bits are undefined. The behavior is undefined unless `dstIndex <= initialLength` and `bitString` has a capacity of at least `initialLength + numBits`. Note that the inserted bits are not assigned any value.
| xref:BloombergLP/bdlb/BitStringUtil/isAny0.adoc[`isAny0`] 
| Return `true` if any of the specified `numBits` beginning at the specified `index` in the specified `bitString` are 0, and `false` otherwise. The behavior is undefined unless `bitString` has a length of at least `index + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/isAny1.adoc[`isAny1`] 
| Return `true` if any of the specified `numBits` beginning at the specified `index` in the specified `bitString` are 1, and `false` otherwise. The behavior is undefined unless `bitString` has a length of at least `index + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/minusEqual.adoc[`minusEqual`] 
| Bitwise MINUS the specified `numBits` of the specified `srcBitString` starting at the specified `srcIndex` from the `numBits` of the specified `dstBitString` starting at the specified `dstIndex`, and write the result over the bits that were read from `dstBitString`. The behavior is undefined unless `dstBitString` has a length of at least `dstIndex + numBits` and `srcBitString` has a length of at least `srcIndex + numBits`. Note that the logical difference `A ‐ B` is defined to be `A & !B`.
| xref:BloombergLP/bdlb/BitStringUtil/num0.adoc[`num0`] 
| Return the number of 0 bits in the specified `numBits` beginning at the specified `index` in the specified `bitString`. The behavior is undefined unless `bitString` has a length of at least `index + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/num1.adoc[`num1`] 
| Return the number of 1 bits in the specified `numBits` beginning at the specified `index` in the specified `bitString`. The behavior is undefined unless `bitString` has a length of at least `index + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/orEqual.adoc[`orEqual`] 
| Bitwise OR the specified `numBits` of the specified `dstBitString` starting at the specified `dstIndex` with the `numBits` of the specified `srcBitString` starting at the specified `srcIndex`, and write the result over the bits that were read from `dstBitString`. The behavior is undefined unless `dstBitString` has a length of at least `dstIndex + numBits` and `srcBitString` has a length of at least `srcIndex + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/print.adoc[`print`] 
| Format to the specified output `stream` the specified low‐order `numBits` in the specified `bitString` in hexadecimal, and return a reference to `stream`. The highest order bits are printed first, in groups of 16 nibbles, 64 nibbles per line (in the case of multi‐line output). Optionally specify `level`, the indentation level for each line output. Optionally specify `spacesPerLevel`, the number of spaces per indentation level. Each line is indented by the absolute value of `level * spacesPerLevel`. If `spacesPerLevel` is negative, suppress line breaks and format the entire output on one line. If `stream` is initially invalid, this operation has no effect. Note that a trailing newline is provided in multiline mode only.
| xref:BloombergLP/bdlb/BitStringUtil/remove.adoc[`remove`] 
| Remove the specified `numBits` from the specified `bitString` of the specified `length` beginning at the specified `index`. Bits above `index + numBits` are shifted down by `numBits` index positions and the length of `bitString` is reduced by `numBits`. The values of the vacated high‐order bits are not modified. The behavior is undefined unless `index + numBits <= length`.
| xref:BloombergLP/bdlb/BitStringUtil/removeAndFill0.adoc[`removeAndFill0`] 
| Remove the specified `numBits` from the specified `bitString` having the specified `length` beginning at the specified `index`. Bits above `index + numBits` are shifted down by `numBits` index positions and the last `numBits` of `bitString` are set to 0. The length of `bitString` is not changed. The behavior is undefined unless `index + numBits <= length`.
| xref:BloombergLP/bdlb/BitStringUtil/removeAndFill1.adoc[`removeAndFill1`] 
| Remove the specified `numBits` from the specified `bitString` having the specified `length` beginning at the specified `index`. Bits above `index + numBits` are shifted down by `numBits` index positions and the last `numBits` of `bitString` are set to 1. The length of `bitString` is not changed. The behavior is undefined unless `index + numBits <= length`.
| xref:BloombergLP/bdlb/BitStringUtil/swapRaw.adoc[`swapRaw`] 
| Exchange the specified `numBits` beginning at the specified `index1` in the specified `bitString1` with the `numBits` beginning at the specified `index2` in the specified `bitString2`. The behavior is undefined unless `bitString1` has a length of at least `index1 + numBits`, `bitString2` has a length of at least `index2 + numBits`, and there is _no_ overlap between the swapped ranges of bits.
| xref:BloombergLP/bdlb/BitStringUtil/toggle.adoc[`toggle`] 
| Invert the values of the specified `numBits` in the specified `bitString` beginning at the specified `index`. The behavior is undefined unless `bitString` has a length of at least `index + numBits`.
| xref:BloombergLP/bdlb/BitStringUtil/xorEqual.adoc[`xorEqual`] 
| Bitwise XOR the specified `numBits` of the specified `dstBitString` starting at the specified `dstIndex` with the `numBits` of the specified `srcBitString` starting at the specified `srcIndex`, and write the result over the bits that were read from `dstBitString`. The behavior is undefined unless `dstBitString` has a length of at least `dstIndex + numBits` and `srcBitString` has a length of at least `srcIndex + numBits`.
|===


== Static Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlb/BitStringUtil/k_INVALID_INDEX.adoc[`k_INVALID_INDEX`] 
| Sentinel index value indicating an invalid bit position.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#