dynamic_bitset documentation and examples:

Documentation:
    --------------

    * converted from HTML 4.01 Transitional to XHTML 1.1 (reason: the website
      uses already XHTML 1.0 Strict, and our page didn't validate as such, even
      though on the website a link to the W3C markup validation service is
      affixed)
    * removed some misleading sentences
    * referenced the source files of examples, so that they do not go out of
      sync again
    * clarified rationale section

    Example files:
    --------------

    * example 3 shows that stream extraction may expand the bitset
    * minor improvements to all examples


[SVN r47389]

example/example1.cpp

@@ -3,23 +3,33 @@
 // accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 
-// Sample output:
-//  1
-//  1
-//  0
-//  0
-//  1
+
+
+// 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 used to reading.
+//
+//  The output is:
+//
+//  11001
+//  10011
+// ---------------------------------------------------------------------
 
 #include <iostream>
 #include <boost/dynamic_bitset.hpp>
-int main() {
-  boost::dynamic_bitset<> x(5); // all 0's by default
-  x[0] = 1;
-  x[1] = 1;
-  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";
-  return EXIT_SUCCESS;
+
+int main()
+{
+    boost::dynamic_bitset<> x(5); // all 0's by default
+    x[0] = 1;
+    x[1] = 1;
+    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";
+
+    return 0;
 }

example/example2.cpp

@@ -3,14 +3,17 @@
 // accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 //
-// Sample output:
+//  Sample output:
+//
 //  bits(0) = 00
 //  bits(1) = 01
 //  bits(2) = 10
 //  bits(3) = 11
 
+
 #include <iostream>
 #include <boost/dynamic_bitset.hpp>
+
 int main()
 {
   const boost::dynamic_bitset<> b0(2, 0ul); 
@@ -25,5 +28,5 @@ int main()
   const boost::dynamic_bitset<> b3(2, 3ul); 
   std::cout << "bits(3) = " << b3 << std::endl;
 
-  return EXIT_SUCCESS;
+  return 0;
 }

example/example3.cpp

@@ -1,35 +1,70 @@
-// (C) Copyright Jeremy Siek 2001.
+// Copyright (c) 2001 Jeremy Siek
+// Copyright (c) 2008 Gennaro Prota
 // 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)
 //
-// Sample output:
-//  mask =      101010101010
-//  Enter a 12-bit bitset in binary: 100110101101
-//  x =        100110101101
-//  As ulong:  2477
-//  And with mask: 100010101000
-//  Or with mask:  101110101111
+// Sample run:
+//
+// mask     = 101010101010
+// x.size() = 0
+// Enter a bitset in binary: x = 100100010
+//
+// Input number:             100100010
+// x.size() is now:          9
+// As unsigned long:         290
+// Mask (possibly resized):  010101010
+// And with mask:            000100010
+// Or with mask:             110101010
+// Shifted left by 1:        001000100
+// Shifted right by 1:       010010001
 
 
+
+#include <ostream>
 #include <iostream>
 #include <boost/dynamic_bitset.hpp>
 
-int main(int, char*[]) {
-  const boost::dynamic_bitset<> mask(12, 2730ul); 
-  std::cout << "mask = " << mask << std::endl;
+int main()
+{
+    boost::dynamic_bitset<> mask(12, 2730ul); 
+    std::cout << "mask     = " << mask << std::endl;
 
-  boost::dynamic_bitset<> x(12);
-  std::cout << "x.size()=" << x.size() << std::endl;
+    boost::dynamic_bitset<> x;
+    std::cout << "x.size() = " << x.size() << std::endl;
 
-  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;
-  }
-  return EXIT_SUCCESS;
+    std::cout << "Enter a bitset in binary: x = " << std::flush;
+    if (std::cin >> x) {
+        const std::size_t sz = x.size();
+        std::cout << std::endl;
+        std::cout << "Input number:             " << x << std::endl;
+        std::cout << "x.size() is now:          " << sz << std::endl;
+
+        bool fits_in_ulong = true;
+        unsigned long ul = 0;
+        try {
+            ul = x.to_ulong();
+        } catch(std::overflow_error &) {
+            fits_in_ulong = false;
+        }
+
+        std::cout << "As unsigned long:         ";
+        if(fits_in_ulong) {
+            std::cout << ul;
+        } else {
+            std::cout << "(overflow exception)";
+        }
+        
+        std::cout << std::endl;
+
+        mask.resize(sz);
+
+        std::cout << "Mask (possibly resized):  " << mask << std::endl;
+
+        std::cout << "And with mask:            " << (x & mask) << std::endl;
+        std::cout << "Or with mask:             " << (x | mask) << std::endl;
+        std::cout << "Shifted left by 1:        " << (x << 1) << std::endl;
+        std::cout << "Shifted right by 1:       " << (x >> 1) << std::endl;
+    }
+    return 0;
 }