Draft 2002-02-21

<bitset>

The <bitset> header declares a single class template, bitset, and some related functions.

bitset class template

Syntax

template<size_t N>
class bitset {
public:
  // 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<class charT, class traits, class Alloc>
  explicit bitset(const basic_string<charT,traits,Alloc>& s,
   typename basic_string<charT,traits,Alloc>::size_type p=0,
   typename basic_string<charT,traits,Alloc>::size_type n =
     basic_string<charT,traits,Allocator>::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 <class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator> 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;
};

Description

The bitset class template is a convenient class for manipulating a fixed-sized sequence of bits. Each bit 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 container, and does not support iterator or generic algorithms. For a container that holds a sequence of bits, use vector<int>. (See <vector>, later in this chapter, to learn more, including why you should not use vector<bool>).

bitset()
Resets all bits.
bitset(unsigned long value)
Initializes the first m bits to value, where m == CHAR_BITS * sizeof(unsigned long). If N > m, all other bits are reset to zero.
bitset(str, pos, n)
Initializes the bitset from the character string str, starting at character pos, 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; any other character sets a bit. Bits left uninitialized by the string are reset.
bitset<N>& operator &=(const bitset<N>& rhs)
Performs *this & rhs. Returns *this.
bitset<N>& operator |=(const bitset<N>& rhs)
Performs *this | rhs. Returns *this.
bitset<N>& operator ^=(const bitset<N>& rhs)
Performs *this ^ rhs. Returns *this.
bitset<N>& operator <<=(size_t pos)
Shifts bits to the left by pos positions. Vacated bits are filled with zero. Returns *this.
bitset<N>& operator >>=(size_t pos)
Shifts bits to the right by pos positions. Vacated bits are filled with zero. 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 from 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 zero.
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 zero. Returns *this.
bitset<N> operator ~() const
Return a new bitset with all bits flipped.
reference operator[](size_t pos)
Returns a reference object for the bit at position pos. The standard is silent on whether this operator throws out_of_range if pos is invalid, so be careful.
bool operator[](size_t pos) const
Returns the value of the bit at position pos. This member function is not in the standard, but might be added in a future revision. (Defect Report 11)
bool any() const
Returns true if any bit is set. Returns false is all bits are zero.
size_t count() const
Returns the number of bits set.
bitset<N>& flip()
Toggle all bits, that is, set 0 bits to 1 and 1 bits to 0. Returns *this.
bitset<N>& flip(size_t pos)
Toggle the bit at position pos. Returns *this.
bool none() const
Returns true if all bits are zero. Returns false if any bit is set.
bitset<N>& reset()
Reset all bits. Returns *this.
bitset<N>& reset(size_t pos)
Reset the bit at position pos. If pos is invalid, throws out_of_range. Returns *this.
bitset<N>& set()
Set 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.
The next version of the standard is likely to change the type of val to bool. (Defect Report 186)
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 is if pos is invalid.
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 zero is the rightmost character (position N - 1).
The compiler cannot deduce the template parameters when calling to_string, so you must specify them explicitly, as shown in the following example.
std::bitset<64> bits(std::string("101000111101010101"));
std::string =
  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, throws overflow_error.

See Also

<climits>, vector class template

operator &

Syntax

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

Description

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

See Also

<cstddef>, bitset class template, operator & (global), operator | (bitset), operator ^ (bitset)

operator |

Syntax

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

Description

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

See Also

<cstddef>, bitset class template, operator & (global), operator | (bitset), operator ^ (bitset)

operator ^

Syntax

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

Description

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

See Also

<cstddef>, bitset class template, operator & (global), operator | (bitset), operator ^ (bitset)

operator >>

Syntax

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

Description

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

basic_istream class template, <cstddef>, bitset class template, operator << (bitset)

operator <<

Syntax

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

Description

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

See Also

basic_ostream class template, <cstddef>, bitset class template, operator >> (bitset)

bitset::reference class

Syntax

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

Description

The bitset::reference class holds a reference toa single bit in a bitset. The constructor is private, so instances can be created only by the bitset class, in particular, by its operator[] function.

reference& operator=(bool x)
reference& operator=(const reference&)
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