23 General utilities library [utilities]

23.9 Bitsets [bitset]

23.9.1 Header <bitset> synopsis [bitset.syn]

#include <string>
#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>
    bitset<N> operator&(const bitset<N>&, const bitset<N>&) noexcept;
  template <size_t N>
    bitset<N> operator|(const bitset<N>&, const bitset<N>&) noexcept;
  template <size_t N>
    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);
}
1
#
The header <bitset> defines a class template and several related functions for representing and manipulating fixed-size sequences of bits.

23.9.2 Class template bitset [template.bitset]

namespace std {
  template<size_t N> class bitset {
  public:
    // bit reference:
    class reference {
      friend class bitset;
      reference() noexcept;
    public:
      ~reference() noexcept;
      reference& operator=(bool x) noexcept;             // for b[i] = x;
      reference& operator=(const reference&) noexcept;   // for b[i] = b[j];
      bool operator~() const noexcept;                   // flips the bit
      operator bool() const noexcept;                    // for x = b[i];
      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>
      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>
      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
    bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator|=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator^=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator<<=(size_t pos) noexcept;
    bitset<N>& operator>>=(size_t pos) noexcept;
    bitset<N>& set() noexcept;
    bitset<N>& set(size_t pos, bool val = true);
    bitset<N>& reset() noexcept;
    bitset<N>& reset(size_t pos);
    bitset<N>  operator~() const noexcept;
    bitset<N>& flip() noexcept;
    bitset<N>& flip(size_t pos);

    // element access:
    constexpr bool operator[](size_t pos) const;       // for b[i];
    reference operator[](size_t pos);                  // for b[i];

    unsigned long to_ulong() const;
    unsigned long long to_ullong() const;
    template <class charT = char,
              class traits = char_traits<charT>,
              class Allocator = allocator<charT>>
      basic_string<charT, traits, Allocator>
        to_string(charT zero = charT('0'), charT one = charT('1')) const;

    size_t count() const noexcept;
    constexpr size_t size() const noexcept;
    bool operator==(const bitset<N>& rhs) const noexcept;
    bool operator!=(const bitset<N>& rhs) const noexcept;
    bool test(size_t pos) const;
    bool all() const noexcept;
    bool any() const noexcept;
    bool none() const noexcept;
    bitset<N> operator<<(size_t pos) const noexcept;
    bitset<N> operator>>(size_t pos) 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 this subclause can report three kinds of errors, each associated with a distinct exception:

23.9.2.1 bitset constructors [bitset.cons]

constexpr bitset() noexcept;
1
#
Effects: Constructs an object of class bitset<N>, initializing all bits to zero.
constexpr bitset(unsigned long long val) noexcept;
2
#
Effects: Constructs an object of class bitset<N>, initializing 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]) of unsigned long long.
If M < N, the remaining bit positions are initialized to zero.
template <class charT, class traits, class Allocator> 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
#
Throws: out_­of_­range if pos > str.size() or invalid_­argument if an invalid character is found (see below).
4
#
Effects: Determines the effective length rlen of the initializing string as the smaller of n and str.size() - pos.
The function then throws invalid_­argument if any of the rlen characters in str beginning at position pos is other than zero or one.
The function uses traits​::​eq() to compare the character values.
Otherwise, the function constructs an object of class bitset<N>, initializing the first M bit positions to values determined from the corresponding characters in the string str.
M is the smaller of N and rlen.
5
#
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.
6
#
If M < N, remaining bit positions are initialized to zero.
template <class charT> explicit bitset( const charT* str, typename basic_string<charT>::size_type n = basic_string<charT>::npos, charT zero = charT('0'), charT one = charT('1'));
7
#
Effects: Constructs an object of class bitset<N> as if by: 
bitset(
  n == basic_string<charT>::npos
    ? basic_string<charT>(str)
    : basic_string<charT>(str, n),
  0, n, zero, one)

23.9.2.2 bitset members [bitset.members]

bitset<N>& operator&=(const bitset<N>& 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.
bitset<N>& operator|=(const bitset<N>& 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.
bitset<N>& operator^=(const bitset<N>& 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.
bitset<N>& 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.
bitset<N>& 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.
bitset<N>& set() noexcept;
11
#
Effects: Sets all bits in *this.
12
#
Returns: *this.
bitset<N>& set(size_t pos, bool val = true);
13
#
Throws: out_­of_­range if pos does not correspond to a valid bit position.
14
#
Effects: Stores a new value in the bit at position pos in *this.
If val is nonzero, the stored value is one, otherwise it is zero.
15
#
Returns: *this.
bitset<N>& reset() noexcept;
16
#
Effects: Resets all bits in *this.
17
#
Returns: *this.
bitset<N>& reset(size_t pos);
18
#
Throws: out_­of_­range if pos does not correspond to a valid bit position.
19
#
Effects: Resets the bit at position pos in *this.
20
#
Returns: *this.
bitset<N> operator~() const noexcept;
21
#
Effects: Constructs an object x of class bitset<N> and initializes it with *this.
22
#
Returns: x.flip().
bitset<N>& flip() noexcept;
23
#
Effects: Toggles all bits in *this.
24
#
Returns: *this.
bitset<N>& flip(size_t pos);
25
#
Throws: out_­of_­range if pos does not correspond to a valid bit position.
26
#
Effects: Toggles the bit at position pos in *this.
27
#
Returns: *this.
unsigned long to_ulong() const;
28
#
Throws: overflow_­error if the integral value x corresponding to the bits in *this cannot be represented as type unsigned long.
29
#
Returns: x.
unsigned long long to_ullong() const;
30
#
Throws: overflow_­error if the integral value x corresponding to the bits in *this cannot be represented as type unsigned long long.
31
#
Returns: x.
template <class charT = char, class traits = char_traits<charT>, class Allocator = allocator<charT>> basic_string<charT, traits, Allocator> to_string(charT zero = charT('0'), charT one = charT('1')) const;
32
#
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.
33
#
Returns: The created object.
size_t count() const noexcept;
34
#
Returns: A count of the number of bits set in *this.
constexpr size_t size() const noexcept;
35
#
Returns: N.
bool operator==(const bitset<N>& rhs) const noexcept;
36
#
Returns: true if the value of each bit in *this equals the value of the corresponding bit in rhs.
bool operator!=(const bitset<N>& rhs) const noexcept;
37
#
Returns: true if !(*this == rhs).
bool test(size_t pos) const;
38
#
Throws: out_­of_­range if pos does not correspond to a valid bit position.
39
#
Returns: true if the bit at position pos in *this has the value one.
bool all() const noexcept;
40
#
Returns: count() == size().
bool any() const noexcept;
41
#
Returns: count() != 0.
bool none() const noexcept;
42
#
Returns: count() == 0.
bitset<N> operator<<(size_t pos) const noexcept;
43
#
Returns: bitset<N>(*this) <<= pos.
bitset<N> operator>>(size_t pos) const noexcept;
44
#
Returns: bitset<N>(*this) >>= pos.
constexpr bool operator[](size_t pos) const;
45
#
Requires: pos shall be valid.
46
#
Returns: true if the bit at position pos in *this has the value one, otherwise false.
47
#
Throws: Nothing.
bitset<N>::reference operator[](size_t pos);
48
#
Requires: pos shall be valid.
49
#
Returns: An object of type bitset<N>​::​reference such that (*this)[pos] == this->test(pos), and such that (*this)[pos] = val is equivalent to this->set(pos, val).
50
#
Throws: Nothing.
51
#
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.

23.9.3 bitset hash support [bitset.hash]

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

23.9.4 bitset operators [bitset.operators]

bitset<N> operator&(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
1
#
Returns: bitset<N>(lhs) &= rhs.
bitset<N> operator|(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
2
#
Returns: bitset<N>(lhs) |= rhs.
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 no characters are stored in str, calls is.setstate(ios_­base​::​failbit) (which may throw ios_­base​::​failure ([iostate.flags])).
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]).