library

Calc Software Package for Number Calc

	USING THE ARBITRARY PRECISION ROUTINES IN A C PROGRAM

Part of the calc release consists of an arbitrary precision math link library.
This link library is used by the calc program to perform its own calculations.
If you wish, you can ignore the calc program entirely and call the arbitrary
precision math routines from your own C programs.

The link library is called libcalc.a, and provides routines to handle arbitrary
precision arithmetic with integers, rational numbers, or complex numbers.
There are also many numeric functions such as factorial and gcd, along
with some transcendental functions such as sin and exp.

Take a look at the sample sub-directory.  It contains a few simple
examples of how to use libcalc.a that might be helpful to look at
after you have read this file.

------------------
FIRST THINGS FIRST
------------------

...............................................................................
.									      .
. You MUST call libcalc_call_me_first() prior to using libcalc lib functions! .
.									      .
...............................................................................

The function libcalc_call_me_first() takes no args and returns void.  You
need call libcalc_call_me_first() only once.

-------------
INCLUDE FILES
-------------

To use any of these routines in your own programs, you need to include the
appropriate include file.  These include files are:

	zmath.h		(for integer arithmetic)
	qmath.h		(for rational arithmetic)
	cmath.h		(for complex number arithmetic)

You never need to include more than one of the above files, even if you wish
to use more than one type of arithmetic, since qmath.h automatically includes
zmath.h, and cmath.h automatically includes qmath.h.

The prototypes for the available routines are listed in the above include
files.	Some of these routines are meant for internal use, and so aren't
convenient for outside use.  So you should read the source for a routine
to see if it really does what you think it does.  I won't guarantee that
obscure internal routines won't change or disappear in future releases!

When calc is installed, all of libraries are installed into ${LIBDIR}.
All of the calc header files are installed under ${INCDIRCALC}.

If CALC_SRC is defined, then the calc header files will assume that
they are in or under the current directory.  However, most external
programs most likely will not be located under calc'c source tree.
External programs most likely want to use the installed calc header
files under ${INCDIRCALC}.  External programs most likely NOT want
to define CALC_SRC.

External programs may want to compile with:

	-L${LIBDIR} -lcalc

If custom functions are also used, they may want to compile with:

	-L${LIBDIR} -lcalc -lcustcalc

The CALC_SRC symbol should NOT be defined by default.  However if you are
feeling pedantic you may want to force CALC_SRC to be undefined:

	-UCALC_SRC

as well.

--------------
ERROR HANDLING
--------------

Your program MUST provide a function called math_error.	 This is called by
the math routines on an error condition, such as malloc failures or a
division by zero.  The routine is called in the manner of printf, with a
format string and optional arguments.  (However, none of the low level math
routines currently uses formatting, so if you are lazy you can simply use
the first argument as a simple error string.)  For example, one of the
error calls you might expect to receive is:

	math_error("Division by zero");

Your program can handle errors in basically one of two ways.  Firstly, it
can simply print the error message and then exit.  Secondly, you can make
use of setjmp and longjmp in your program.  Use setjmp at some appropriate
level in your program, and use longjmp in the math_error routine to return
to that level and so recover from the error.  This is what the calc program
does.

For convenience, the link library libcalc.a contains a math_error routine.
By default, this routine simply prints a message to stderr and then exits.
By simply linking in this link library, any calc errors will result in a
error message on stderr followed by an exit.

External programs that wish to use this math_error may want to compile with:

	-I${LIBDIR} -L${LIBDIR} -lcalc

If one sets up calc_jmp_buf, and then sets calc_jmp to non-zero then
this routine will longjmp back (with the value of calc_jmp) instead.
In addition, the last calc error message will be found in calc_error;
this error is not printed to stderr.  The calc error message will
not have a trailing newline.

For example:

    #include <setjmp.h>

    extern jmp_buf calc_jmp_buf;
    extern int calc_jmp;
    extern char *calc_error;
    int error;

    ...

    if ((error = setjmp(calc_jmp_buf)) != 0) {

	    /* reinitialize calc after a longjmp */
	    reinitialize();

	    /* report the error */
	    printf("Ouch: %s\n", calc_error);
    }
    calc_jmp = 1;

---------------
OUTPUT ROUTINES
---------------

The output from the routines in the link library normally goes to stdout.  You
can divert that output to either another FILE handle, or else to a string.
Read the routines in zio.c to see what is available.  Diversions can be
nested.

You use math_setfp to divert output to another FILE handle.  Calling
math_setfp with stdout restores output to stdout.

Use math_divertio to begin diverting output into a string.  Calling
math_getdivertedio will then return a string containing the output, and
clears the diversion.  The string is reallocated as necessary, but since
it is in memory, there are obviously limits on the amount of data that can
be diverted into it.  The string needs freeing when you are done with it.

Calling math_cleardiversions will clear all the diversions to strings, and
is useful on an error condition to restore output to a known state.  You
should also call math_setfp on errors if you had changed that.

If you wish to mix your own output with numeric output from the math routines,
then you can call math_chr, math_str, math_fill, math_fmt, or math_flush.
These routines output single characters, output null-terminated strings,
output strings with space filling, output formatted strings like printf, and
flush the output.  Output from these routines is diverted as described above.

You can change the default output mode by calling math_setmode, and you can
change the default number of digits printed by calling math_setdigits.	These
routines return the previous values.  The possible modes are described in
zmath.h.

--------------
USING INTEGERS
--------------

The arbitrary precision integer routines define a structure called a ZVALUE.
This is defined in zmath.h.  A ZVALUE contains a pointer to an array of
integers, the length of the array, and a sign flag.  The array is allocated
using malloc, so you need to free this array when you are done with a
ZVALUE.	 To do this, you should call zfree with the ZVALUE as an argument
(or call freeh with the pointer as an argument) and never try to free the
array yourself using free.  The reason for this is that sometimes the pointer
points to one of two statically allocated arrays which should NOT be freed.

The ZVALUE structures are passed to routines by value, and are returned
through pointers.  For example, to multiply two small integers together,
you could do the following:

	ZVALUE	z1, z2, z3;

	itoz(3L, &z1);
	itoz(4L, &z2);
	zmul(z1, z2, &z3);

Use zcopy to copy one ZVALUE to another.  There is no sharing of arrays
between different ZVALUEs even if they have the same value, so you MUST
use this routine.  Simply assigning one value into another will cause
problems when one of the copies is freed.  However, the special ZVALUE
values _zero_ and _one_ CAN be assigned to variables directly, since their
values of 0 and 1 are so common that special checks are made for them.

For initial values besides 0 or 1, you need to call itoz to convert a long
value into a ZVALUE, as shown in the above example.  Or alternatively,
for larger numbers you can use the atoz routine to convert a string which
represents a number into a ZVALUE.  The string can be in decimal, octal,
hex, or binary according to the leading digits.

Always make sure you free a ZVALUE when you are done with it or when you
are about to overwrite an old ZVALUE with another value by passing its
address to a routine as a destination value, otherwise memory will be
lost.  The following shows an example of the correct way to free memory
over a long sequence of operations.

	ZVALUE z1, z2, z3;

	z1 = _one_;
	atoz("12345678987654321", &z2);
	zadd(z1, z2, &z3);
	zfree(z1);
	zfree(z2);
	zsquare(z3, &z1);
	zfree(z3);
	itoz(17L, &z2);
	zsub(z1, z2, &z3);
	zfree(z1);
	zfree(z2);
	zfree(z3);

There are some quick checks you can make on integers.  For example, whether
or not they are zero, negative, even, and so on.  These are all macros
defined in zmath.h, and should be used instead of checking the parts of the
ZVALUE yourself.  Examples of such checks are:

	ziseven(z)	(number is even)
	zisodd(z)	(number is odd)
	ziszero(z)	(number is zero)
	zisneg(z)	(number is negative)
	zispos(z)	(number is positive)
	zisunit(z)	(number is 1 or -1)
	zisone(z)	(number is 1)
	zisnegone(z)	(number is -1)
	zistwo(z)	(number is 2)
	zisabstwo(z)	(number is 2 or -2)
	zisabsleone(z)	(number is -1, 0 or 1)
	zislezero(z)	(number is <= 0)
	zisleone(z)	(number is <= 1)
	zge16b(z)	(number is >= 2^16)
	zge24b(z)	(number is >= 2^24)
	zge31b(z)	(number is >= 2^31)
	zge32b(z)	(number is >= 2^32)
	zge64b(z)	(number is >= 2^64)

Typically the largest unsigned long is typedefed to FULL.  The following
macros are useful in dealing with this data type:

	MAXFULL		(largest positive FULL value)
	MAXUFULL	(largest unsigned FULL value)