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.
