[Boost-commit] svn:boost r60989 - sandbox/xint/libs/xint/example

Subject: [Boost-commit] svn:boost r60989 - sandbox/xint/libs/xint/example
From: pbristow_at_[hidden]
Date: 2010-04-01 07:56:20

Author: pbristow
Date: 2010-04-01 07:56:18 EDT (Thu, 01 Apr 2010)
New Revision: 60989
URL: http://svn.boost.org/trac/boost/changeset/60989

Log:
Sketched out two examples
Text files modified: 
   sandbox/xint/libs/xint/example/xint_fibonacci.cpp |   181 +++++++++++++++++++++++++++++++++++---- 
   sandbox/xint/libs/xint/example/xint_simple.cpp    |    61 +++++++++++-                            
   2 files changed, 212 insertions(+), 30 deletions(-)

Modified: sandbox/xint/libs/xint/example/xint_fibonacci.cpp
==============================================================================
--- sandbox/xint/libs/xint/example/xint_fibonacci.cpp	(original)
+++ sandbox/xint/libs/xint/example/xint_fibonacci.cpp	2010-04-01 07:56:18 EDT (Thu, 01 Apr 2010)
@@ -6,20 +6,22 @@
 // (See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 
-/** 
-\file     
-\brief Simple demo of xint sending the fibonacci sequence to stream output.
-\details
+/*! 
+  \file     
+  \brief Simple demo of xint sending the fibonacci sequence to stream output.
+  \details
 
-Fibonacci numbers are a sequence of numbers, starting with the numbers 0 and 1,
-where each successive number is the sum of the previous two.
+  Fibonacci numbers are a sequence of numbers, starting with the numbers 0 and 1,
+  where each successive number is the sum of the previous two.
+
+  http://en.wikipedia.org/wiki/Fibonacci_number 
 
 The first few Fibonacci numbers are:
 
     0 1 1 2 3 5 8 13 21 34 55 89 144...
 
 You might be curious what the first Fibonacci number is that's too big to calculate
-using the standard C++ unsigned long type. 
+using the standard C++ unsigned long int type. 
 A brute-force method of calculating this would be problematic, 
 since it might not be possible to tell when it overflows.
 But with the XInt library, it's child's play.
@@ -31,52 +33,189 @@
 -- except that an xint::integer won't overflow on you
 until you completely exhaust your system's memory. :-)
 
+  Output:
+  \verbatim
+ 
+0: 0
+1: 1
+2: 1
+3: 2
+4: 3
+5: 5
+6: 8
+7: 13
+8: 21
+9: 34
+10: 55
+11: 89
+12: 144
+13: 233
+14: 377
+15: 610
+16: 987
+17: 1597
+18: 2584
+19: 4181
+20: 6765
+21: 10946
+22: 17711
+23: 28657
+24: 46368
+25: 75025
+26: 121393
+27: 196418
+28: 317811
+29: 514229
+30: 832040
+31: 1346269
+32: 2178309
+33: 3524578
+34: 5702887
+35: 9227465
+36: 14930352
+37: 24157817
+38: 39088169
+39: 63245986
+40: 102334155
+41: 165580141
+42: 267914296
+43: 433494437
+44: 701408733
+45: 1134903170
+46: 1836311903
+47: 2971215073
+The 1st Fibonacci member > 4294967295 is number 48, with value 4807526976.
+
+  \endverbatim
+
+
 */
 #include <iostream>
 #include <limits>
 
 #include <boost/xint/xint.hpp>
+// <boost/xint.hpp> ???
 
-int main() {
+int main()
+{
     using xint::integer;
     using std::cout;
     using std::endl;
     using std::numeric_limits;
 
-//[xint_fibonacci_snippet_1
+/*
+    //[xint_fibonacci_snippet_1
 
-// Select our limit, in this case the largest number 
-// that will fit into an unsigned long:
-  integer limit=(std::numeric_limits<unsigned long>::max)();
+  [@http://en.wikipedia.org/wiki/Fibonacci_number  Fibonacci numbers]
+are a sequence of numbers, starting with the numbers 0 and 1,
+  where each successive number is the sum of the previous two.
+
+The first few Fibonacci numbers are:
+
+    0 1 1 2 3 5 8 13 21 34 55 89 144...
+
+You might be curious what the first Fibonacci number is that's too big to calculate
+using the standard C++ unsigned long int type. 
+A brute-force method of calculating this would be problematic, 
+since it might not be possible to tell when it overflows.
+But with the XInt library, it's child's play.
+
+If you're not intimately familiar with the Fibonacci sequence,
+and how fast the numbers in it grow, the answer might shock you.
+
+As you can see, using the XInt library is just like using the native integer types 
+-- except that an xint::integer won't overflow on you
+until you completely exhaust your system's memory. :-)
 
-  // Set the first two numbers in the sequence:
-  integer n, n1=0, n2=1;
 //] [xint_fibonacci_snippet_1]
+*/
+
+  // Select our limit, in this case the largest number 
+  // that will fit into an unsigned long:
+  integer limit = (std::numeric_limits<unsigned long>::max)();
+
+  // Set the first two numbers in the sequence:
+  integer n; //   (= 0 by default).
+  integer n1=0; // to hold the previous Fibonacci number.
+  integer n2=1; // to hold the new Fibonacci number.
+
 
     // Now count the items in the sequence as we iterate over them,
-    //  until we come to the first one greater than the limit we've set.
+    // until we come to the first one greater than the limit we've set.
     size_t counter=0;
     cout << counter++ << ": " << n1 << endl;
     cout << counter++ << ": " << n2 << endl;
 
-    while (true) {
-        n = n1 + n2;
+    while (true)
+    {
+        n = n1 + n2; // 
         if (n > limit) break;
         // That one didn't do it, go back for another try.
         cout << counter++ << ": " << n << endl;
 
-        n1=n2;
-        n2=n;
+        n1 = n2; 
+        n2 = n;
     }
+//[xint_fibonacci_snippet_2
+//` Finally we print the one that we could not compute using a unsigned long int.
+    cout << "The 1st Fibonacci member > " << limit << " is number " << counter << ", with value " << n << "." << endl;
+//] [xint_fibonacci_snippet_2]
 
-    cout << "The answer is " << counter << " (" << n << ")." << endl;
 } // int main()
 
 
 /*
 //[xint_fibonacci_output_1
 
-
+0: 0
+1: 1
+2: 1
+3: 2
+4: 3
+5: 5
+6: 8
+7: 13
+8: 21
+9: 34
+10: 55
+11: 89
+12: 144
+13: 233
+14: 377
+15: 610
+16: 987
+17: 1597
+18: 2584
+19: 4181
+20: 6765
+21: 10946
+22: 17711
+23: 28657
+24: 46368
+25: 75025
+26: 121393
+27: 196418
+28: 317811
+29: 514229
+30: 832040
+31: 1346269
+32: 2178309
+33: 3524578
+34: 5702887
+35: 9227465
+36: 14930352
+37: 24157817
+38: 39088169
+39: 63245986
+40: 102334155
+41: 165580141
+42: 267914296
+43: 433494437
+44: 701408733
+45: 1134903170
+46: 1836311903
+47: 2971215073
+The 1st Fibonacci member > 4294967295 is number 48, with value 4807526976.
 
 //] [xint_fibonacci_output_1]
 */

Modified: sandbox/xint/libs/xint/example/xint_simple.cpp
==============================================================================
--- sandbox/xint/libs/xint/example/xint_simple.cpp	(original)
+++ sandbox/xint/libs/xint/example/xint_simple.cpp	2010-04-01 07:56:18 EDT (Thu, 01 Apr 2010)
@@ -13,11 +13,31 @@
 Tests a few operators for output to a std:: stream.
 **/
 
+  // TODO I think you should get this into the boost namespace now or there will be zillions of places to change.
+  //using namespace boost::xint
+
+//[xint_simple_snippet_1
+/*`First we need an include to use Boost.Xint
+*/
 #include <boost/xint/xint.hpp>
 
+/*`It is also convenient to be able to write just 'integer',
+rather than tediously typing xint::integer,
+so in a main program, we can write simply
+  using namespace xint;
+
+but if the file is included by other programs, certain for .hpp files,
+this should be placed a local scope to avoid enforcing this on other code.
+
+Or you can explicitly declare which xint items you are using:
+*/
+  using xint::integer;
+//] [/xint_simple_snippet_1]
+
 #include <iostream>
 using std::cout;
 using std::endl;
+using std::hex;
 #include <iomanip>
 using std::setprecision;
 using std::setw;
@@ -25,22 +45,40 @@
 
 int main()
 {    
-  // TODO I think you should get this into the boost namespace now or there will be zillions of places to change.
-  //using namespace boost::xint
 
-  //using namespace xint;
+//[xint_simple_snippet_2
+
+/*`Some really unsurprising integer things we can do are:
+*/
   using xint::integer;
 
-//[xint_simple_snippet_1
+  integer a; // Construct a xint::integer, zero by default.
+  a++; // Try out an operator.
+  integer b(3);  // Construct with a given value of 3.
+  integer c = a + b; // Assign a sum.
+  cout << "a = " << a << ", b = " << b << ", a + b = " << c << endl;
+  // a = 1, b = 3, a + b = 4
+
+/*`But we can also just as easily do thing that Plain Old Integers can't.
+If we fill an integer using the max value for the type, and square it,
+it must overflow, and the value we get (without any warning) is just wrong.
+*/
+
+  long k= (std::numeric_limits<long>::max)();
+  cout << "k = " << k << ", k ^ 2 = " << k * k << endl; // Will overflow!
+  //   k = 2147483647, k ^ 2 = 1
 
-  xint::integer a;
-  integer b = 3;
 
-  integer c = a + b;
+/*`But if we use the extended integer, it does what we would expect
+(don't try this on your calculator either!)
+*/
+  integer xk =(std::numeric_limits<long>::max)();
+  cout << "xk ^ 2 = "<< xk * xk << endl; // xk ^ 2 = 4611686014132420609
 
-  cout << a << ", b = " << b << ", a + b = " << c << endl;
+/*`In hex it may be clearer:*/
+  cout << hex << "k = " << k << ", xk ^ 2 = "<< xk * xk << endl;
 
-//] [xint_simple_snippet_1]
+//] [xint_simple_snippet_2]
       return 0;
 } // int(main)
 
@@ -50,6 +88,11 @@
 //[xint_simple_output
 Output:
 
+a = 1, b = 3, a + b = 4
+k = 2147483647, k ^ 2 = 1
+xk ^ 2 = 4611686014132420609
+k = 7fffffff, xk ^ 2 = 3fffffff00000001
+
 
 //] [xint_simple_output]
 */