Apache C++ Standard Library Reference Guide

## bitset

Library: Containers

    Does not inherit

- Local Index
- Summary
- Synopsis
- Description
- Errors and Exceptions
- Interface
- Constructors
- Assignment Operators
- Operators
- Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

any() bitset() count() flip() none() operator!=() | operator&() operator&=() operator>>() operator>>=() operator<<() operator<<=() | operator=() operator==() operator^() operator^=() operator|() operator|=() | operator~() reset() set() size() test() to_ulong()

### Summary

A class template and related functions for storing and manipulating fixed-size sequences of bits

### Synopsis

    #include <bitset>

    namespace std {
      template <size_t N>
      class bitset;
    }

### Description

bitset is a class that describes objects that can store a sequence consisting of a fixed number of bits,`N.` Each bit represents either the value zero (`reset`) or one (`set`) and has a non-negative position `pos`.

### Errors and Exceptions

Bitset constructors and member functions may throw the following exceptions:

- invalid_argument

- out_of_range

- overflow_error

If exceptions are not supported on your compiler, you get an assertion failure instead of an exception.

### Interface

    namespace std {

      template <size_t N>
      class bitset {

      public:

      // bit reference:

        class reference {
          friend class bitset;
          public:

          ~reference();
          reference& operator= (bool);
          reference& operator= (const reference&);
          bool operator~() const;
          operator bool() const;
          reference& flip();
        };

      // Constructors
        bitset ();
        bitset (unsigned long);
        template<class charT, class traits, class Allocator>
        explicit bitset
                 (const basic_string<charT, traits, Allocator>,
                  typename basic_string<charT, traits,
                                    Allocator>::size_type=0,
                  typename basic_string<charT, traits
                                    Allocator>::size_type=
                  basic_string<charT, traits, Allocator>::npos);
        bitset (const bitset<N>&);
        bitset<N>& operator= (const bitset<N>&);

      // Bitwise Operators and Bitwise Operator Assignment
         bitset<N>& operator&= (const bitset<N>&);
         bitset<N>& operator|= (const bitset<N>&);
         bitset<N>& operator^= (const bitset<N>&);
         bitset<N>& operator<<= (size_t);
         bitset<N>& operator>>= (size_t);

      // Set, Reset, Flip
         bitset<N>& set ();
         bitset<N>& set (size_t, int = true);
         bitset<N>& reset ();
         bitset<N>& reset (size_t);
         bitset<N> operator~() const;
         bitset<N>& flip ();
         bitset<N>& flip (size_t);

      // element access
         reference operator[] (size_t);
         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>&) const;
         bool operator!= (const bitset<N>&) const;
         bool test (size_t) const;
         bool any() const;
         bool none() const;
         bitset<N> operator<< (size_t) const;
         bitset<N> operator>> (size_t) const;

      };

      // Nonmember operators
      template <size_t N>
      bitset<N> operator& (const bitset<N>&, const bitset<N>&);

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

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

      template <size_t N>
      basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>&,
                 bitset<N>&);

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

### Constructors

    bitset();

Constructs an object of class `bitset<N>`, initializing all bit values to zero.

    bitset(unsigned long val);

Constructs an object of class bitset, initializing the first `M` bit values to the corresponding bits in `val`. `M` is the smaller of `N` and the value `CHAR_BIT * sizeof(unsigned long)`. If `M < N`, remaining bit positions are initialized to zero. Note: `CHAR_BIT` is defined in `<climits>`.

    template<class charT, class traits, class Allocator>
    explicit
    bitset (const basic_string<charT, traits, Allocator>,
            typename basic_string<charT, traits,
                                  Allocator>::size_type=0,
            typename basic_string<charT, traits,
                                  Allocator>::size_type=
            basic_string<charT, traits, Allocator>::npos);

Determines the effective length `rlen` of the initializing string as the smaller of `n` and `str.size() - pos`. The function throws an invalid_argument exception if any of the `rlen` characters in `str`, beginning at position `pos`, is other than `0` or `1`. Otherwise, the function constructs an object of class bitset, 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`. This constructor expects `pos <= str.size()`. If that is not `true`, the constructor throws an out_of_range exception.

    bitset(const bitset<N>& rhs);

Creates a copy of `rhs`.

### Assignment Operators

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

Erases all bits in self, then inserts into self a copy of each bit in `rhs`. Returns a reference to `*this`.

### Operators

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

Returns `true` if the value of each bit in `*this` equals the value of each corresponding bit in `rhs`. Otherwise returns `false`.

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

Returns `true` if the value of any bit in `*this` is not equal to the value of the corresponding bit in `rhs`. Otherwise returns `false`.

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

Clears each bit in `*this` for which the corresponding bit in `rhs` is clear and leaves all other bits unchanged. Returns `*this`.

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

Sets each bit in `*this` for which the corresponding bit in `rhs` is set, and leaves all other bits unchanged. Returns `*this`.

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

Toggles each bit in `*this` for which the corresponding bit in `rhs` is set, and leaves all other bits unchanged. Returns `*this`.

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

Replaces each bit at position `I` with `0` if `I < pos` or with the value of the bit at`I - pos` if `I >= pos`. Returns `*this`.

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

Replaces each bit at position `I` with `0` if `pos >= N-I` or with the value of the bit at position `I + pos` if `pos < N-I`. Returns `*this`.

    bitset<N>&
    operator>>(size_t pos) const;

Returns `bitset<N>(*this) >>= pos`.

    bitset<N>&
    operator<<(size_t pos) const;

Returns `bitset<N>(*this) <<= pos`.

    bitset<N>
    operator~() const;

Returns the bitset that is the logical complement of each bit in `*this`.

    bitset<N>
    operator&(const bitset<N>& lhs,
              const bitset<N>& rhs);

`lhs` gets logical `AND` of `lhs` with `rhs`.

    bitset<N>
    operator|(const bitset<N>& lhs,
              const bitset<N>& rhs);

`lhs` gets logical `OR` of `lhs` with `rhs`.

    bitset<N>
    operator^(const bitset<N>& lhs,
              const bitset<N>& rhs);

`lhs` gets logical `XOR` of `lhs` with `rhs`.

    template <size_t N>
    basic_istream<charT, traits>m&
    operator>>(basic_istream<charT, traits>& is, bitset<N>& x);

Extracts up to `N` characters (single-byte) from `is`. Stores these characters in a temporary object `str` of type `string`, then evaluates the expression `x = bitset<N>(str)`. Characters are extracted and stored until any of the following occurs:

- `N` characters have been extracted and stored

- An end-of-file is reached on the input sequence

- The next character is neither '0' nor '1'. In this case, the character is not extracted

Returns `is`. If no characters are extracted and stored, calls `is.setstate(ios::failbit)` (which may throw ios_base::failure).

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

Returns `os << x.to_string()`.

### Member Functions

    bool
    any() const;

Returns `true` if any bit in `*this` is set. Otherwise returns `false`.

    size_t
    count() const;

Returns a count of the number of bits set in `*this`.

    bitset<N>&
    flip();

Flips all bits in `*this`, and returns `*this`.

    bitset<N>&
    flip(size_t pos);

Flips the bit at position `pos` in `*this` and returns `*this`. Throws an out_of_range exception if `pos` does not correspond to a valid bit position.

    bool
    none() const;

Returns `true` if no bit in `*this` is set. Otherwise returns `false`.

    bitset<N>&
    reset();

Resets all bits in `*this`, and returns `*this`.

    bitset<N>&
    reset(size_t pos);

Resets the bit at position `pos` in `*this`. Throws an out_of_range exception if `pos` does not correspond to a valid bit position.

    bitset<N>&
    set();

Sets all bits in `*this`, and returns `*this`.

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

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. Throws an out_of_range exception if `pos` does not correspond to a valid bit position.

    size_t
    size() const;

Returns the template parameter `N`.

    bool
    test(size_t pos) const;

Returns `true` if the bit at position `pos` is set. Throws an out_of_range exception if `pos` does not correspond to a valid bit position.

    template<class charT, class traits, class Allocator>
    basic_string<charT, traits, Allocator>
    to_string() const;

Returns an object of type `basic_string`, `N` characters long.

Each position in the new string is initialized with a character ('0' for zero and '1' for one) representing the value stored in the corresponding bit position of `*this`. Character position `N - 1` corresponds to bit position 0. Subsequent decreasing character positions correspond to increasing bit positions.

    unsigned long
    to_ulong() const;

Returns the integral value corresponding to the bits in `*this`. Throws an overflow_error if these bits cannot be represented as type `unsigned long`.

### Example

    //
    // bitset.cpp
    //

    #include <bitset>     // for bitset
    #include <iostream>   // for cout, endl

    int main ()
    {
        // Construct a bitset with 8 elements
        // all initioalized to 0.
        std::bitset<8> b;

        // Bitwise or bitset with 5.
        b |= 5;

        // Write bitset to cout.
        std::cout << b << std::endl;

        return 0;
    }

    Program Output:

00000101

### See Also

Containers

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 23.3.5