[#BloombergLP-bdlc-BitArray]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlc.adoc[bdlc]::BitArray
:relfileprefix: ../../
:mrdocs:

This class implements an efficient, value‐semantic array of boolean (a.k.a. bit, i.e., binary digit) values stored in contiguous memory. The physical capacity of this array may grow, but never shrinks. Capacity may be reserved initially via a constructor, or at any time thereafter by using the `reserveCapacity` method; otherwise, capacity will be increased automatically as needed. Note that capacity is not a _salient_ attribute of this object, and, as such, does not contribute to overall value. Also note that this class provides an implicit no‐throw guarantee for all methods (including manipulators) that do not attempt to alter capacity.

== Synopsis

Declared in `<bdlc_bitarray.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class BitArray;
----

== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/BitArray/_04enum.adoc[`Unnamed enum`] 
| Constants describing the storage representation of a `BitArray`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/BitArray/2constructor-011.adoc[`BitArray`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlc/BitArray/2destructor.adoc[`~BitArray`] [.small]#[destructor]#
| Destroy this object.
| xref:BloombergLP/bdlc/BitArray/operator_assign.adoc[`operator=`] 
| Assign to this array the value of the specified `rhs` array, and return a non‐`const` reference to this array.
| xref:BloombergLP/bdlc/BitArray/allocator.adoc[`allocator`] 
| Return the allocator used by this object to supply memory.
| xref:BloombergLP/bdlc/BitArray/andEqual-04.adoc[`andEqual`] 
| `andEqual` overloads
| xref:BloombergLP/bdlc/BitArray/append-0b.adoc[`append`] 
| `append` overloads
| xref:BloombergLP/bdlc/BitArray/assign-01.adoc[`assign`] 
| `assign` overloads
| xref:BloombergLP/bdlc/BitArray/assign0-00.adoc[`assign0`] 
| `assign0` overloads
| xref:BloombergLP/bdlc/BitArray/assign1-0d.adoc[`assign1`] 
| `assign1` overloads
| xref:BloombergLP/bdlc/BitArray/assignAll.adoc[`assignAll`] 
| Set all bits in this array to the specified `value`.
| xref:BloombergLP/bdlc/BitArray/assignAll0.adoc[`assignAll0`] 
| Set to 0 the value of every bit in this array.
| xref:BloombergLP/bdlc/BitArray/assignAll1.adoc[`assignAll1`] 
| Set to 1 the value of every bit in this array.
| xref:BloombergLP/bdlc/BitArray/assignBits.adoc[`assignBits`] 
| Assign the low‐order specified `numBits` from the specified `srcBits` to this object, starting at the specified `index`. The behavior is undefined unless `numBits <= k_BITS_PER_UINT64` and `index + numBits <= length()`.
| xref:BloombergLP/bdlc/BitArray/bdexStreamIn.adoc[`bdexStreamIn`] 
| Assign to this object the value read from the specified input `stream` using the specified `version` format, and return a reference to `stream`. If `stream` is initially invalid, this operation has no effect. If `version` is not supported, this object is unaltered and `stream` is invalidated, but otherwise unmodified. If `version` is supported but `stream` becomes invalid during this operation, this object has an undefined, but valid, state. Note that no version is read from `stream`. See the `bslx` package‐level documentation for more information on BDEX streaming of value‐semantic types and containers.
| xref:BloombergLP/bdlc/BitArray/bdexStreamOut.adoc[`bdexStreamOut`] 
| Write the value of this object, using the specified `version` format, to the specified output `stream`, and return a reference to `stream`. If `stream` is initially invalid, this operation has no effect. If `version` is not supported, `stream` is invalidated, but otherwise unmodified. Note that `version` is not written to `stream`. See the `bslx` package‐level documentation for more information on BDEX streaming of value‐semantic types and containers.
| xref:BloombergLP/bdlc/BitArray/bits.adoc[`bits`] 
| Return the specified `numBits` beginning at the specified `index` in this array as the low‐order bits of the returned value. The behavior is undefined unless `numBits <= sizeof(uint64_t) * CHAR_BIT` and `index + numBits <= length()`.
| xref:BloombergLP/bdlc/BitArray/find0AtMaxIndex.adoc[`find0AtMaxIndex`] 
| Return the index of the most‐significant 0 bit in this array in the range optionally specified by `begin` and `end`, and `k_INVALID_INDEX` otherwise. The range is `[begin .. effectiveEnd)]`, where `effectiveEnd == length()` if `end` is not specified and `effectiveEnd == end` otherwise. The behavior is undefined unless `begin <= effectiveEnd <= length()`.
| xref:BloombergLP/bdlc/BitArray/find0AtMinIndex.adoc[`find0AtMinIndex`] 
| Return the index of the least‐significant 0 bit in this array in the range optionally specified by `begin` and `end`, and `k_INVALID_INDEX` otherwise. The range is `[begin .. effectiveEnd)]`, where `effectiveEnd == length()` if `end` is not specified and `effectiveEnd == end` otherwise. The behavior is undefined unless `begin <= effectiveEnd <= length()`.
| xref:BloombergLP/bdlc/BitArray/find1AtMaxIndex.adoc[`find1AtMaxIndex`] 
| Return the index of the most‐significant 1 bit in this array in the range optionally specified by `begin` and `end`, and `k_INVALID_INDEX` otherwise. The range is `[begin .. effectiveEnd)]`, where `effectiveEnd == length()` if `end` is not specified and `effectiveEnd == end` otherwise. The behavior is undefined unless `begin <= effectiveEnd <= length()`.
| xref:BloombergLP/bdlc/BitArray/find1AtMinIndex.adoc[`find1AtMinIndex`] 
| Return the index of the least‐significant 1 bit in this array in the range optionally specified by `begin` and `end`, and `k_INVALID_INDEX` otherwise. The range is `[begin .. effectiveEnd)]`, where `effectiveEnd == length()` if `end` is not specified and `effectiveEnd == end` otherwise. The behavior is undefined unless `begin <= effectiveEnd <= length()`.
| xref:BloombergLP/bdlc/BitArray/insert-08.adoc[`insert`] 
| `insert` overloads
| xref:BloombergLP/bdlc/BitArray/isAny0.adoc[`isAny0`] 
| Return `true` if the value of any bit in this array is 0, and `false` otherwise.
| xref:BloombergLP/bdlc/BitArray/isAny1.adoc[`isAny1`] 
| Return `true` if the value of any bit in this array is 1, and `false` otherwise.
| xref:BloombergLP/bdlc/BitArray/isEmpty.adoc[`isEmpty`] 
| Return `true` if the length of this bit array is 0, and `false` otherwise.
| xref:BloombergLP/bdlc/BitArray/length.adoc[`length`] 
| Return the number of bits in this array.
| xref:BloombergLP/bdlc/BitArray/minusEqual-0c.adoc[`minusEqual`] 
| `minusEqual` overloads
| xref:BloombergLP/bdlc/BitArray/num0.adoc[`num0`] 
| Return the number of bits in the range optionally specified by `begin` and `end` having a value of 0. The range is `[begin .. effectiveEnd)]`, where `effectiveEnd == length()` if `end` is not specified and `effectiveEnd == end` otherwise. The behavior is undefined unless `begin <= effectiveEnd <= length()`.
| xref:BloombergLP/bdlc/BitArray/num1.adoc[`num1`] 
| Return the number of bits in the range optionally specified by `begin` and `end` having a value of 1. The range is `[begin .. effectiveEnd)]`, where `effectiveEnd == length()` if `end` is not specified and `effectiveEnd == end` otherwise. The behavior is undefined unless `begin <= effectiveEnd <= length()`.
| xref:BloombergLP/bdlc/BitArray/operator_and_eq.adoc[`operator&=`] 
| Bitwise AND the value of the specified `rhs` array with the value of this array (retaining the results), and return a non‐`const` reference to this object. The length of the result will be the maximum of the lengths of this object and `rhs`, where any most‐significant bits that are represented in one of the two but not the other will be set to 0. Note that `a &= b;` will result in the same value of `a` as `a = a & b;`.
| xref:BloombergLP/bdlc/BitArray/operator_minus_eq.adoc[`operator‐=`] 
| Bitwise MINUS the value of the specified `rhs` array from the value of this array (retaining the results), and return a non‐`const` reference to this object. The length of the result will be the maximum of the lengths of this object and `rhs`. If `length() > rhs.length()`, the unmatched most‐significant bits in this array are left unchanged; otherwise, any high‐order bits of the result that were not present in this object prior to the operation will be set to 0. Note that `a ‐= b;` will result in the same value of `a` as `a = a ‐ b;` and if `a` and `b` are the same length, `a ‐= b;` will result in the same value of `a` as `a &= ~b;` or `a = a & ~b;`.
| xref:BloombergLP/bdlc/BitArray/operator_lshift_eq.adoc[`operator<<=`] 
| Shift the bits in this array LEFT by the specified `numBits`, filling lower‐order bits with zeros (retaining the results), and return a non‐`const` reference to this object. The behavior is undefined unless `numBits <= length()`. Note that the length of this array is unchanged and the highest‐order `numBits` are discarded.
| xref:BloombergLP/bdlc/BitArray/operator_rshift_eq.adoc[`operator>>=`] 
| Shift the bits in this array RIGHT by the specified `numBits`, filling higher‐order bits with zeros and discarding low‐order bits, and return a non‐`const` reference to this object. The behavior is undefined unless `numBits <= length()`. Note that the length of this array is unchanged.
| xref:BloombergLP/bdlc/BitArray/operator_subs.adoc[`operator[]`] 
| Return the value of the bit at the specified `index` in this array. The behavior is undefined unless `index < length()`.
| xref:BloombergLP/bdlc/BitArray/operator_xor_eq.adoc[`operatorˆ=`] 
| Bitwise XOR the value of the specified `rhs` array with the value of this array (retaining the results), and return a non‐`const` reference to this object. If `length() > rhs.length()`, the unmatched most‐significant bits in this array are left unchanged; otherwise, any unmatched most‐significant bits in `rhs` are propagated to the result without modification. Note that `a ˆ= b;` will result in the same value of `a` as `a = a ˆ b;`.
| xref:BloombergLP/bdlc/BitArray/operator_or_eq.adoc[`operator|=`] 
| Bitwise OR the value of the specified `rhs` array with the value of this array (retaining the results), and return a non‐`const` reference to this object. If `length() > rhs.length()`, the unmatched most‐significant bits in this array are left unchanged; otherwise, any unmatched most‐significant bits in `rhs` are propagated to the result without modification. Note that `a |= b;` will result in the same value of `a` as `a = a | b;`.
| xref:BloombergLP/bdlc/BitArray/orEqual-076.adoc[`orEqual`] 
| `orEqual` overloads
| xref:BloombergLP/bdlc/BitArray/print.adoc[`print`] 
| Format this object to the specified output `stream` at the optionally specified indentation `level` and return a non‐`const` reference to `stream`. If `level` is specified, optionally specify `spacesPerLevel`, the number of spaces per indentation level for this and all of its nested objects. Each line is indented by the absolute value of `level * spacesPerLevel`. If `level` is negative, suppress indentation of the first line. 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/bdlc/BitArray/remove-09.adoc[`remove`] 
| `remove` overloads
| xref:BloombergLP/bdlc/BitArray/removeAll.adoc[`removeAll`] 
| Remove all of the bits in this array, leaving the length 0, but having no effect on capacity.
| xref:BloombergLP/bdlc/BitArray/reserveCapacity.adoc[`reserveCapacity`] 
| Reserve sufficient internal capacity to accommodate a length of at least the specified `numBits` without reallocation. If an exception is thrown during this reallocation attempt (i.e., by the memory allocator indicated at construction) the value of this array is guaranteed to be unchanged.
| xref:BloombergLP/bdlc/BitArray/rotateLeft.adoc[`rotateLeft`] 
| Shift the values in this array to the left by the specified `numBits` positions, with the high‐order values "rotating" into the low‐order bits. The behavior is undefined unless `numBits <= length()`. Note that the length of this array remains unchanged.
| xref:BloombergLP/bdlc/BitArray/rotateRight.adoc[`rotateRight`] 
| Shift the values in this array to the right by the specified `numBits` positions, with the low‐order values "rotating" into the high‐order bits. The behavior is undefined unless `numBits <= length()`. Note that the length of this array remains unchanged.
| xref:BloombergLP/bdlc/BitArray/setLength.adoc[`setLength`] 
| Set the number of bits in this array to the specified `newLength`. If `newLength < length()`, bits at index positions at or above `newLength` are removed; otherwise, any new bits (at or above the current length) are initialized to the optionally specified `value`, or to 0 if `value` is not specified.
| xref:BloombergLP/bdlc/BitArray/swap.adoc[`swap`] 
| Efficiently exchange the value of this object with the value of the specified `other` object. This method provides the no‐throw exception‐safety guarantee. The behavior is undefined unless this object was created with the same allocator as `other`.
| xref:BloombergLP/bdlc/BitArray/swapBits.adoc[`swapBits`] 
| Efficiently exchange the values of the bits at the specified `index1` and `index2` indices. The behavior is undefined unless `index1 < length()` and `index2 < length()`.
| xref:BloombergLP/bdlc/BitArray/toggle-0d1.adoc[`toggle`] 
| `toggle` overloads
| xref:BloombergLP/bdlc/BitArray/toggleAll.adoc[`toggleAll`] 
| Complement the value of every bit in this array. Note that the behavior is analogous to applying the `~` operator to an object of fundamental type `unsigned int`.
| xref:BloombergLP/bdlc/BitArray/xorEqual-0e.adoc[`xorEqual`] 
| `xorEqual` overloads
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/BitArray/maxSupportedBdexVersion-07.adoc[`maxSupportedBdexVersion`] 
| `maxSupportedBdexVersion` overloads
|===


== Static Data Members

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


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlc/operator_eq-04d.adoc[BloombergLP::bdlc::operator==]`
| Return `true` if the specified `lhs` and `rhs` arrays have the same value, and `false` otherwise. Two arrays have the same value if they have the same length, and corresponding bits at each bit position have the same value.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/operator_not_eq-008.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` arrays do not have the same value, and `false` otherwise. Two arrays do not have the same value if they do not have the same length, or there is at least one valid index position at which corresponding bits do not have the same value.
| xref:BloombergLP/bdlc/operator_bitand.adoc[`operator&`]
| Return the value that is the bitwise AND of the specified `lhs` and `rhs` arrays. The length of the resulting bit array will be the maximum of that of `lhs` and `rhs`, with any unmatched high‐order bits set to 0. Note that this behavior is consistent with zero‐extending a copy of the shorter array.
| xref:BloombergLP/bdlc/operator_minus-0a9.adoc[`operator‐`]
| Return the value that is the bitwise MINUS of the specified `lhs` and `rhs` arrays. The length of the resulting bit array will be the maximum of that of `lhs` and `rhs`, with any unmatched high‐order `lhs` bits copied unchanged, and any unmatched high‐order `rhs` bits set to 0. Note that this behavior is consistent with zero‐extending a copy of the shorter array.
| xref:BloombergLP/bdlc/operator_lshift-0688.adoc[`operator<<`]
| Return the value of the specified `array` left‐shifted by the specified `numBits` positions, having filled the lower‐index positions with zeros. The behavior is undefined unless `numBits <= array.length()`. Note that the length of the result equals the length of the original array, and that the highest‐order `numBits` are discarded in the result.
| xref:BloombergLP/bdlc/operator_rshift.adoc[`operator>>`]
| Return the value of the specified `array` right‐shifted by the specified `numBits` positions, having filled the higher‐index positions with zeros. The behavior is undefined unless `numBits <= array.length()`. Note that the length of the result equals the length of the original array, and that the lowest‐order `numBits` are discarded in the result.
| xref:BloombergLP/bdlc/operator_xor.adoc[`operatorˆ`]
| Return the value that is the bitwise XOR of the specified `lhs` and `rhs` arrays. The length of the resulting bit array will be the maximum of that of `lhs` and `rhs`, with any unmatched high‐order bits copied unchanged. Note that this behavior is consistent with zero‐extending a copy of the shorter array.
| xref:BloombergLP/bdlc/operator_bitor.adoc[`operator|`]
| Return the value that is the bitwise OR of the specified `lhs` and `rhs` arrays. The length of the resulting bit array will be the maximum of that of `lhs` and `rhs`, with any unmatched high‐order bits copied unchanged. Note that this behavior is consistent with zero‐extending a copy of the shorter array.
| xref:BloombergLP/bdlc/operator_bitnot.adoc[`operator~`]
| Return the bitwise complement ("toggle") of the specified `array`.
| xref:BloombergLP/bdlc/swap-00b.adoc[`swap`]
| Exchange the values of the specified `a` and `b` objects. This function provides the no‐throw exception‐safety guarantee if the two objects were created with the same allocator and the basic guarantee otherwise.
|===


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