From 16a25f7f10945c193e766308b708896fae06a941 Mon Sep 17 00:00:00 2001 From: Gennaro Prota Date: Sun, 18 Apr 2004 09:14:20 +0000 Subject: [PATCH] moved from the sandbox [SVN r22650] --- dynamic_bitset.html | 1797 ++++++++++++++++++++++++++----------------- 1 file changed, 1094 insertions(+), 703 deletions(-) diff --git a/dynamic_bitset.html b/dynamic_bitset.html index aadbb73..10d52f2 100644 --- a/dynamic_bitset.html +++ b/dynamic_bitset.html @@ -1,95 +1,137 @@ - - + + - -dynamic_bitset<Block, Allocator> - - + (C) Jeremy Siek 2001. + (C) Gennaro Prota 2003-2004. - c++boost.gif (8819 bytes) -

- -
-

dynamic_bitset<Block, Allocator>

+ Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) + --> + + + +dynamic_bitset<Block, Allocator> + + +c++boost.gif (8819 bytes) + +

+
+

+ + +TODO: + +
+Note: + Other things to do are marked by "[gps]" + + + +

dynamic_bitset<Block, Allocator>

Contents

+
-
Description
-
Synopsis
-
Definitions
-
Examples
-
Rationale
-
Header Files
-
Template Parameters
-
Concepts modeled
-
Type requirements
-
Public base classes
-
Member typedefs
-
Constructors
-
Destructor
-
Member functions
-
Non-member functions
-
See also
-
Acknowledgements
+
Description
+ +
Synopsis
+ +
Definitions
+ +
Examples
+ +
Rationale
+ +
Header Files
+ +
Template Parameters
+ +
Concepts modeled
+ +
Type requirements
+ +
Public base classes
+ +
Nested type names
+ +
Public data members
+ +
Constructors
+ +
Destructor
+ +
Member functions
+ +
Non-member functions
+ +
Exception guarantees
+ +
Changes from previous version(s)
+ +
See also
+ +
Acknowledgements

Description

-

-The dynamic_bitset class represents a set of bits. It provides -accesses to the value of individual bits via an operator[] -and provides all of the bitwise operators that one can apply to -builtin integers, such as operator& and -operator<<. The number of bits in the set is specified -at runtime via a parameter to the constructor of the -dynamic_bitset.

+

The dynamic_bitset class represents a set of bits. It +provides accesses to the value of individual bits via an +operator[] and provides all of the bitwise operators +that one can apply to builtin integers, such as +operator& and operator<<. The number +of bits in the set is specified at runtime via a parameter to the +constructor of the dynamic_bitset.

-

-The dynamic_bitset class is nearly identical to the std::bitset -class. The difference is that the size of the dynamic_bitset -(the number of bits) is specified at run-time during the construction -of a dynamic_bitset object, whereas the size of a -std::bitset is specified at compile-time through an integer -template parameter.

+

The dynamic_bitset class is nearly identical to the +std::bitset +class. The difference is that the size of the +dynamic_bitset (the number of bits) is specified at +run-time during the construction of a dynamic_bitset +object, whereas the size of a std::bitset is specified +at compile-time through an integer template parameter.

-

The main problem that dynamic_bitset is designed to solve is -that of representing a subset of a finite set. Each bit represents -whether an element of the finite set is in the subset or not. As such -the bitwise operations of dynamic_bitset, such as -operator& and operator|, correspond to set -operations, such as intersection and union.

+

The main problem that dynamic_bitset is designed to +solve is that of representing a subset of a finite set. Each bit +represents whether an element of the finite set is in the subset +or not. As such the bitwise operations of +dynamic_bitset, such as operator& and +operator|, correspond to set operations, such as +intersection and union.

Synopsis

@@ -101,67 +143,91 @@ class dynamic_bitset { public: typedef Block block_type; + typedef Allocator allocator_type; typedef implementation-defined size_type; - enum { bits_per_block = CHAR_BIT * sizeof(Block) }; + + static const int bits_per_block = implementation-defined; + static const size_type npos = implementation-defined; class reference { + void operator&(); // not defined public: // An automatically generated copy constructor. + reference& operator=(bool value); + reference& operator=(const reference& rhs); + reference& operator|=(bool value); reference& operator&=(bool value); reference& operator^=(bool value); reference& operator-=(bool value); - reference& operator=(const reference& j); - reference& operator|=(const reference& j); - reference& operator&=(const reference& j); - reference& operator^=(const reference& j); - reference& operator-=(const reference& j); + bool operator~() const; operator bool() const; reference& flip(); }; typedef bool const_reference; - explicit dynamic_bitset(const Allocator& alloc = Allocator()); + explicit dynamic_bitset(const Allocator& alloc = Allocator()); - explicit dynamic_bitset(size_type num_bits, unsigned long value = 0, + explicit dynamic_bitset(size_type num_bits, unsigned long value = 0, const Allocator& alloc = Allocator()); template <typename CharT, typename Traits, typename Alloc> - explicit dynamic_bitset(const std::basic_string<CharT, Traits, Alloc>& s, - typename std::basic_string<CharT, Traits, Alloc>::size_type pos = 0, + explicit dynamic_bitset(const std::basic_string<CharT, Traits, Alloc>& s, + typename std::basic_string<CharT, Traits, Alloc>::size_type pos = 0, typename std::basic_string<CharT, Traits, Alloc>::size_type n = std::basic_string<CharT, Traits, Alloc>::npos, const Allocator& alloc = Allocator()); template <typename BlockInputIterator> - dynamic_bitset(BlockInputIterator first, BlockInputIterator last, + dynamic_bitset(BlockInputIterator first, BlockInputIterator last, const Allocator& alloc = Allocator()); - dynamic_bitset(const dynamic_bitset& b); + dynamic_bitset(const dynamic_bitset& b); void swap(dynamic_bitset& b); - dynamic_bitset& operator=(const dynamic_bitset& b); + dynamic_bitset& operator=(const dynamic_bitset& b); - void resize(size_type num_bits, bool value = false); + allocator_type get_allocator() const; + + void resize(size_type num_bits, bool value = false); void clear(); void push_back(bool bit); void append(Block block); template <typename BlockInputIterator> - void append(BlockInputIterator first, BlockInputIterator last); + void append(BlockInputIterator first, BlockInputIterator last); - dynamic_bitset& operator&=(const dynamic_bitset& b); - dynamic_bitset& operator|=(const dynamic_bitset& b); - dynamic_bitset& operator^=(const dynamic_bitset& b); - dynamic_bitset& operator-=(const dynamic_bitset& b); - dynamic_bitset& operator<<=(size_type n); - dynamic_bitset& operator>>=(size_type n); - dynamic_bitset operator<<(size_type n) const; - dynamic_bitset operator>>(size_type n) const; + dynamic_bitset& operator&=(const dynamic_bitset& b); + dynamic_bitset& operator|=(const dynamic_bitset& b); + dynamic_bitset& operator^=(const dynamic_bitset& b); + dynamic_bitset& operator-=(const dynamic_bitset& b); + dynamic_bitset& operator<<=(size_type n); + dynamic_bitset& operator>>=(size_type n); + dynamic_bitset operator<<(size_type n) const; + dynamic_bitset operator>>(size_type n) const; - dynamic_bitset& set(size_type n, bool val = true); + dynamic_bitset& set(size_type n, bool val = true); dynamic_bitset& set(); dynamic_bitset& reset(size_type n); dynamic_bitset& reset(); @@ -173,95 +239,121 @@ public: dynamic_bitset operator~() const; size_type count() const; - reference operator[](size_type pos) { return reference(*this, pos); } - bool operator[](size_type pos) const { return test(pos); } + reference operator[](size_type pos); + bool operator[](size_type pos) const; unsigned long to_ulong() const; - + size_type size() const; size_type num_blocks() const; + size_type max_size() const; + bool empty() const; + + bool is_subset_of(const dynamic_bitset& a) const; + bool is_proper_subset_of(const dynamic_bitset& a) const; + + size_type find_first() const; + size_type find_next(size_type pos) const; + + - bool is_subset_of(const dynamic_bitset& a) const; - bool is_proper_subset_of(const dynamic_bitset& a) const; }; template <typename B, typename A> -bool operator==(const dynamic_bitset<B, A>& a, const dynamic_bitset<B, A>& b); +bool operator==(const dynamic_bitset<B, A>& a, const dynamic_bitset<B, A>& b); template <typename Block, typename Allocator> -bool operator!=(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); +bool operator!=(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); template <typename B, typename A> -bool operator<(const dynamic_bitset<B, A>& a, const dynamic_bitset<B, A>& b); +bool operator<(const dynamic_bitset<B, A>& a, const dynamic_bitset<B, A>& b); template <typename Block, typename Allocator> -bool operator<=(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); +bool operator<=(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); template <typename Block, typename Allocator> -bool operator>(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); +bool operator>(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); template <typename Block, typename Allocator> -bool operator>=(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); +bool operator>=(const dynamic_bitset<Block, Allocator>& a, const dynamic_bitset<Block, Allocator>& b); template <typename Block, typename Allocator> dynamic_bitset<Block, Allocator> -operator&(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); +operator&(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); template <typename Block, typename Allocator> dynamic_bitset<Block, Allocator> -operator|(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); +operator|(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); template <typename Block, typename Allocator> dynamic_bitset<Block, Allocator> -operator^(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); +operator^(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); template <typename Block, typename Allocator> dynamic_bitset<Block, Allocator> -operator-(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); +operator-(const dynamic_bitset<Block, Allocator>& b1, const dynamic_bitset<Block, Allocator>& b2); template <typename Block, typename Allocator, typename CharT, typename Alloc> -void to_string(const dynamic_bitset<Block, Allocator>& b, +void to_string(const dynamic_bitset<Block, Allocator>& b, std::basic_string<CharT, Alloc>& s); template <typename Block, typename Allocator, typename BlockOutputIterator> -void to_block_range(const dynamic_bitset<Block, Allocator>& b, +void to_block_range(const dynamic_bitset<Block, Allocator>& b, BlockOutputIterator result); template <typename CharT, typename Traits, typename Block, typename Allocator> std::basic_ostream<CharT, Traits>& -operator<<(std::basic_ostream<CharT, Traits>& os, const dynamic_bitset<Block, Allocator>& b); +operator<<(std::basic_ostream<CharT, Traits>& os, const dynamic_bitset<Block, Allocator>& b); template <typename CharT, typename Traits, typename Block, typename Allocator> std::basic_istream<CharT, Traits>& -operator>>(std::basic_istream<CharT, Traits>& is, dynamic_bitset<Block, Allocator>& b); +operator>>(std::basic_istream<CharT, Traits>& is, dynamic_bitset<Block, Allocator>& b); } // namespace boost

Definitions

-

-Each bit represents either the Boolean value true or false (1 or 0). -To set a bit is to assign it 1. To clear or reset -a bit is to assign it 0. To flip a bit is to change the value -to 1 if it was 0 and to 0 if it was 1. Each bit has a non-negative -position. A bitset x contains x.size() bits, -with each bit assigned a unique position in the range -[0,x.size()). The bit at position 0 is called the least -significant bit and the bit at position size() - 1 is the -most significant bit. When converting an instance of -dynamic_bitset to or from an unsigned long n, the bit at -position i of the bitset has the same value as (n >> i) -& 1. -

+ +

Each bit represents either the Boolean value true or false (1 +or 0). To set a bit is to assign it 1. To clear or +reset a bit is to assign it 0. To flip a bit is to +change the value to 1 if it was 0 and to 0 if it was 1. Each bit +has a non-negative position. A bitset x contains +x.size() bits, with each bit assigned a unique position +in the range [0,x.size()). The bit at position 0 is +called the least significant bit and the bit at position +size() - 1 is the most significant bit. When +converting an instance of dynamic_bitset to or from an +unsigned long n, the bit at position i of the +bitset has the same value as (n >> i) & 1.

Examples

An example of setting and reading some bits. Note that -operator[] goes from the least-significant bit at 0 -to the most significant bit at size()-1. The -operator<< for dynamic_bitset prints the bitset from -most-significant to least-significant, since that is the format most -people are use to reading.

+operator[] goes from the least-significant bit at +0 to the most significant bit at size()-1. The +operator<< for dynamic_bitset prints the +bitset from most-significant to least-significant, since that is +the format most people are use to reading.

+ 
 #include <iostream>
@@ -273,13 +365,15 @@ int main(int, char*[]) {
   x[4] = 1;
   for (boost::dynamic_bitset<>::size_type i = 0; i < x.size(); ++i)
     std::cout << x[i];
-  std::cout << "\n";
-  std::cout << x << "\n";
+  std::cout << "\n";
+  std::cout << x << "\n";
   return EXIT_SUCCESS;
 }
+

The output is

+ 
 11001
@@ -287,8 +381,8 @@ int main(int, char*[]) {
-

-An example of creating some bitsets from integers (unsigned longs). +

An example of creating some bitsets from integers (unsigned +longs).

@@ -296,23 +390,25 @@ An example of creating some bitsets from integers (unsigned longs).
 #include <boost/dynamic_bitset.hpp>
 int main(int, char*[])
 {
-  const boost::dynamic_bitset<> b0(2, 0ul); 
-  std::cout << "bits(0) = " << b0 << std::endl;
+  const boost::dynamic_bitset<> b0(2, 0ul);
+  std::cout << "bits(0) = " << b0 << std::endl;
 
-  const boost::dynamic_bitset<> b1(2, 1ul); 
-  std::cout << "bits(1) = " << b1 << std::endl;
+  const boost::dynamic_bitset<> b1(2, 1ul);
+  std::cout << "bits(1) = " << b1 << std::endl;
 
-  const boost::dynamic_bitset<> b2(2, 2ul); 
-  std::cout << "bits(2) = " << b2 << std::endl;
+  const boost::dynamic_bitset<> b2(2, 2ul);
+  std::cout << "bits(2) = " << b2 << std::endl;
 
-  const boost::dynamic_bitset<> b3(2, 3ul); 
-  std::cout << "bits(3) = " << b3 << std::endl;
+  const boost::dynamic_bitset<> b3(2, 3ul);
+  std::cout << "bits(3) = " << b3 << std::endl;
 
   return EXIT_SUCCESS;
 }
+

The output is

+ 
 bits(0) = 00
@@ -322,34 +418,34 @@ bits(3) = 11
-

-An example of performing some bitwise operations. -

+

An example of performing some bitwise operations.

 #include <iostream>
 #include <boost/dynamic_bitset.hpp>
 int main(int, char*[]) {
-  const boost::dynamic_bitset<> mask(12, 2730ul); 
-  std::cout << "mask = " << mask << std::endl;
+  const boost::dynamic_bitset<> mask(12, 2730ul);
+  std::cout << "mask = " << mask << std::endl;
 
   boost::dynamic_bitset<> x(12);
 
-  std::cout << "Enter a 12-bit bitset in binary: " << std::flush;
+  std::cout << "Enter a 12-bit bitset in binary: " << std::flush;
   if (std::cin >> x) {
-    std::cout << "input number:     " << x << std::endl;
-    std::cout << "As unsigned long: " << x.to_ulong() << std::endl;
-    std::cout << "And with mask:    " << (x & mask) << std::endl;
-    std::cout << "Or with mask:     " << (x | mask) << std::endl;
-    std::cout << "Shifted left:     " << (x << 1) << std::endl;
-    std::cout << "Shifted right:    " << (x >> 1) << std::endl;
+    std::cout << "input number:     " << x << std::endl;
+    std::cout << "As unsigned long: " << x.to_ulong() << std::endl;
+    std::cout << "And with mask:    " << (x & mask) << std::endl;
+    std::cout << "Or with mask:     " << (x | mask) << std::endl;
+    std::cout << "Shifted left:     " << (x << 1) << std::endl;
+    std::cout << "Shifted right:    " << (x >> 1) << std::endl;
   }
   return EXIT_SUCCESS;
 }
+

The output is

+ 
 mask = 101010101010
@@ -363,238 +459,319 @@ Shifted right:    010011010110
-

Rationale

-The dynamic_bitset does not provide iterators (and therefore is -not a -Container) for the following reasons: +The dynamic_bitset does not provide iterators (and +therefore is not a Container) for +the following reasons: +
    -
  1. std::bitset does not have iterators, and - dynamic_bitset is meant to be a run-time sized version of - std::bitset. +
  2. std::bitset does not have iterators, and +dynamic_bitset is meant to be a run-time sized version +of std::bitset.
    3. -
  3. The dynamic_bitset is not - designed to be a - Container.
    4. +
  4. The dynamic_bitset is not designed to be a Container.
    5. -
  5. A container with a proxy reference type can not - fulfill the container requirements as specified in the C++ - standard (unless one resorts to strange iterator - semantics). std::vector<bool> has a proxy - reference type and does not fulfill the container - requirements and as a result has caused many problems. One common - problem is when people try to use iterators from - std::vector<bool> with a Standard algorithm such as - std::search. The std::search requirements say - that the iterator must be a Forward - Iterator, but the std::vector<bool>::iterator - does not meet this requirement because of the proxy reference. - Depending on the implementation, they may or not be a compile - error or even a run-time error due to this misuse. For further - discussion of the problem see Effective STL by Scott - Meyers). So dynamic_bitset tries to avoid these problems by - not pretending to be a container.
    6. +
  6. A container with a proxy reference type can not +fulfill the container requirements as specified in the C++ +standard (unless one resorts to strange iterator semantics). +std::vector<bool> has a proxy reference +type and does not fulfill the container requirements and as a +result has caused many problems. One common problem is when +people try to use iterators from std::vector<bool> +with a Standard algorithm such as std::search. The +std::search requirements say that the iterator must be a +Forward +Iterator, but the std::vector<bool>::iterator +does not meet this requirement because of the proxy reference. +Depending on the implementation, they may or not be a compile +error or even a run-time error due to this misuse. For further +discussion of the problem see Effective STL by Scott +Meyers). So dynamic_bitset tries to avoid these problems +by not pretending to be a container.
-

-Some people prefer the name "toggle" to - "flip". The name "flip" was chosen because that - is the name used in std::bitset. - In fact, most of the function names for dynamic_bitset were chosen for - this reason.

- -

-dynamic_bitset does not throw exceptions when a precondition -is violated (as is done in std::bitset). Instead -assert is used. See the guidelines for Error and -Exception Handling for the explanation. -

+

Some people prefer the name "toggle" to "flip". The name +"flip" was chosen because that is the name used in std::bitset. +In fact, most of the function names for dynamic_bitset +were chosen for this reason.

+

dynamic_bitset does not throw exceptions when a +precondition is violated (as is done in std::bitset). +Instead assert is used. See the guidelines for Error and Exception Handling +for the explanation.

Header Files

-

The class dynamic_bitset is defined in the header -boost/dynamic_bitset.hpp. Also, there is a forward declaration for -dynamic_bitset in the header -boost/dynamic_bitset_fwd.hpp.

- +

The class dynamic_bitset is defined in the header boost/dynamic_bitset.hpp. +Also, there is a forward declaration for dynamic_bitset +in the header boost/dynamic_bitset_fwd.hpp.

Template parameters

- - - - - - - - - - - + +
-Parameter - -Description - -Default -
-Block - -The integer type in which the bits are stored. - -unsigned long -
- - - + + + + + + + + + + + + + + +
-Allocator - -The allocator type used for all internal memory management. - -std::allocator<Block> -ParameterDescriptionDefault
Block The integer type in which the bits are +stored.unsigned long
Allocator The allocator type used for all internal memory +management.std::allocator<Block>
+

Concepts Modeled

-Assignable, -Default Constructible, -Equality Comparable, -LessThan Comparable. +Assignable, Default +Constructible, Equality +Comparable, LessThan +Comparable.

Type requirements

-Block is an unsigned integer type. Allocator satisfies -the Standard requirements for an Allocator. + +Block is an unsigned integer type. Allocator +satisfies the Standard requirements for an allocator.

Public base classes

+ None. -

Member typedefs

+

Nested type names

- 
 dynamic_bitset::reference
-

A proxy class that acts as a reference to a single bit. It contains -an assignment operator, a conversion to bool, an -operator~, and a member function flip. It exists -only as a helper class for dynamic_bitset's -operator[]. The following table describes the valid -operations on the reference type. Assume that b is -an instance of dynamic_bitset, i, j are of -size_type and in the range [0,b.size()). Also, note -that when we write b[i] we mean an object of type -reference that was initialized from b[i]. The + +

A proxy class that acts as a reference to a single bit. It +contains an assignment operator, a conversion to bool, +an operator~, and a member function flip. It +exists only as a helper class for dynamic_bitset's +operator[]. The following table describes the valid +operations on the reference type. Assume that b +is an instance of dynamic_bitset, i, j are of +size_type and in the range [0,b.size()). Also, +note that when we write b[i] we mean an object of type +reference that was initialized from b[i]. The variable x is a bool.

- - - - +
ExpressionSemantics
x = b[i] Assign the ith bit of b to x.
(bool)b[i] Return the ith bit of b.
+ + + + - - - - - + + + + - - - - - + + + + + + + + - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExpressionSemantics
b[i] = x Set the ith bit of b to the value of x and return b[i].
b[i] |= x Or the ith bit of b with the value of x and return b[i].
b[i] &= x And the ith bit of b with the value of x and return b[i].
b[i] ^= x Exclusive-Or the ith bit of b with the value of x and return b[i].
b[i] -= x If x==true, clear the ith bit of b. Returns b[i].
x = b[i]Assign the ith bit of b to x.
b[i] = b[j] Set the ith bit of b to the value of the jth bit of b and return b[i].
b[i] |= b[j] Or the ith bit of b with the - jth bit of b and return b[i].
b[i] &= b[j] And the ith bit of b with the jth bit of b and return b[i].
b[i] ^= b[j] Exclusive-Or the ith bit of b with the jth bit of b and return b[i].
b[i] -= b[j] If the jth bit of b is set, clear the ith bit of b. Returns b[i].
(bool)b[i]Return the ith bit of b.
b[i] = xSet the ith bit of b to the value of x and +return b[i].
x = ~b[i] Assign the opposite of the ith bit of b to x.
(bool)~b[i] Return the opposite of the ith bit of b.
b[i].flip() Flip the ith bit of b and return b[i].
b[i] |= xOr the ith bit of b with the value of x and +return b[i].
b[i] &= xAnd the ith bit of b with the value of x +and return b[i].
b[i] ^= xExclusive-Or the ith bit of b with the value of +x and return b[i].
b[i] -= xIf x==true, clear the ith bit of b. Returns +b[i].
b[i] = b[j]Set the ith bit of b to the value of the jth bit of +b and return b[i].
b[i] |= b[j]Or the ith bit of b with the jth bit of b +and return b[i].
b[i] &= b[j]And the ith bit of b with the jth bit of b +and return b[i].
b[i] ^= b[j]Exclusive-Or the ith bit of b with the jth bit of +b and return b[i].
b[i] -= b[j]If the jth bit of b is set, clear the ith bit of +b. Returns b[i].
x = ~b[i]Assign the opposite of the ith bit of b to +x.
(bool)~b[i]Return the opposite of the ith bit of b.
b[i].flip() Flip the ith bit of b and return b[i].
 dynamic_bitset::const_reference
+ The type bool. 
 dynamic_bitset::size_type
-The unsigned integer for representing the size of the bit set. + +The unsigned integer type for representing the size of the bit set.
- 
 dynamic_bitset::block_type
-The same type as the Block template parameter. + +The same type as Block.
+
+dynamic_bitset::allocator_type;
+
+The same type as Allocator. + +
+

Public data members

+ +
 dynamic_bitset::bits_per_block
-The number of bits in a Block. + +The number of bits the type Block uses to represent values, +excluding any padding bits. Numerically equal +to std::numeric_limits<Block>::digits.
+
+dynamic_bitset::npos
+
+The maximum value of size_type. [gps] + +

Constructors

- 
-dynamic_bitset(const Allocator& alloc = Allocator())
+dynamic_bitset(const Allocator& alloc = Allocator())
-Effects: Constructs a bitset of size zero. -A copy of the alloc object will be used in subsequent -bitset operations such as resize to allocate memory.
- -Postconditions: this->size() == 0.
- -Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
- -(Required by -Default Constructible.) +Effects: Constructs a bitset of size zero. A copy of the +alloc object will be used in subsequent bitset +operations such as resize to allocate memory.
+ Postconditions: this->size() == 0.
+ Throws: An allocation error if memory is exhausted +(std::bad_alloc if +Allocator=std::allocator).
+ (Required by Default +Constructible.)
- 
 dynamic_bitset(size_type num_bits,
                unsigned long value = 0,
-               const Allocator& alloc = Allocator())
+               const Allocator& alloc = Allocator())
-Effects: Constructs a bitset from an integer. The first +Effects: Constructs a bitset from an integer. The first M bits are initialized to the corresponding bits in -val and all other bits, if any, to zero (where -M = min(num_bits, sizeof(unsigned long) * CHAR_BIT)). A copy -of the alloc object will be used in subsequent bitset +val and all other bits, if any, to zero (where M = +min(num_bits, std::numeric_limits<unsigned long>::digits)). A copy of +the alloc object will be used in subsequent bitset operations such as resize to allocate memory.
+ Postconditions: -Postconditions: Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
+(std::bad_alloc if +Allocator=std::allocator).
+
- 
 dynamic_bitset(const dynamic_bitset& x)
@@ -602,773 +779,984 @@ operations such as resize to allocate memory.
Effects: Constructs a bitset that is a copy of the bitset x. The allocator for this bitset is a copy of the allocator in x.
- -Postconditions: For all i in the range - [0,x.size()), (*this)[i] == x[i].
- -Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
- -(Required by -Assignable.) + Postconditions: For all i in the range +[0,x.size()), (*this)[i] == x[i].
+ Throws: An allocation error if memory is exhausted +(std::bad_alloc if +Allocator=std::allocator).
+ (Required by Assignable.)
- 
 template <typename BlockInputIterator>
 explicit
-dynamic_bitset(BlockInputIterator first, BlockInputIterator last,
+dynamic_bitset(BlockInputIterator first, BlockInputIterator last,
                const Allocator& alloc = Allocator());
Effects: Constructs a bitset based on a range of blocks. -Let *first be block number 0, *++first block number -1, etc. Block number b is used to initialize the bits of the -dynamic_bitset in the position range [b*bits_per_block, (b+1)*bits_per_block). For -each block number b with value bval, the bit -(bval >> i) & 1 corresponds to the bit at position (b * -bits_per_block + i) in the bitset (where i goes through the -range [0, bits_per_block)).
- -Requires: The type BlockInputIterator must be a model -of Input +Let *first be block number 0, *++first block +number 1, etc. Block number b is used to initialize the +bits of the dynamic_bitset in the position range +[b*bits_per_block, (b+1)*bits_per_block). For each block +number b with value bval, the bit (bval +>> i) & 1 corresponds to the bit at position +(b * bits_per_block + i) in the bitset (where i +goes through the range [0, bits_per_block)).
+ Requires: The type BlockInputIterator must be a +model of Input Iterator and its value_type must be the same type as Block.
+ Throws: An allocation error if memory is exhausted +(std::bad_alloc if +Allocator=std::allocator).
-Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
- 
 template<typename Char, typename Traits, typename Alloc>
 explicit
-dynamic_bitset(const std::basic_string<Char,Traits,Alloc>& s,
+dynamic_bitset(const std::basic_string<Char,Traits,Alloc>& s,
                typename std::basic_string<CharT, Traits, Alloc>::size_type pos = 0,
-               typename std::basic_string<CharT, Traits, Alloc>::size_type n = std::basic_string<Char,Traits,Alloc>::npos,
-               const Allocator& alloc = Allocator()) 
+               typename std::basic_string<CharT, Traits, Alloc>::size_type n = std::basic_string<Char,Traits,Alloc>::npos,
+               const Allocator& alloc = Allocator())
-Precondition: pos <= s.size() -and the characters used to -initialize the bits must be 0 or 1.
- -Effects: Constructs a bitset from a string of 0's and 1's. The -first M bits are initialized to the corresponding characters -in s, where M = min(s.size() - pos, n). Note that -the highest character position in s, not the lowest, -corresponds to the least significant bit. That is, character position -pos + M - 1 - i corresponds to bit i. So, for -example, dynamic_bitset(string("1101")) is the same as +Precondition: pos <= s.size() and the +characters used to initialize the bits must be 0 or +1.
+ Effects: Constructs a bitset from a string of 0's and +1's. The first M bits are initialized to the +corresponding characters in s, where M = +min(s.size() - pos, n). Note that the highest +character position in s, not the lowest, corresponds to +the least significant bit. That is, character position pos + +M - 1 - i corresponds to bit i. So, for example, +dynamic_bitset(string("1101")) is the same as dynamic_bitset(13ul).
- -Throws: an allocation error if memory is exhausted + Throws: an allocation error if memory is exhausted (std::bad_alloc if Allocator=std::allocator).
-

Destructor

 ~dynamic_bitset()
+ Effects: Releases the memory associated with this bitset and destroys the bitset object itself.
- -Throws: nothing. - + Throws: nothing.
-

Member Functions

 void swap(dynamic_bitset& b);
+ Effects: The contents of this bitset and bitset b - are exchanged.
-Postconditions: This bitset is equal to the original b, - and b is equal to the previous version of this bitset.
+are exchanged.
+Postconditions: This bitset is equal to the original +b, and b is equal to the previous version of +this bitset.
Throws: nothing.
- 
-dynamic_bitset& operator=(const dynamic_bitset& x)
+dynamic_bitset& operator=(const dynamic_bitset& x)
-Effects: This bitset becomes a copy of the bitset x.
- -Postconditions: For all i in the range - [0,x.size()), (*this)[i] == x[i].
- -Returns: *this.
- -Throws: nothing. - -
-(Required by - Assignable.) - +Effects: This bitset becomes a copy of the bitset +x.
+ Postconditions: For all i in the range +[0,x.size()), (*this)[i] == x[i].
+ Returns: *this.
+ Throws: nothing.
+(Required by Assignable.)
- 
-void resize(size_type num_bits, bool value = false);
+allocator_type get_allocator() const;
+
+ Returns: A copy of the allocator object used to construct *this. + +
+
+void resize(size_type num_bits, bool value = false);
Effects: Changes the number of bits of the bitset to -num_bits. If num_bits > size() then the bits in the -range [0,size()) remain the same, and the bits in -[size(),num_bits) are all set to value. If -num_bits < size() then the bits in the range +num_bits. If num_bits > size() then the bits +in the range [0,size()) remain the same, and the bits in +[size(),num_bits) are all set to value. If +num_bits < size() then the bits in the range [0,num_bits) stay the same (and the remaining bits are discarded).
+ Postconditions: this->size() == num_bits.
+ Throws: An allocation error if memory is exhausted +(std::bad_alloc if +Allocator=std::allocator).
-Postconditions: this->size() == num_bits.
- -Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
-
- 
 void clear()
-Effects: The size of the bitset becomes zero.
-Throws: nothing. +Effects: The size of the bitset becomes zero.
+ Throws: nothing.
- 
 void push_back(bool value);
-Effects: Increases the size of the bitset by one, and sets the value of -the new most-significant bit to value.
-Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
+Effects: Increases the size of the bitset by one, and sets +the value of the new most-significant bit to value.
+ Throws: An allocation error if memory is exhausted +(std::bad_alloc if +Allocator=std::allocator).
+
- 
 void append(Block value);
-Effects: Appends the bits in value to the bitset -(appends to the most-significant end). This increases the size of the -bitset by bits_per_block. Let s be the old size of the -bitset, then for i in the range [0,bits_per_block), the -bit at position (s + i) is set to ((value >> i) & -1).
-Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
+Effects: Appends the bits in value to the bitset +(appends to the most-significant end). This increases the size of +the bitset by bits_per_block. Let s be the old +size of the bitset, then for i in the range +[0,bits_per_block), the bit at position (s + i) +is set to ((value >> i) & 1).
+ Throws: An allocation error if memory is exhausted +(std::bad_alloc if +Allocator=std::allocator).
+
- 
 template <typename BlockInputIterator>
-void append(BlockInputIterator first, BlockInputIterator last);
+void append(BlockInputIterator first, BlockInputIterator last);
-Effects: This function provides the same end result as the following -code, but is typically more efficient. + +Effects: This function provides the same end result as the +following code, but is typically more efficient. [gps] + 
 for (; first != last; ++first)
   append(*first);
-Requires: The BlockInputIterator type must be a model -of Input +Requires: The BlockInputIterator type must be a +model of Input Iterator and the value_type must be the same type as Block.
+ Throws: An allocation error if memory is exhausted +(std::bad_alloc if +Allocator=std::allocator).
-Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator).
- 
-dynamic_bitset& operator&=(const dynamic_bitset& rhs)
+dynamic_bitset& operator&=(const dynamic_bitset& rhs)
Requires: this->size() == rhs.size().
+ Effects: Bitwise-AND all the bits in rhs with +the bits in this bitset. This is equivalent to: -Effects: Bitwise-AND all the bits in rhs with the -bits in this bitset. This is equivalent to: 
-for (size_type i = 0; i != this->size(); ++i)
-  (*this)[i] = (*this)[i] & rhs[i];
+for (size_type i = 0; i != this->size(); ++i)
+  (*this)[i] = (*this)[i] & rhs[i];
Returns: *this.
- -Throws: nothing. + Throws: nothing.
- -
dynamic_bitset& operator|=(const dynamic_bitset& rhs)
-
-Requires: this->size() == rhs.size().
- -Effects: Bitwise-OR's all the bits in rhs -with the bits in this bitset. This is equivalent to: 
-for (size_type i = 0; i != this->size(); ++i)
+dynamic_bitset& operator|=(const dynamic_bitset& rhs)
+
+ +Requires: this->size() == rhs.size().
+ Effects: Bitwise-OR's all the bits in rhs with +the bits in this bitset. This is equivalent to: + +
+for (size_type i = 0; i != this->size(); ++i)
   (*this)[i] = (*this)[i] | rhs[i];
Returns: *this.
- -Throws: nothing. + Throws: nothing.
- 
-dynamic_bitset& operator^=(const dynamic_bitset& rhs)
+dynamic_bitset& operator^=(const dynamic_bitset& rhs)
-Requires: this->size() == rhs.size().
-Effects: Bitwise-XOR's all the bits in rhs -with the bits in this bitset. This is equivalent to: +Requires: this->size() == rhs.size().
+ Effects: Bitwise-XOR's all the bits in rhs with +the bits in this bitset. This is equivalent to: + 
-for (size_type i = 0; i != this->size(); ++i)
+for (size_type i = 0; i != this->size(); ++i)
   (*this)[i] = (*this)[i] ^ rhs[i];
Returns: *this.
- -Throws: nothing. + Throws: nothing.
- 
-dynamic_bitset& operator-=(const dynamic_bitset& rhs)
+dynamic_bitset& operator-=(const dynamic_bitset& rhs)
+ Requires: this->size() == rhs.size().
+ Effects: Computes the set difference of this bitset and +the rhs bitset. This is equivalent to: -Effects: Computes the set difference of -this bitset and the rhs bitset. This is equivalent to: 
-for (size_type i = 0; i != this->size(); ++i)
-  (*this)[i] = (*this)[i] && !rhs[i];
+for (size_type i = 0; i != this->size(); ++i)
+  (*this)[i] = (*this)[i] && !rhs[i];
Returns: *this.
- -Throws: nothing. + Throws: nothing.
- 
-dynamic_bitset& operator<<=(size_type n)
+dynamic_bitset& operator<<=(size_type n)
+ Effects: Shifts the bits in this bitset to the left by -n bits. For each bit in the bitset, the bit at position pos -takes on the previous value of the bit at position pos - n, -or zero if no such bit exists.
- -Returns: *this.
- -Throws: nothing. +n bits. For each bit in the bitset, the bit at position +pos takes on the previous value of the bit at position pos - +n, or zero if no such bit exists.
+ Returns: *this.
+ Throws: nothing.
- 
-dynamic_bitset& operator>>=(size_type n)
+dynamic_bitset& operator>>=(size_type n)
+ Effects: Shifts the bits in this bitset to the right by n bits. For each bit in the bitset, the bit at position -pos takes on the previous value of bit pos + n, or -zero if no such bit exists.
- -Returns: *this.
- -Throws: nothing. +pos takes on the previous value of bit pos + n, +or zero if no such bit exists.
+ Returns: *this.
+ Throws: nothing.
- 
-dynamic_bitset operator<<(size_type n) const
+dynamic_bitset operator<<(size_type n) const
-Returns: a copy of *this shifted to the left by n -bits. For each bit in the returned bitset, the bit at position pos -takes on the value of the bit at position pos - n of this -bitset, or zero if no such bit exists. -Note that the expression b << n is equivalent to + +Returns: a copy of *this shifted to the left by +n bits. For each bit in the returned bitset, the bit at +position pos takes on the value of the bit at position pos - +n of this bitset, or zero if no such bit exists. Note that +the expression b << n is equivalent to constructing a temporary copy of b and then using operator<<=.
- -Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). + Throws: An allocation error if memory is exhausted +(std::bad_alloc if Allocator=std::allocator).
- 
-dynamic_bitset operator>>(size_type n) const
+dynamic_bitset operator>>(size_type n) const
Returns: a copy of *this shifted to the right by -n bits. For each bit in the returned bitset, the bit at +n bits. For each bit in the returned bitset, the bit at position pos takes on the value of the bit at position pos + -n of this bitset, or zero if no such bit exists. Note that the -expression b >> n is equivalent to constructing a -temporary copy of b and then using +n of this bitset, or zero if no such bit exists. Note that +the expression b >> n is equivalent to +constructing a temporary copy of b and then using operator>>=.
- -Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). + Throws: An allocation error if memory is exhausted +(std::bad_alloc if Allocator=std::allocator).
- 
 dynamic_bitset& set()
+ Effects: Sets every bit in this bitset to 1.
Returns: *this
Throws: nothing.
- 
 dynamic_bitset& flip()
+ Effects: Flips the value of every bit in this bitset.
Returns: *this
Throws: nothing.
- 
 dynamic_bitset operator~() const
-Returns: a copy of *this with all of its bits flipped.
+ +Returns: a copy of *this with all of its bits +flipped.
Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). +(std::bad_alloc if Allocator=std::allocator).
- 
 dynamic_bitset& reset()
+ Effects: Clears every bit in this bitset.
Returns: *this
Throws: nothing. -
+
-dynamic_bitset& set(size_type n, bool val = true)
+dynamic_bitset& set(size_type n, bool val = true)
Precondition: n < this->size().
- -Effects: Sets bit n if val is true, - and clears bit n if val is false.
- -Returns: *this + Effects: Sets bit n if val is +true, and clears bit n if val is +false.
+ Returns: *this
- 
 dynamic_bitset& reset(size_type n)
+ Precondition: n < this->size().
Effects: Clears bit n.
Returns: *this
- 
 dynamic_bitset& flip(size_type n)
+ Precondition: n < this->size().
Effects: Flips bit n.
Returns: *this
- 
 size_type size() const
+ Returns: the number of bits in this bitset.
Throws: nothing. -
+
 size_type num_blocks() const
+ Returns: the number of blocks in this bitset.
Throws: nothing. -
+
+
+size_type max_size() const;
+
+ +Returns: the maximum size of a dynamic_bitset +object having the same type as *this. Note that if +any dynamic_bitset operation causes size() to +exceed max_size() then the behavior is undefined. +

[The semantics of this function could change slightly +when lib issue 197 will be closed - G.P.S.]
+ +
+
+bool empty() const;
+
+ +Returns: true if this->size() == 0, false +otherwise. Note: not to be confused with none(), that has +different semantics. + +
+ + +
 size_type count() const
-Returns: the number of bits in this bitset that are set.
+ +Returns: the number of bits in this bitset that are +set.
Throws: nothing.
- 
 bool any() const
+ Returns: true if any bits in this bitset are set, and otherwise returns false.
Throws: nothing.
- 
 bool none() const
+ Returns: true if no bits are set, and otherwise returns false.
Throws: nothing.
- 
 bool test(size_type n) const
-Precondition: n < this->size().
-Returns: true if bit n is set and +Precondition: n < this->size().
+ Returns: true if bit n is set and false is bit n is 0. -
- 
 reference operator[](size_type n)
- + Precondition: n < this->size().
- -Returns: a reference to bit n. Note that -reference is a proxy class with an assignment operator and a -conversion to bool, which allows you to use -operator[] for assignment. That is, you can write both x -= b[n] and b[n] = x. However, in many other respects the -proxy is not the same as the true reference type bool&. - + Returns: a reference to bit n. Note +that reference is a proxy class with an assignment +operator and a conversion to bool, which allows you to +use operator[] for assignment. That is, you can write +both x = b[n] and b[n] = x. However, in many +other respects the proxy is not the same as the true reference +type bool&.
- 
 bool operator[](size_type n) const
-Precondition: n < this->size().
-Returns: true if bit n is set. +Precondition: n < this->size().
+Returns: The same as test(n).
- 
 unsigned long to_ulong() const
-Returns: An unsigned long integer whose bits -corresponds to the bits in this bitset, as long as there are no bits -in the bitset that are set to 1 at a position greater than -sizeof(unsigned long) * CHAR_BIT. -Throws: std::overflow_error if the value of the bitset -can not be represented in an unsigned long. +Returns: The numeric value corresponding to the bits in *this. +
+Throws: std::overflow_error if that value is too large to +be represented in an unsigned long, i.e. if *this has +any non-zero bit at a position >= +std::numeric_limits<unsigned long>::digits.
- 
-bool is_subset_of(const dynamic_bitset& a) const
+bool is_subset_of(const dynamic_bitset& a) const
-Requires: this->size() == a.size()
-Returns: true if this bitset is a subset of bitset a. -That is, it returns true if, for every bit that is set in this bitset, the -corresponding bit in bitset a is also set. Otherwise this -function returns false.
+ +Requires: this->size() == a.size()
+Returns: true if this bitset is a subset of bitset +a. That is, it returns true if, for every bit that is +set in this bitset, the corresponding bit in bitset a is +also set. Otherwise this function returns false.
Throws: nothing.
- 
-bool is_proper_subset_of(const dynamic_bitset& a) const
+bool is_proper_subset_of(const dynamic_bitset& a) const
-Requires: this->size() == a.size()
-Returns: true if this bitset is a proper subset of bitset a. -That is, it returns true if, for every bit that is set in this bitset, the -corresponding bit in bitset a is also set and if -this->count() < a.count(). Otherwise this -function returns false.
+ +Requires: this->size() == a.size()
+Returns: true if this bitset is a proper subset of bitset +a. That is, it returns true if, for every bit that is +set in this bitset, the corresponding bit in bitset a is +also set and if this->count() < a.count(). +Otherwise this function returns false.
Throws: nothing.
- 
-bool operator==(const dynamic_bitset& rhs) const
+size_type find_first() const;
+ +Returns: the lowest index i such as bit i +is set, or npos if *this has no on bits. + +
+
+size_type find_next(size_type pos) const;
+
+ +Returns: the lowest index i greater than +pos such as bit i is set, or npos if +no such index exists. + +
+
+bool operator==(const dynamic_bitset& rhs) const
+
+ Returns: true if this->size() == rhs.size() and if for all i in the range [0,rhs.size()), (*this)[i] == rhs[i]. Otherwise returns false.
- -Throws: nothing.
- -(Required by Equality - Comparable.) + Throws: nothing.
+ (Required by Equality +Comparable.)
- 
-bool operator!=(const dynamic_bitset& rhs) const
+bool operator!=(const dynamic_bitset& rhs) const
+ Returns: !((*this) == rhs)
Throws: nothing.
-(Required by Equality - Comparable.) +(Required by Equality +Comparable.)
- 
-bool operator<(const dynamic_bitset& rhs) const
+bool operator<(const dynamic_bitset& rhs) const
-Returns: true if this bitset is lexicographically less -than rhs, and returns false otherwise. (See the -description of -lexicographical_compare for a definition of lexicographic -ordering).
+ +Returns: true if this bitset is lexicographically +less than rhs, and returns false otherwise. +(See the description of lexicographical_compare +for a definition of lexicographic ordering).
Throws: nothing.
-(Required by - Less Than Comparable.) +(Required by Less Than +Comparable.)
- 
-bool operator>(const dynamic_bitset& rhs) const
+bool operator>(const dynamic_bitset& rhs) const
-Returns: !((*this) < rhs || (*this) == rhs)
+ +Returns: !((*this) < rhs || (*this) == +rhs)
Throws: nothing.
-(Required by Less Than -Comparable.) +(Required by Less Than +Comparable.)
- 
-bool operator<=(const dynamic_bitset& rhs) const
+bool operator<=(const dynamic_bitset& rhs) const
-Returns: (*this) < rhs || (*this) == rhs
+ +Returns: (*this) < rhs || (*this) == rhs
Throws: nothing.
-(Required by - Less Than Comparable.) +(Required by Less Than +Comparable.)
- 
-bool operator>=(const dynamic_bitset& rhs) const
+bool operator>=(const dynamic_bitset& rhs) const
-Returns: (*this) > rhs || (*this) == rhs
+ +Returns: (*this) > rhs || (*this) == rhs
Throws: nothing.
-(Required by - Less Than Comparable.) +(Required by Less Than +Comparable.)
-

Non-Member Functions

- 
-dynamic_bitset operator&(const dynamic_bitset& a, const dynamic_bitset& b)
+dynamic_bitset operator&(const dynamic_bitset& a, const dynamic_bitset& b)
+ Requires: a.size() == b.size()
-Returns: A new bitset that is the bitwise-AND of the bitsets -a and b. Note that the expression b1 & -b2 is equivalent to creating a temporary copy of b1, -using operator&=, and returning the temporary copy.
+Returns: A new bitset that is the bitwise-AND of the +bitsets a and b. Note that the expression +b1 & b2 is equivalent to creating a temporary copy +of b1, using operator&=, and returning the +temporary copy.
Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). +(std::bad_alloc if Allocator=std::allocator).
- 
-dynamic_bitset operator|(const dynamic_bitset& a, const dynamic_bitset& b)
+dynamic_bitset operator|(const dynamic_bitset& a, const dynamic_bitset& b)
+ Requires: a.size() == b.size()
-Returns: A new bitset that is the bitwise-OR of the bitsets -a and b. Note that the expression b1 & -b2 is equivalent to creating a temporary copy of b1, -using operator&=, and returning the temporary copy.
+Returns: A new bitset that is the bitwise-OR of the +bitsets a and b. Note that the expression +b1 & b2 is equivalent to creating a temporary copy +of b1, using operator&=, and returning the +temporary copy.
Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). +(std::bad_alloc if Allocator=std::allocator).
- 
-dynamic_bitset operator^(const dynamic_bitset& a, const dynamic_bitset& b)
+dynamic_bitset operator^(const dynamic_bitset& a, const dynamic_bitset& b)
+ Requires: a.size() == b.size()
-Returns: A new bitset that is the bitwise-XOR of the bitsets -a and b. Note that the expression b1 & -b2 is equivalent to creating a temporary copy of b1, -using operator&=, and returning the temporary copy.
+Returns: A new bitset that is the bitwise-XOR of the +bitsets a and b. Note that the expression +b1 & b2 is equivalent to creating a temporary copy +of b1, using operator&=, and returning the +temporary copy.
Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). +(std::bad_alloc if Allocator=std::allocator).
- 
-dynamic_bitset operator-(const dynamic_bitset& a, const dynamic_bitset& b)
+dynamic_bitset operator-(const dynamic_bitset& a, const dynamic_bitset& b)
+ Requires: a.size() == b.size()
-Returns: A new bitset that is the set difference of the bitsets -a and b. Note that the expression b1 - b2 -is equivalent to creating a temporary copy of b1, -using operator-=, and returning the temporary copy.
+Returns: A new bitset that is the set difference of the +bitsets a and b. Note that the expression +b1 - b2 is equivalent to creating a temporary copy of +b1, using operator-=, and returning the +temporary copy.
Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). +(std::bad_alloc if Allocator=std::allocator).
- 
 template <typename CharT, typename Alloc>
-void to_string(const dynamic_bitset<Block, Allocator>& b,
-               std::basic_string<Char,Traits,Alloc>& s)
+void to_string(const dynamic_bitset<Block, Allocator>& b,
+               std::basic_string<Char,Traits,Alloc>& s)
-Effects: Copies a representation of b into the string -s. A character in the string is '1' if the -corresponding bit is set, and '0' if it is not. Character -position i in the string corresponds to bit position -b.size() - 1 - i.
- -Throws: If memory is exhausted, the string will throw an - allocation error.
- -Rationale: This function is not a member function taking zero - arguments and returning a string for a couple reasons. First, this - version can be slighly more efficient because the string is not - copied (due to being passed by value). Second, as a member function, - to allow for flexibility with regards to the template parameters of - basic_string, the member function would require explicit - template parameters. Few C++ programmers are familiar with explicit - template parameters, and some C++ compilers do not handle them - properly. - +Effects: Copies a representation of b into the +string s. A character in the string is '1' if +the corresponding bit is set, and '0' if it is not. +Character position i in the string corresponds to bit +position b.size() - 1 - i.
+ Throws: If memory is exhausted, the string will throw an +allocation error.
+ Rationale: This function is not a member function taking +zero arguments and returning a string for a couple reasons. +First, this version can be slighly more efficient because the +string is not copied (due to being passed by value). Second, as a +member function, to allow for flexibility with regards to the +template parameters of basic_string, the member function +would require explicit template parameters. Few C++ programmers +are familiar with explicit template parameters, and some C++ +compilers do not handle them properly. 
 template <typename Block, typename Alloc, typename BlockOutputIterator>
-void to_block_range(const dynamic_bitset<Block, Alloc>& b, BlockOutputIterator result)
+void to_block_range(const dynamic_bitset<Block, Alloc>& b, BlockOutputIterator result)
+ Effects: Writes the bits of the bitset into the iterator -result a block at a time. The first block written represents -the bits in the position range [0,bits_per_block) in the -bitset, the second block written the bits in the range -[bits_pre_block,2*bits_per_block), and so on. For each block -bval written, the bit (bval >> i) & 1 -corresponds to the bit at position (b * bits_per_block + i) -in the bitset.
- -Requires: The type BlockOutputIterator must be a model -of Output +result a block at a time. The first block written +represents the bits in the position range +[0,bits_per_block) in the bitset, the second block +written the bits in the range +[bits_pre_block,2*bits_per_block), and so on. For each +block bval written, the bit (bval >> i) & +1 corresponds to the bit at position (b * bits_per_block ++ i) in the bitset.
+ Requires: The type BlockOutputIterator must be a +model of Output Iterator and its value_type must be the same type as -Block. Further, the size of the output range must be greater -or equal b.num_blocks(). - +Block. Further, the size of the output range must be +greater or equal b.num_blocks(). 
 template <typename BlockIterator, typename Block, typename Alloc>
-void from_block_range(BlockIterator first,
+void from_block_range(BlockIterator first,
     BlockIterator last, const dynamic_bitset<Block, Alloc>& b)
+ Effects: Reads blocks from the iterator range into the bitset.
- -Requires: The type BlockIterator must be a model of Input + Requires: The type BlockIterator must be a model +of Input Iterator and its value_type must be the same type as -Block. The size of the iterator range must be less or equal -to b.num_blocks(). - +Block. The size of the iterator range must be less or +equal to b.num_blocks(). 
 template <typename Char, typename Traits, typename Block, typename Alloc>
 basic_ostream<Char, Traits>&
-operator<<(basic_ostream<Char, Traits>& os, const dynamic_bitset<Block, Alloc>& x)
+operator<<(basic_ostream<Char, Traits>& os, const dynamic_bitset<Block, Alloc>& b)
-Output a dynamic_bitset to an output stream. This function -behaves as if it converts the dynamic_bitset to a string and then -writes that string to the output stream. That is, it is equivalent to + +Effects: Inserts a textual representation of b into the stream +os (highest bit first). Informally, the output is the same as doing + 
 std::basic_string<Char, Traits> s;
-to_string(x, s):
-os << s;
+boost::to_string(x, s):
+os << s;
-Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). - Also will throw std::ios_base::failure if there is a problem - writing to the stream. +except that the stream inserter takes into accout the locale imbued into +os, which boost::to_string() can't do. Here is a more +precise specification, given in terms of "as if" rule: first, for each +valid position i into the bitset b let's put: + character_of(b[i)]) = b[i]? os.widen('1') : os.widen('0'); + +Let also s be a std::basic_string<Char, Traits> +object, having length b.size() and such as, for each i +in [0, b.size()), + + s[i] is character_of(b[i]) + +Then, the output, the effects on os and the exception behavior +is the same as outputting the object s to os (same +width, same exception mask, same padding, same setstate() logic) +
+Returns: os
+Throws: std::ios_base::failure if there is a +problem writing to the stream. 
 template <typename Char, typename Traits, typename Block, typename Alloc>
-basic_istream<Char,Traits>&
-operator>>(basic_istream<Char,Traits>& is, dynamic_bitset<Block, Alloc>& x)
+std::basic_istream<Char,Traits>&
+operator>>(std::basic_istream<Char,Traits>& is, dynamic_bitset<Block, Alloc>& b)
-Effects: Extracts a dynamic_bitset from an input -stream. This function first skips whitespace, then extracts up to -x.size() characters from the input stream. It stops either -when it has successfully extracted x.size() characters, or -when extraction fails, or when it sees a character that is something -other than 1 (in which case it does not extract that -character). If extraction is successful, the function then assigns a -value to the bitset in the same way as if it were initializing the -bitset from a string. So, for example, if the input stream contains -the characters "1100abc", it will assign the value -12ul to the bitset, and the next character read from the -input stream will be a.
+ +Effects: Extracts a dynamic_bitset from an input stream. +

+ Definitions:

+ Let Tr be the traits_type of is. Then: +
    +
  1. + A (non-eof) character c extracted from is + is a bitset digit if and only if either Tr::eq(c, is.widen('0')) or + Tr::eq(c, is.widen('1')) return true. +
    2. +
  2. If c is a bitset digit, it's corresponding bit value is 0 if + Tr::eq(c, is.widen('0')) is true, 1 otherwise. +
    3. +
+ +The function begins by constructing a sentry object k as if k +were constructed by + + typename std::basic_istream<Char, Traits>::sentry k(is). + +If bool(k) is true, it calls b.clear() +then attempts to extract characters from is. For each character c +that is a bitset digit the corresponding bit value is +appended to the less significant end of b (appending may throw - gps ). +If is.width() is greater than zero and smaller than b.max_size() +then the maximum number n of bits appended is is.width(); +otherwise n = b.max_size(). + +Unless the extractor is exited via an exception, characters are extracted (and +corresponding bits appended) until any of the following occurs:
+ + +
If no exception caused the function to exit then is.width(0) is + called, regardless of how many characters were actually extracted. The + sentry object k is destroyed. +
+
If the function extracts no characters[???], it calls is.setstate(std::ios::failbit), + which may throw std::ios_base::failure. + + +
------ + + +
Throws: An allocation error if memory is exhausted - (std::bad_alloc if Allocator=std::allocator). - Also will throw std::ios_base::failure if there is a problem - reading from the stream. +(std::bad_alloc if Allocator=std::allocator). +A std::ios_base::failure if there is a problem reading +from the stream.
+

Exception guarantees

+All of dynamic_bitset functions offer at least the basic +guarantee. In addition some functions offer the strong or the nothrow +guarantee as summarized in the table below (the destructor, as usual, +doesn't throw): + + + +
-strongnothrow
f x
+ + + +
+

Changes from previous version(s)

+ + +

Changes from Boost 1.31.0

+ +Technicalities and minor changes + +General improvements +

+Several optimizations to member and non-member functions and to the +nested class reference. + +

See also

-std::bitset, -std::vector, + +std::bitset, +std::vector,

Acknowledgements

-

-We would like to thank the Boost community for putting in the time to -review and accept this library. This library is much better than it -ever would have been due to all the suggestions from Boost members. We -especially thank Matt Marcus for taking on the task of review -manager. Also, a special thanks goes to Gennaro Prota for work on -increasing efficiency for many of dynamic_bitset's functions. -

+

We would like to thank the Boost community for putting in the +time to review and accept this library. This library is much +better than it ever would have been due to all the suggestions +from Boost members. We especially thank Matt Marcus for taking on +the task of review manager. Also, a special thanks goes to +James Kanze for his invaluable help with the internationalization +issues.

-
- - -
Copyright © 2001 -Jeremy Siek, -Indiana University (jsiek@osl.iu.edu)
-Chuck Allison, Senior Editor, C/C++ Users Journal (cda@freshsources.com)
-
+
+ + + + + + + + + + + + + + +
Copyright © 2001Jeremy Siek, +Indiana University (jsiek@osl.iu.edu)
+Chuck Allison, Senior +Editor, C/C++ Users Journal (cda@freshsources.com)
+
Copyright © 2003-2004Gennaro Prota
- - + + +