X-Git-Url: https://mattmccutchen.net/bigint/bigint.git/blobdiff_plain/05780f4b578d6ae054be0b19b8498d32a4f16c60..26a5f52b24d9c9733139a6cf29647f1de7915a56:/sample.cc

diff --git a/sample.cc b/sample.cc
index 58023a6..5344781 100644
--- a/sample.cc
+++ b/sample.cc
@@ -1,42 +1,46 @@
 /*
 * Matt McCutchen's Big Integer Library
-* http://mysite.verizon.net/mccutchen/bigint/
 */
 
 /*
-* This sample file demonstrates the most important features of the Big Integer Library.
+* This sample program demonstrates the most important features of the Big Integer Library.
+* To get started quickly, read the code and explanations below.  Then try the program out.
 *
-* To get started quickly with the library, imitate the code in `main' below.
-*
-* If you want more detail or more speed or can't find a feature here,
-* look in the appropriate source file.  This file shows only the more ``user-friendly'' features;
+* If you want more detail or more speed or can't find a feature here, look in the
+* appropriate source file.  This file shows only the more ``user-friendly'' features;
 * the other features are messier but worth learning eventually.
 *
 * GO FORTH and play with many-digit numbers!  (c.f. The TeXbook.)
 */
 
-#include "BigUnsigned.hh"
-#include "BigInteger.hh"
-#include "BigIntegerUtils.hh"
-
+// Standard libraries
 #include <string>
 #include <iostream>
 
+// For the BigInteger class itself.
+#include "BigInteger.hh"
+
+// For the 4 routines `easy BI/BU <=> string' and `iostream' integration.
+#include "BigIntegerUtils.hh"
+
 int main() {
 	try {
+		std::cout << "=====\nBig Integer Library Demonstration" << std::endl;
+		
 		BigInteger a; // a is 0
 		int b = 535;
 		
-		a = b; // From int to BigUnsigned...
+		a = b; // From int to BigInteger...
 		b = a; // ...and back, no casts required!
 		/*
 		* If a were too big for an int you'd get a runtime exception.  The Big Integer Library
 		* throws C-strings (that is, `const char *'s) when something goes wrong.  It's a good
-		* idea to catch them.  Some C++ compilers need a special command-line option to compile
-		* code that uses throw/catch.
+		* idea to catch them; the `try/catch' construct wrapping all this code is an example
+		* of how to do this.  Some C++ compilers need a special command-line option to compile
+		* code that uses exceptions.
 		*/
 		
-		BigInteger c(a); // Copy them.
+		BigInteger c(a); // Copy a BigInteger.
 		
 		BigInteger d(-314159265); // c is -314159265.  The `int' literal is converted to a BigInteger.
 		
@@ -55,43 +59,30 @@ int main() {
 		/*
 		* Let's do some math!
 		*
-		* The Big Integer Library provides three kinds of operators:
-		*
-		* (1) Overloaded ``value'' operators: +, -, *, /, %, unary -.
-		* Big-integer code using these operators looks identical to
-		* code using the primitive integer types.  The operator takes
-		* one or two BigInteger inputs and returns a BigInteger result,
-		* which can then be assigned to a BigInteger variable or used
-		* in an expression.
-		*
-		* (2) Overloaded assignment operators: +=, -=, *=, /=, %=,
-		*     ++, --, flipSign.
-		* Again, these are used on BigIntegers just like on ints.
-		* They take one writable BigInteger that both provides an
-		* operand and receives a result.  The first five also take
-		* a second read-only operand.
-		*
-		* (3) ``Put-here'' operations: `add', `subtract', etc.
-		* Use these if and only if you are concerned about performance.
-		* They require fewer BigInteger copy-constructions and assignments
-		* than do operators in (1) or (2).  Most take two read-only operands
-		* and save the result in the invoked object `*this', whose previous
-		* value is irrelevant.  `divideWithRemainder' is an exception.
-		* <<< NOTE >>>: Put-here operations do not return a value: they don't need to!!
+		* The Big Integer Library provides lots of overloaded operators
+		* and corresponding assignment operators.  So you can do `a + b'
+		* with big integers just as with normal integers.  The named
+		* methods `add', `divideWithRemainder', etc. are more advanced
+		* ``put-here operations''; see `BigUnsigned.hh' for details.
 		*/
-		
 		BigInteger g(314159), h(265);
-		// All five ``value'' operators
+		// All five ``return-by-value'' operators.
 		std::cout << (g + h) << '\n' << (g - h) << '\n' << (g * h)
 			<< '\n' << (g / h) << '\n' << (g % h) << std::endl;
 		
-		BigInteger i(5), j(10), k;
-		// These two lines do the same thing: k is set to a BigInteger containing 15.
-		k = i + j;
-		k.add(i, j);
+		std::cout << "=====\nTest code" << std::endl;
+		
+		/*
+		* If you want to experiment with the library,
+		* put your own test code here.
+		*/
+		
+		/*
+		* (End of test code)
+		*/
 		
 		// Let's do some heavy lifting.
-		std::cout << "Powers of 3" << std::endl;
+		std::cout << "=====\nPowers of 3" << std::endl;
 		std::cout << "How many do you want?" << std::endl;
 		int maxPower;
 		std::cin >> maxPower;
@@ -102,12 +93,13 @@ int main() {
 			x *= three; // A BigInteger assignment operator
 		}
 		
-		std::cout << "There you go.  Goodbye." << std::endl;
+		std::cout << "There you go.  Goodbye.\n=====" << std::endl;
 		
-	} catch(char const* err){
-		std::cout << "Sorry, the library threw an exception:\n"
+	} catch(char const* err) {
+		std::cout << "=====\nSorry, the library threw an exception:\n"
 			<< err << std::endl;
 	}
+	
 	return 0;
 }