added big int lib

bigint/README

@@ -0,0 +1,92 @@
+The "bigint" Package
+====================
+
+1. What is it?
+--------------
+
+This package implements a multiple-precision integer arithmetic package,
+i.e., a collection of functions which can calculate with integers having
+arbitrarily many digits. The algorithms are taken from [D. Knuth: The
+Art of Computer Programming, Vol. 2, Seminumerical Algorithms], the
+implementation language is C.
+
+
+2. "Multiple Precision" - how does it work?
+-------------------------------------------
+
+Each integer number is represented as an array of digits. The array
+is large enough to hold the number of digits necessary to represent
+the number. Each digit occupies a single byte, so the number base of
+this representation is 256. Addition, subtraction, and multiplication
+work as we all have learned it: perform the desired operation digit
+by digit, starting from the least significant digit, and observing
+any "carries" from one place to the next higher one. Division is a
+little bit more complicated because there is a certain amount of
+guesswork involved. Knuth gives a formal treatment of this guesswork.
+
+
+3. How do I use it?
+-------------------
+
+Because every big integer may have a differently sized array to hold
+its digits, these structures are dynamically allocated on the heap of
+the C runtime system, and accessed by pointers. If you want to perform
+an arithmetic operation on one or two big integers, you have to load
+the corresponding pointers into a structure called BIP ("Big Integer
+Processor"), and call the arithmetic function. When the function has
+returned, the pointer to the result of the operation can be found in
+another component of the BIP. The following functions are available:
+
+    int bigSgn(void);                        /* sign */
+    int bigCmp(void);                        /* comparison */
+    void bigNeg(void);                       /* negation */
+    void bigAdd(void);                       /* addition */
+    void bigSub(void);                       /* subtraction */
+    void bigMul(void);                       /* multiplication */
+    void bigDiv(void);                       /* division */
+    void bigFromInt(int n);                  /* conversion int --> big */
+    int bigToInt(void);                      /* conversion big --> int */
+    void bigRead(FILE *in);                  /* read a big integer */
+    void bigPrint(FILE *out);                /* print a big integer */
+    void bigDump(FILE *out, BigObjRef bigObjRef);  /* dump a big integer */
+
+Some of these functions accept or return ordinary integers. For the
+exact definition of each function's interface, please see the comments
+in the function's source.
+
+
+4. What else is needed?
+-----------------------
+
+The library tries to detect fatal errors in using its functions (e.g.,
+null pointers to operands) as well as internal errors (which "cannot
+happen"). In either case a user-supplied error routine is called, which
+is supposed to print an error message and then to terminate the program.
+
+The library does not attempt to manage memory. For this purpose, it
+relies on a user-supplied function "void* newPrimObject(int dataSize)",
+which should allocate sufficiently many bytes and return a pointer to
+a created object. In addition, the library needs to access a data field
+- that implements the size-as-needed cocept - within the created object, 
+to actualy manage the data structures that represent the values of the 
+integer number. For this, the following function can be used:
+
+void * getPrimObjectDataPointer(void * obj){
+  ObjRef oo = ((ObjRef)  (obj));
+  return oo->data;
+}
+
+This function must also be a user-supplied function that must be 
+implemented by the program that wants to use this library.
+
+For details about these three user-supplied functions take a look in 
+the file "support.c" in the directory "tst".
+
+
+5. What is in the directory "tst"?
+----------------------------------
+
+Well, you may have guessed it already: these are test cases for the
+library. You can learn how to link against the library by inspecting
+the "Makefile" for the tests, and you can find a simple implementation
+of the support library.