22 General utilities library [utilities]

22.9 Bitsets [bitset]

22.9.1 Header <bitset> synopsis [bitset.syn]

1
#
The header <bitset> defines a class template and several related functions for representing and manipulating fixed-size sequences of bits.
#include <string> // see [string.syn] #include <iosfwd> // for istream ([istream.syn]), ostream ([ostream.syn]), see [iosfwd.syn] namespace std { template<size_t N> class bitset; // [bitset.operators], bitset operators template<size_t N> constexpr bitset<N> operator&(const bitset<N>&, const bitset<N>&) noexcept; template<size_t N> constexpr bitset<N> operator|(const bitset<N>&, const bitset<N>&) noexcept; template<size_t N> constexpr bitset<N> operator^(const bitset<N>&, const bitset<N>&) noexcept; template<class charT, class traits, size_t N> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, bitset<N>& x); template<class charT, class traits, size_t N> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const bitset<N>& x); }

22.9.2 Class template bitset [template.bitset]

22.9.2.1 General [template.bitset.general]

🔗
namespace std { template<size_t N> class bitset { public: // bit reference class reference { friend class bitset; constexpr reference() noexcept; public: constexpr reference(const reference&) = default; constexpr ~reference(); constexpr reference& operator=(bool x) noexcept; // for b[i] = x; constexpr reference& operator=(const reference&) noexcept; // for b[i] = b[j]; constexpr bool operator~() const noexcept; // flips the bit constexpr operator bool() const noexcept; // for x = b[i]; constexpr reference& flip() noexcept; // for b[i].flip(); }; // [bitset.cons], constructors constexpr bitset() noexcept; constexpr bitset(unsigned long long val) noexcept; template<class charT, class traits, class Allocator> constexpr explicit bitset( const basic_string<charT, traits, Allocator>& str, typename basic_string<charT, traits, Allocator>::size_type pos = 0, typename basic_string<charT, traits, Allocator>::size_type n = basic_string<charT, traits, Allocator>::npos, charT zero = charT('0'), charT one = charT('1')); template<class charT> constexpr explicit bitset( const charT* str, typename basic_string<charT>::size_type n = basic_string<charT>::npos, charT zero = charT('0'), charT one = charT('1')); // [bitset.members], bitset operations constexpr bitset& operator&=(const bitset& rhs) noexcept; constexpr bitset& operator|=(const bitset& rhs) noexcept; constexpr bitset& operator^=(const bitset& rhs) noexcept; constexpr bitset& operator<<=(size_t pos) noexcept; constexpr bitset& operator>>=(size_t pos) noexcept; constexpr bitset operator<<(size_t pos) const noexcept; constexpr bitset operator>>(size_t pos) const noexcept; constexpr bitset& set() noexcept; constexpr bitset& set(size_t pos, bool val = true); constexpr bitset& reset() noexcept; constexpr bitset& reset(size_t pos); constexpr bitset operator~() const noexcept; constexpr bitset& flip() noexcept; constexpr bitset& flip(size_t pos); // element access constexpr bool operator[](size_t pos) const; constexpr reference operator[](size_t pos); constexpr unsigned long to_ulong() const; constexpr unsigned long long to_ullong() const; template<class charT = char, class traits = char_traits<charT>, class Allocator = allocator<charT>> constexpr basic_string<charT, traits, Allocator> to_string(charT zero = charT('0'), charT one = charT('1')) const; // observers constexpr size_t count() const noexcept; constexpr size_t size() const noexcept; constexpr bool operator==(const bitset& rhs) const noexcept; constexpr bool test(size_t pos) const; constexpr bool all() const noexcept; constexpr bool any() const noexcept; constexpr bool none() const noexcept; }; // [bitset.hash], hash support template<class T> struct hash; template<size_t N> struct hash<bitset<N>>; }
1
#
The class template bitset<N> describes an object that can store a sequence consisting of a fixed number of bits, N.
2
#
Each bit represents either the value zero (reset) or one (set).
To toggle a bit is to change the value zero to one, or the value one to zero.
Each bit has a non-negative position pos.
When converting between an object of class bitset<N> and a value of some integral type, bit position pos corresponds to the bit value 1 << pos.
The integral value corresponding to two or more bits is the sum of their bit values.
3
#
The functions described in [template.bitset] can report three kinds of errors, each associated with a distinct exception:

22.9.2.2 Constructors [bitset.cons]

🔗
constexpr bitset() noexcept;
1
#
Effects: Initializes all bits in *this to zero.
🔗
constexpr bitset(unsigned long long val) noexcept;
2
#
Effects: Initializes the first M bit positions to the corresponding bit values in val.
M is the smaller of N and the number of bits in the value representation ([basic.types.general]) of unsigned long long.
If M < N, the remaining bit positions are initialized to zero.
🔗
template<class charT, class traits, class Allocator> constexpr explicit bitset( const basic_string<charT, traits, Allocator>& str, typename basic_string<charT, traits, Allocator>::size_type pos = 0, typename basic_string<charT, traits, Allocator>::size_type n = basic_string<charT, traits, Allocator>::npos, charT zero = charT('0'), charT one = charT('1'));
3
#
Effects: Determines the effective length rlen of the initializing string as the smaller of n and str.size() - pos.
Initializes the first M bit positions to values determined from the corresponding characters in the string str.
M is the smaller of N and rlen.
4
#
An element of the constructed object has value zero if the corresponding character in str, beginning at position pos, is zero.
Otherwise, the element has the value one.
Character position pos + M - 1 corresponds to bit position zero.
Subsequent decreasing character positions correspond to increasing bit positions.
5
#
If M < N, remaining bit positions are initialized to zero.
6
#
The function uses traits​::​eq to compare the character values.
7
#
Throws: out_of_range if pos > str.size() or invalid_argument if any of the rlen characters in str beginning at position pos is other than zero or one.
🔗
template<class charT> constexpr explicit bitset( const charT* str, typename basic_string<charT>::size_type n = basic_string<charT>::npos, charT zero = charT('0'), charT one = charT('1'));
8
#
Effects: As if by: bitset(n == basic_string<charT>::npos ? basic_string<charT>(str) : basic_string<charT>(str, n), 0, n, zero, one)

22.9.2.3 Members [bitset.members]

🔗
constexpr bitset& operator&=(const bitset& rhs) noexcept;
1
#
Effects: Clears each bit in *this for which the corresponding bit in rhs is clear, and leaves all other bits unchanged.
2
#
Returns: *this.
🔗
constexpr bitset& operator|=(const bitset& rhs) noexcept;
3
#
Effects: Sets each bit in *this for which the corresponding bit in rhs is set, and leaves all other bits unchanged.
4
#
Returns: *this.
🔗
constexpr bitset& operator^=(const bitset& rhs) noexcept;
5
#
Effects: Toggles each bit in *this for which the corresponding bit in rhs is set, and leaves all other bits unchanged.
6
#
Returns: *this.
🔗
constexpr bitset& operator<<=(size_t pos) noexcept;
7
#
Effects: Replaces each bit at position I in *this with a value determined as follows:
  • (7.1)
    If I < pos, the new value is zero;
  • (7.2)
    If I >= pos, the new value is the previous value of the bit at position I - pos.
8
#
Returns: *this.
🔗
constexpr bitset& operator>>=(size_t pos) noexcept;
9
#
Effects: Replaces each bit at position I in *this with a value determined as follows:
  • (9.1)
    If pos >= N - I, the new value is zero;
  • (9.2)
    If pos < N - I, the new value is the previous value of the bit at position I + pos.
10
#
Returns: *this.
🔗
constexpr bitset operator<<(size_t pos) const noexcept;
11
#
Returns: bitset(*this) <<= pos.
🔗
constexpr bitset operator>>(size_t pos) const noexcept;
12
#
Returns: bitset(*this) >>= pos.
🔗
constexpr bitset& set() noexcept;
13
#
Effects: Sets all bits in *this.
14
#
Returns: *this.
🔗
constexpr bitset& set(size_t pos, bool val = true);
15
#
Effects: Stores a new value in the bit at position pos in *this.
If val is true, the stored value is one, otherwise it is zero.
16
#
Returns: *this.
17
#
Throws: out_of_range if pos does not correspond to a valid bit position.
🔗
constexpr bitset& reset() noexcept;
18
#
Effects: Resets all bits in *this.
19
#
Returns: *this.
🔗
constexpr bitset& reset(size_t pos);
20
#
Effects: Resets the bit at position pos in *this.
21
#
Returns: *this.
22
#
Throws: out_of_range if pos does not correspond to a valid bit position.
🔗
constexpr bitset operator~() const noexcept;
23
#
Effects: Constructs an object x of class bitset and initializes it with *this.
24
#
Returns: x.flip().
🔗
constexpr bitset& flip() noexcept;
25
#
Effects: Toggles all bits in *this.
26
#
Returns: *this.
🔗
constexpr bitset& flip(size_t pos);
27
#
Effects: Toggles the bit at position pos in *this.
28
#
Returns: *this.
29
#
Throws: out_of_range if pos does not correspond to a valid bit position.
🔗
constexpr bool operator[](size_t pos) const;
30
#
Preconditions: pos is valid.
31
#
Returns: true if the bit at position pos in *this has the value one, otherwise false.
32
#
Throws: Nothing.
🔗
constexpr bitset::reference operator[](size_t pos);
33
#
Preconditions: pos is valid.
34
#
Returns: An object of type bitset​::​reference such that (*this)[pos] == this->test(pos), and such that (*this)[pos] = val is equivalent to this->set(pos, val).
35
#
Throws: Nothing.
36
#
Remarks: For the purpose of determining the presence of a data race ([intro.multithread]), any access or update through the resulting reference potentially accesses or modifies, respectively, the entire underlying bitset.
🔗
constexpr unsigned long to_ulong() const;
37
#
Returns: x.
38
#
Throws: overflow_error if the integral value x corresponding to the bits in *this cannot be represented as type unsigned long.
🔗
constexpr unsigned long long to_ullong() const;
39
#
Returns: x.
40
#
Throws: overflow_error if the integral value x corresponding to the bits in *this cannot be represented as type unsigned long long.
🔗
template<class charT = char, class traits = char_traits<charT>, class Allocator = allocator<charT>> constexpr basic_string<charT, traits, Allocator> to_string(charT zero = charT('0'), charT one = charT('1')) const;
41
#
Effects: Constructs a string object of the appropriate type and initializes it to a string of length N characters.
Each character is determined by the value of its corresponding bit position in *this.
Character position N - 1 corresponds to bit position zero.
Subsequent decreasing character positions correspond to increasing bit positions.
Bit value zero becomes the character zero, bit value one becomes the character one.
42
#
Returns: The created object.
🔗
constexpr size_t count() const noexcept;
43
#
Returns: A count of the number of bits set in *this.
🔗
constexpr size_t size() const noexcept;
44
#
Returns: N.
🔗
constexpr bool operator==(const bitset& rhs) const noexcept;
45
#
Returns: true if the value of each bit in *this equals the value of the corresponding bit in rhs.
🔗
constexpr bool test(size_t pos) const;
46
#
Returns: true if the bit at position pos in *this has the value one.
47
#
Throws: out_of_range if pos does not correspond to a valid bit position.
🔗
constexpr bool all() const noexcept;
48
#
Returns: count() == size().
🔗
constexpr bool any() const noexcept;
49
#
Returns: count() != 0.
🔗
constexpr bool none() const noexcept;
50
#
Returns: count() == 0.

22.9.3 bitset hash support [bitset.hash]

🔗
template<size_t N> struct hash<bitset<N>>;
1
#
The specialization is enabled ([unord.hash]).

22.9.4 bitset operators [bitset.operators]

🔗
template<size_t N> constexpr bitset<N> operator&(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
1
#
Returns: bitset<N>(lhs) &= rhs.
🔗
template<size_t N> constexpr bitset<N> operator|(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
2
#
Returns: bitset<N>(lhs) |= rhs.
🔗
template<size_t N> constexpr bitset<N> operator^(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
3
#
Returns: bitset<N>(lhs) ^= rhs.
🔗
template<class charT, class traits, size_t N> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, bitset<N>& x);
4
#
A formatted input function ([istream.formatted]).
5
#
Effects: Extracts up to N characters from is.
Stores these characters in a temporary object str of type basic_string<charT, traits>, then evaluates the expression x = bitset<N>(str).
Characters are extracted and stored until any of the following occurs:
  • (5.1)
    N characters have been extracted and stored;
  • (5.2)
    end-of-file occurs on the input sequence;
  • (5.3)
    the next input character is neither is.widen('0') nor is.widen('1') (in which case the input character is not extracted).
6
#
If N > 0 and no characters are stored in str, ios_base​::​failbit is set in the input function's local error state before setstate is called.
7
#
Returns: is.
🔗
template<class charT, class traits, size_t N> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const bitset<N>& x);
8
#
Returns: os << x.template to_string<charT, traits, allocator<charT>>( use_facet<ctype<charT>>(os.getloc()).widen('0'), use_facet<ctype<charT>>(os.getloc()).widen('1')) (see [ostream.formatted]).