.\" ident @(#)bitset.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH bitset 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2bitset\fP \ - A template class and related functions for storing and manipulating fixed-size sequences of bits. .SH SYNOPSIS .br #include .br template .br class bitset ; .SH DESCRIPTION bitset is a class that describes objects that can store a sequence consisting of a fixed number of bits,\f2 N.\fP Each bit represents either the value zero (\f2reset\fP) or one (\f2set\fP) and has a non-negative position \f2pos\fP. .SH ERRORS AND EXCEPTIONS Bitset constructors and member functions may report the following three types of errors - each associated with a distinct exception: .HP .5i \(bu Invalid-argument error or \f2invalid_argument()\fP exception; .HP .5i \(bu Out-of-range error or \f2out_of_range()\fP exception; .HP .5i \(bu Overflow error or \f2over-flow_error()\fP exception; .HP 0 If exceptions are not supported on your compiler, you get an assertion failure instead of an exception. .SH INTERFACE .br template .br class bitset { .br .br public: .br .br // bit reference: .br .RE .RS 1 class reference { .RE .RS 2 friend class bitset; .RE .RS 1 public: .RE .RS 0 .RE .RS 3 ~reference(); .RE .RS 2 reference& operator= (bool); .br reference& operator= (const reference&); .br bool operator~() const; .br operator bool() const; .br reference& flip(); .br }; .RE .RS 0 .br .br // Constructors .RE .RS 1 bitset (); .br bitset (unsigned long); .br template .br explicit bitset .RE .RS 11 (const basic_string, .br typename basic_string::size_type=0, .RE .RS 11 typename basic_string::size_type= .RE .RS 11 basic_string::npos); .RE .RS 1 bitset (const bitset&); .br bitset& operator= (const bitset&); .RE .RS 0 .br // Bitwise Operators and Bitwise Operator Assignment .RE .RS 2 bitset& operator&= (const bitset&); .br bitset& operator|= (const bitset&); .br bitset& operator^= (const bitset&); .br bitset& operator<<= (size_t); .br bitset& operator>>= (size_t); .RE .RS 0 .br // Set, Reset, Flip .RE .RS 2 bitset& set (); .br bitset& set (size_t, int = 1); .br bitset& reset (); .br bitset& reset (size_t); .br bitset operator~() const; .br bitset& flip (); .br bitset& flip (size_t); .RE .RS 0 .br // element access .RE .RS 2 reference operator[] (size_t); .br unsigned long to_ulong() const; .br template .br basic_string to_string(); .br size_t count() const; .br size_t size() const; .br bool operator== (const bitset&) const; .br bool operator!= (const bitset&) const; .br bool test (size_t) const; .br bool any() const; .br bool none() const; .br bitset operator<< (size_t) const; .br bitset operator>> (size_t) const; .RE .RS 0 .br }; .br .br // Non-member operators .br template .br bitset operator& (const bitset&, const bitset&); .br .br template .br bitset operator| (const bitset&, const bitset&); .br .br template .br bitset operator^ (const bitset&, const bitset&); .br .br template .br istream& operator>> (istream&, bitset&); .br .br template .br ostream& operator<< (ostream&, const bitset&) .SH CONSTRUCTORS .br bitset(); .RE .RS 3 Constructs an object of class \f2bitset\fP, initializing all bit values to zero. .RE .br bitset(unsigned long val); .RE .RS 3 Constructs an object of class \f2bitset\fP, initializing the first \f2M\fP bit values to the corresponding bits in \f2val\fP. \f2M\fP is the smaller of \f2N\fP and the value \f2CHAR_BIT * sizeof(unsigned long)\fP. If \f2M < N\fP, remaining bit positions are initialized to zero. Note: \f2CHAR_BIT\fP is defined in \f2\fP. .br template .RE .br explicit .br bitset (const basic_string, .RE .RS 7 typename basic_string::size_type=0, .RE .RS 7 typename basic_string::size_type= .RE .RS 7 basic_string::npos); .RE .RS 3 Determines the effective length \f2rlen\fP of the initializing string as the smaller of \f2n\fP and \f2str.size() - pos\fP. The function throws an \f2invalid_argument\fP exception if any of the \f2rlen\fP characters in \f2str\fP, beginning at position \f2pos\fP, is other than \f20\fP or \f21\fP. Otherwise, the function constructs an object of class bitset, initializing the first \f2M\fP bit positions to values determined from the corresponding characters in the string \f2str\fP. \f2M\fP is the smaller of \f2N\fP and \f2rlen\fP. This constructor expects \f2pos <= str.size()\fP. If that is not \f2true\fP, the constructor throws an \f2out_of_range\fP exception. .RE .RE .RS 0 bitset(const bitset& rhs); .RE .RS 3 Creates a copy of \f2rhs\fP. .RE .SH ASSIGNMENT OPERATORS .br bitset& .br operator=(const bitset& rhs); .RE .RS 3 Erases all bits in self, then inserts into self a copy of each bit in \f2rhs\fP. Returns a reference to \f2*this\fP. .RE .SH OPERATORS .br bool .br operator==(const bitset& rhs) const; .RE .RS 3 Returns \f2true\fP if the value of each bit in \f2*this\fP equals the value of each corresponding bit in \f2rhs\fP. Otherwise returns \f2false\fP. .RE .br bool .br operator!=(const bitset& rhs) const; .RE .RS 3 Returns \f2true\fP if the value of any bit in \f2*this\fP is not equal to the value of the corresponding bit in \f2rhs\fP. Otherwise returns \f2false\fP. .RE .br bitset& .br operator&=(const bitset& rhs); .RE .RS 3 Clears each bit in \f2*this\fP for which the corresponding bit in \f2rhs\fP is clear and leaves all other bits unchanged. Returns \f2*this\fP. .RE .br bitset& .br operator|=(const bitset& rhs); .RE .RS 3 Sets each bit in \f2*this\fP for which the corresponding bit in \f2rhs\fP is set, and leaves all other bits unchanged. Returns \f2*this\fP. .RE .br bitset& .br operator^=(const bitset& rhs); .RE .RS 3 Toggles each bit in \f2*this\fP for which the corresponding bit in \f2rhs\fP is set, and leaves all other bits unchanged. Returns \f2*this\fP. .RE .br bitset& .br operator<<=(size_t pos); .RE .RS 3 Replaces each bit at position \f2I\fP with \f20\fP if \f2I < pos\fP or with the value of the bit at\f2 I - pos\fP if \f2I >= pos\fP. Returns \f2*this\fP. .RE .br bitset& .br operator>>=(size_t pos); .RE .RS 3 Replaces each bit at position \f2I\fP with \f20\fP if \f2pos >= N-I\fP or with the value of the bit at position \f2I + pos\fP if \f2pos < N-I\fP. Returns \f2*this\fP. .RE .br bitset& .br operator>>(size_t pos) const; .RE .RS 3 Returns \f2bitset(*this) >>= pos\fP. .RE .br bitset& .br operator<<(size_t pos) const; .RE .RS 3 Returns \f2bitset(*this) <<= pos\fP. .RE .br bitset .br operator~() const; .RE .RS 3 Returns the bitset that is the logical complement of each bit in \f2*this\fP. .RE .br bitset .br operator&(const bitset& lhs, .RE .RS 9 const bitset& rhs); .RE .RS 3 \f2lhs\fP gets logical \f2AND\fP of \f2lhs\fP with \f2rhs\fP. .RE .RE .RS 0 bitset .br operator|(const bitset& lhs, .RE .RS 9 const bitset& rhs); .RE .RS 3 \f2lhs\fP gets logical \f2OR\fP of \f2lhs\fP with \f2rhs\fP. .RE .RE .RS 0 bitset .br operator^(const bitset& lhs, .RE .RS 9 const bitset& rhs); .RE .RS 3 \f2lhs\fP gets logical \f2XOR\fP of \f2lhs\fP with \f2rhs\fP. .RE .RE .RS 0 template .br istream& .br operator>>(istream& is, bitset& x); .RE .RS 3 Extracts up to \f2N\fP characters (single-byte) from \f2is\fP. Stores these characters in a temporary object \f2str\fP of type \f2string\fP, then evaluates the expression \f2x = bitset(str)\fP. Characters are extracted and stored until any of the following occurs: .RS .5i .HP .5i - \f2N\fP characters have been extracted and stored .HP .5i - An end-of-file is reached on the input sequence .HP .5i - The next character is neither '0' nor '1'. In this case, the character is not extracted .RE Returns \f2is\fP. .RE .br template .br ostream& .br operator<<(ostream& os, const bitset& x); .RE .RS 3 Returns \f2os << x.to_string()\fP .RE .SH MEMBER FUNCTIONS .br bool .br any() const; .RE .RS 3 Returns \f2true\fP if any bit in \f2*this\fP is set. Otherwise returns \f2false\fP. .RE .br size_t .br count() const; .RE .RS 3 Returns a count of the number of bits set in \f2*this\fP. .RE .br bitset& .br flip(); .RE .RS 3 Flips all bits in \f2*this\fP, and returns \f2*this\fP. .RE .br bitset& .br flip(size_t pos); .RE .RS 3 Flips the bit at position \f2pos\fP in \f2*this\fP and returns \f2*this\fP. Throws an \f2out_of_range\fP exception if \f2pos\fP does not correspond to a valid bit position. .RE .br bool .br none() const; .RE .RS 3 Returns \f2true\fP if no bit in \f2*this\fP is set. Otherwise returns \f2false\fP. .RE .br bitset& .br reset(); .RE .RS 3 Resets all bits in \f2*this\fP, and returns \f2*this\fP. .RE .br bitset& .br reset(size_t pos); .RE .RS 3 Resets the bit at position \f2pos\fP in \f2*this\fP. Throws an \f2out_of_range\fP exception if \f2pos\fP does not correspond to a valid bit position. .RE .br bitset& .br set(); .RE .RS 3 Sets all bits in \f2*this\fP, and returns \f2*this\fP. .RE .br bitset& .br set(size_t pos, int val = 1); .RE .RS 3 Stores a new value in the bits at position \f2pos\fP in \f2*this.\fP If \f2val\fP is nonzero, the stored value is one, otherwise it is zero. Throws an \f2out_of_range\fP exception if \f2pos\fP does not correspond to a valid bit position. .RE .br size_t .br size() const; .RE .RS 3 Returns the template parameter \f2N\fP. .RE .br bool .br test(size_t pos) const; .RE .RS 3 Returns \f2true\fP if the bit at position \f2pos\fP is set. Throws an \f2out_of_range\fP exception if \f2pos\fP does not correspond to a valid bit position. .br template .br basic_string .br to_string(); Returns an object of type \f2string\fP, \f2N\fP 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 \f2*this\fP. Character position \f2N - 1\fP corresponds to bit position 0. Subsequent decreasing character positions correspond to increasing bit positions. .RE .br unsigned long .br to_ulong() const; .RE .RS 3 Returns the integral value corresponding to the bits in \f2*this\fP. Throws an \f2overflow_error\fP if these bits cannot be represented as type \f2unsigned long\fP. .RE .SH SEE ALSO Containers