library

Calc Software Package for Number Calc

	zgtmaxfull(z)	(number is > MAXFULL)
	zgtmaxufull(z)	(number is > MAXUFULL)
	zgtmaxlong(z)	(number is > MAXLONG, largest long value)
	zgtmaxulong(z)	(number is > MAXULONG, largest unsigned long value)

If zgtmaxufull(z) is false, then one may quickly convert the absolute
value of number into a full with the macro:

	ztofull(z)	(convert abs(number) to FULL)
	ztoulong(z)	(convert abs(number) to an unsigned long)
	ztolong(z)	(convert abs(number) to a long)

If the value is too large for ztofull(), ztoulong() or ztolong(), only
the low order bits converted.

There are two types of comparisons you can make on ZVALUEs.  This is whether
or not they are equal, or the ordering on size of the numbers.	The zcmp
function tests whether two ZVALUEs are equal, returning TRUE if they differ.
The zrel function tests the relative sizes of two ZVALUEs, returning -1 if
the first one is smaller, 0 if they are the same, and 1 if the first one
is larger.

---------------
USING FRACTIONS
---------------

The arbitrary precision fractional routines define a structure called NUMBER.
This is defined in qmath.h.  A NUMBER contains two ZVALUEs for the numerator
and denominator of a fraction, and a count of the number of uses there are
for this NUMBER.  The numerator and denominator are always in lowest terms,
and the sign of the number is contained in the numerator.  The denominator
is always positive.  If the NUMBER is an integer, the denominator has the
value 1.

Unlike ZVALUEs, NUMBERs are passed using pointers, and pointers to them are
returned by functions.	So the basic type for using fractions is not really
(NUMBER), but is (NUMBER *).  NUMBERs are allocated using the qalloc routine.
This returns a pointer to a number which has the value 1.  Because of the
special property of a ZVALUE of 1, the numerator and denominator of this
returned value can simply be overwritten with new ZVALUEs without needing
to free them first.  The following illustrates this:

	NUMBER *q;

	q = qalloc();
	itoz(55L, &q->num);

A better way to create NUMBERs with particular values is to use the itoq,
iitoq, or atoq functions.  Using itoq makes a long value into a NUMBER,
using iitoq makes a pair of longs into the numerator and denominator of a
NUMBER (reducing them first if needed), and atoq converts a string representing
a number into the corresponding NUMBER.	 The atoq function accepts input in
integral, fractional, real, or exponential formats.  Examples of allocating
numbers are:

	NUMBER *q1, *q2, *q3;

	q1 = itoq(66L);
	q2 = iitoq(2L, 3L);
	q3 = atoq("456.78");

Also unlike ZVALUEs, NUMBERs are quickly copied.  This is because they contain
a link count, which is the number of pointers there are to the NUMBER.	The
qlink macro is used to copy a pointer to a NUMBER, and simply increments
the link count and returns the same pointer.  Since it is a macro, the
argument should not be a function call, but a real pointer variable.  The
qcopy routine will actually make a new copy of a NUMBER, with a new link
count of 1.  This is not usually needed.

NUMBERs are deleted using the qfree routine.  This decrements the link count
in the NUMBER, and if it reaches zero, then it will deallocate both of
the ZVALUEs contained within the NUMBER, and then puts the NUMBER structure
onto a free list for quick reuse.  The following is an example of allocating
NUMBERs, copying them, adding them, and finally deleting them again.

	NUMBER *q1, *q2, *q3;

	q1 = itoq(111L);
	q2 = qlink(q1);
	q3 = qqadd(q1, q2);
	qfree(q1);
	qfree(q2);
	qfree(q3);

Because of the passing of pointers and the ability to copy numbers easily,
you might wish to use the rational number routines even for integral
calculations.  They might be slightly slower than the raw integral routines,
but are more convenient to program with.

The prototypes for the fractional routines are defined in qmath.h.
Many of the definitions for integer functions parallel the ones defined
in zmath.h.  But there are also functions used only for fractions.
Examples of these are qnum to return the numerator, qden to return the
denominator, qint to return the integer part of, qfrac to return the
fractional part of, and qinv to invert a fraction.

There are some transcendental functions in the link library, such as sin
and cos.  These cannot be evaluated exactly as fractions.  Therefore,
they accept another argument which tells how accurate you want the result.
This is an "epsilon" value, and the returned value will be within that
quantity of the correct value.	This is usually an absolute difference,
but for some functions (such as exp), this is a relative difference.
For example, to calculate sin(0.5) to 100 decimal places, you could do:

	NUMBER *q, *ans, *epsilon;

	q = atoq("0.5");
	epsilon = atoq("1e-100");
	ans = qsin(q, epsilon);

There are many convenience macros similar to the ones for ZVALUEs which can
give quick information about NUMBERs.  In addition, there are some new ones
applicable to fractions.  These are all defined in qmath.h.  Some of these
macros are:

	qiszero(q)	(number is zero)
	qisneg(q)	(number is negative)
	qispos(q)	(number is positive)
	qisint(q)	(number is an integer)
	qisfrac(q)	(number is fractional)
	qisunit(q)	(number is 1 or -1)
	qisone(q)	(number is 1)
	qisnegone(q)	(number is -1)
	qistwo(q)	(number is 2)
	qiseven(q)	(number is an even integer)
	qisodd(q)	(number is an odd integer)
	qistwopower(q)	(number is a power of 2 >= 1)

The comparisons for NUMBERs are similar to the ones for ZVALUEs.  You use the
qcmp and qrel functions.

There are four predefined values for fractions.	 You should qlink them when
you want to use them.  These are _qzero_, _qone_, _qnegone_, and _qonehalf_.
These have the values 0, 1, -1, and 1/2.  An example of using them is:

	NUMBER *q1, *q2;

	q1 = qlink(&_qonehalf_);
	q2 = qlink(&_qone_);

---------------------
USING COMPLEX NUMBERS
---------------------

The arbitrary precision complex arithmetic routines define a structure
called COMPLEX.	 This is defined in cmath.h.  This contains two NUMBERs
for the real and imaginary parts of a complex number, and a count of the
number of links there are to this COMPLEX number.

The complex number routines work similarly to the fractional routines.
You can allocate a COMPLEX structure using comalloc (NOT calloc!).
You can construct a COMPLEX number with desired real and imaginary
fractional parts using qqtoc.  You can copy COMPLEX values using clink
which increments the link count.  And you free a COMPLEX value using cfree.
The following example illustrates this:

	NUMBER *q1, *q2;
	COMPLEX *c1, *c2, *c3;

	q1 = itoq(3L);
	q2 = itoq(4L);
	c1 = qqtoc(q1, q2);
	qfree(q1);
	qfree(q2);
	c2 = clink(c1);
	c3 = cmul(c1, c2);
	cfree(c1);
	cfree(c2);
	cfree(c3);

As a shortcut, when you want to manipulate a COMPLEX value by a real value,
you can use the caddq, csubq, cmulq, and cdivq routines.  These accept one
COMPLEX value and one NUMBER value, and produce a COMPLEX value.

There is no direct routine to convert a string value into a COMPLEX value.
But you can do this yourself by converting two strings into two NUMBERS,
and then using the qqtoc routine.

COMPLEX values are always returned from these routines.	 To split out the
real and imaginary parts into normal NUMBERs, you can simply qlink the
two components, as shown in the following example:

	COMPLEX *c;
	NUMBER *rp, *ip;

	c = calloc();
	rp = qlink(c->real);
	ip = qlink(c->imag);

There are many macros for checking quick things about complex numbers,
similar to the ZVALUE and NUMBER macros.  In addition, there are some
only used for complex numbers.	Examples of macros are:

	cisreal(c)	(number is real)
	cisimag(c)	(number is pure imaginary)
	ciszero(c)	(number is zero)
	cisnegone(c)	(number is -1)
	cisone(c)	(number is 1)
	cisrunit(c)	(number is 1 or -1)
	cisiunit(c)	(number is i or -i)
	cisunit(c)	(number is 1, -1, i, or -i)
	cistwo(c)	(number is 2)
	cisint(c)	(number is has integer real and imaginary parts)
	ciseven(c)	(number is has even real and imaginary parts)
	cisodd(c)	(number is has odd real and imaginary parts)

There is only one comparison you can make for COMPLEX values, and that is
for equality.  The ccmp function returns TRUE if two complex numbers differ.

There are three predefined values for complex numbers.	You should clink
them when you want to use them.	 They are _czero_, _cone_, and _conei_.
These have the values 0, 1, and i.

----------------
LAST THINGS LAST
----------------

If you wish, when you are all doen you can call libcalc_call_me_last()
to free a small amount of storage associated with the libcalc_call_me_first()
call.  This is not required, but is does bring things to a closure.

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

## Copyright (C) 1999  David I. Bell and Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA.
##
## @(#) $Revision: 29.5 $
## @(#) $Id: LIBRARY,v 29.5 2001/06/08 22:57:35 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/RCS/LIBRARY,v $
##
## Under source code control:	1993/07/30 19:44:49
## File existed as early as:	1993
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/