13.2 <bitset>

The <bitset> header declares a single class template, bitset, and some related functions. A bitset is a fixed-size sequence of bits. The bitwise operators (&, |, ^, etc.) are overloaded to work with bitsets in the usual manner, and you can refer to individual bits by index.

The Boost project has a class template for a bit sequence that can change size at runtime. See Appendix B for information about Boost.

template<size_t N>
class bitset {
public:
  // Proxy class to simulate a bit reference
  class reference {
    friend class bitset;
    reference(  );
  public:
    ~reference(  );
    reference& operator=(bool x);
    reference& operator=(const reference&);
    bool operator~(  ) const;
    operator bool(  ) const;
    reference& flip(  );
  };

  // Constructors 
  bitset(  ); 
  bitset(unsigned long val);

  template<typename charT, typename traits, typename A>
  explicit bitset(const basic_string<charT,traits,A>& s, typename 
    basic_string<charT,traits,A>::size_type p=0, typename basic
    string<charT,traits,A>::size_type n = basic_string<charT,traits,A>::npos);

  // bitset operations
  bitset<N>& operator&=(const bitset<N>& rhs);
  bitset<N>& operator|=(const bitset<N>& rhs);
  bitset<N>& operator^=(const bitset<N>& rhs);
  bitset<N>& operator<<=(size_t pos);
  bitset<N>& operator>>=(size_t pos);
  bitset<N>& set(  );
  bitset<N>& set(size_t pos, int val=true);
  bitset<N>& reset(  );
  bitset<N>& reset(size_t pos);
  bitset<N>  operator~(  ) const;
  bitset<N>& flip(  );
  bitset<N>& flip(size_t pos);
  
  // Element access
  reference operator[](size_t pos);
  bool operator[](size_t pos) const;
  
  unsigned long  to_ulong(  ) const;
  template <typename charT, typename traits, typename Alloc>
    basic_string<charT, traits, Alloc> to_string(  ) const;
  
  size_t count(  ) const;
  size_t size(  )  const; 
  bool operator==(const bitset<N>& rhs) const;
  bool operator!=(const bitset<N>& rhs) const;
  bool test(size_t pos) const;
  bool any(  ) const;
  bool none(  ) const;
  bitset<N> operator<<(size_t pos) const;
  bitset<N> operator>>(size_t pos) const
};

The bitset class template offers a convenient way to manipulate a fixed-sized sequence of bits. The number of bits is specified as a template argument, so each bitset object can have a different size. Each bit in a bitset can be set (1 or true) or reset (0 or false). Bit positions are numbered from right to left, that is, 0 is the least-significant bit, and N - 1 is the most-significant bit.

A bitset is not a standard container and does not provide iterators or support generic algorithms. For a container that holds a sequence of bit values, use vector<int> or deque<bool>. (See <vector> later in this chapter to learn more, including why you should not use vector<bool>.) In the following member function descriptions, N is the template parameter (number of bits):

bitset( )

Resets all bits.

bitset(unsigned long value)

Initializes the first m bits to value, in which m == CHAR_BITS * sizeof(unsigned long). If N > m, all other bits are reset to 0. If N < m, excess bits of m are ignored.

template<typename charT, typename traits, typename A>
explicit bitset(const basic_string<charT,traits,A>& s, 
    typename basic_string<charT,traits,A>::size_type p=0, 
    typename basic_string<charT,traits,A>::size_type n= 
    basic_string<charT,traits,A>::npos)

Initializes the bitset from the character string s, starting at index p and extending for n characters (or to the end of the string, whichever comes first). The default is to use all characters in the string. A character equal to '0' resets a bit, '1' sets a bit, and any other character causes the constructor to throw invalid_argument.

The rightmost character of the substring (that is, the character s[p+n-1] or the rightmost character of s) initializes the bit at index 0 of the bitset, and subsequent bits are initialized by characters at preceding indices of s. Bits left uninitialized by the string are reset. All of the bitsets in the following example are equal to 000111:

bitset<6> a(string("111"));
bitset<6> b(string("000111"));
bitset<6> c(string("10110011100"), 5, 4);
bitset<6> d(string("111111"), 3, 42);

The unwieldy declaration is due to the basic_string class template. For the common case of a plain string, you can read the declaration as:

bitset(const string& s, size_t p=0, size_n n=string::npos)

bitset<N>& operator&=(const bitset<N>& rhs)

Performs *this = *this & rhs. Returns *this.

bitset<N>& operator|=(const bitset<N>& rhs)

Performs *this = *this | rhs. Returns *this.

bitset<N>& operator^=(const bitset<N>& rhs)

Performs *this = *this ^ rhs. Returns *this.

bitset<N>& operator<<=(size_t pos)

Shifts bits to the left by pos positions. Vacated bits are filled with 0. Returns *this.

bitset<N>& operator>>=(size_t pos)

Shifts bits to the right by pos positions. Vacated bits are filled with 0. Returns *this.

bool operator==(const bitset<N> rhs)

Returns true if every bit in *this has the same value as the corresponding bit in rhs.

bool operator!=(const bitset<N> rhs)

Returns true if any bit in *this has a different value than the corresponding bit in rhs.

bitset<N> operator<<(size_t pos)

Returns a new bitset with its bits shifted to the left by pos positions. Vacated bits are filled with 0.

bitset<N> operator>>(size_t pos)

Returns a new bitset with its bits shifted to the right by pos positions. Vacated bits are filled with 0.

bitset<N> operator~( ) const

Returns a new bitset with all bits flipped.

reference operator[](size_t pos)

Returns a bitset::reference object for the bit at position pos. The behavior is undefined if pos is out of range.

bool operator[](size_t pos) const

Returns the value of the bit at position pos. The behavior is undefined if pos is out of range. This member function was added to the standard as part of the technical corrigendum (TC1), so it might not yet be supported by some compilers.

bool any( ) const

Returns true if any bit is set. Returns false if all bits are 0.

size_t count( ) const

Returns the number of bits set.

bitset<N>& flip( )

Toggles all bits, that is, sets 0 bits to 1 and 1 bits to 0. Returns *this.

bitset<N>& flip(size_t pos)

Toggles the bit at position pos. If pos is invalid, throws out_of_range. Returns *this.

bool none( ) const

Returns true if all bits are 0. Returns false if any bit is set.

bitset<N>& reset( )

Resets all bits. Returns *this.

bitset<N>& reset(size_t pos)

Resets the bit at position pos. If pos is invalid, throws out_of_range. Returns *this.

bitset<N>& set( )

Sets all bits. Returns *this.

bitset<N>& set(size_t pos, int val = true)

Sets the bit at position pos to val != 0. If pos is invalid, throws out_of_range. Returns *this.

size_t size( ) const

Returns N.

bool test(size_t pos) const

Returns the value of the bit at position pos. Throws out_of_range if pos is invalid.

template <class charT, class traits, class Allocator>

basic_string<charT, traits, Allocator>

to_string( ) const

Returns a string representation of the bitset. Each bit is converted to the character '0' if reset or '1' if set. Bit position 0 is the rightmost character (position N - 1).

The compiler cannot deduce the template parameters when calling to_string, so you must specify them explicitly:

std::bitset<64> bits(std::string("101000111101010101"));
std::string str = bits.template to_string<char, std::char_traits<char>,
                                          std::allocator<char> >(  ));

unsigned long to_ulong( ) const

Returns the integral value of the bitset. If N is too large for unsigned long, it throws overflow_error.

See Also

<climits>, <vector>

class reference {
  friend class bitset;
  reference(  )
public:
  ~reference(  );
  reference& operator=(bool x);
  reference& operator=(const reference&);
  bool operator~(  ) const;
  operator bool(  ) const;
  reference& flip(  );
};

The bitset::reference class is a proxy that refers to a single bit in a bitset. The constructor is private, so instances can be created only by the bitset class, particularly by its operator[] function. The member functions are:

reference& operator=(bool x)

reference& operator=(const reference& x)

Sets the referenced bit to x in the underlying bitset. Returns *this.

bool operator~( ) const

Returns the logical negation of the referenced bit.

operator bool( ) const

Returns the value of the referenced bit.

reference& flip( )

Toggles the referenced bit in the underlying bitset. Returns *this.

See Also

bitset class template

template <size_t N>
  bitset<N> operator&(const bitset<N>& a, const bitset<N>& b);

The & operator takes two bitsets and returns a new bitset that represents the bitwise and of the operands. In other words, an output bit is set only when the corresponding bit is set in both operands; otherwise, an output bit is reset.

See Also

bitset class template, operator |, operator ^, <cstddef>, bit_and keyword

template <size_t N>
  bitset<N> operator|(const bitset<N>& a, const bitset<N>& b);

The | operator takes two bitsets and returns a new bitset that represents the bitwise inclusive or of the operands. In other words, an output bit is set when the corresponding bit is set in either operand, and an output bit is reset if the corresponding bits in both operands are 0.

See Also

bitset class template, operator &, operator ^, <cstddef>, bit_or keyword

template <size_t N>
  bitset<N> operator^(const bitset<N>& a, const bitset<N>& b);

The ^ operator takes two bitsets and returns a new bitset that represents the bitwise exclusive or of the operands. In other words, an output bit is set when the corresponding bits are not equal in either operand, and an output bit is reset if the corresponding bits in both operands are identical.

See Also

bitset class template, operator &, operator |, <cstddef>, xor keyword

template <typename charT, typename traits, size_t N>
  basic_istream<charT, traits)& operator>>(basic_istream<charT, traits)& 
                                           in, const bitset<N>& x);

The >> operator reads a bitset from an input stream. It extracts up to N characters and constructs a bitset object using the same format as the string constructor.

Only '0' and '1' characters are extracted. Input stops when it reaches any other character (without extracting that other character).

See Also

bitset class template, operator <<, <istream>, <cstddef>

template <typename charT, typename traits, size_t N>
  basic_ostream<charT, traits)& operator<<(basic_ostream<charT, traits)& in,
                                           const bitset<N>& x);

The << operator writes a bitset on an output stream, using the same format as the to_string member function.

See Also

bitset class template, operator >>, <cstddef>, <ostream>