unction, the specified
	    variable must already be defined, and is just converted to
	    a matrix of the specified size, and all elements are set
	    to the value of zero.  For convenience, at the top level
	    command level, the MAT command automatically defines a
	    global variable of the specified name if necessary.

	    Since the MAT statement is executed, the bounds on the
	    matrix can be full expressions, and so matrices can be
	    dynamically allocated.  For example:

		    size = 20;
		    mat data[size*2];

	    allocates a matrix which can be indexed from 0 to 39.

	    Initial values for the elements of a matrix can be specified
	    by following the bounds information with an equals sign and
	    then a list of values enclosed in a pair of braces.	 Even if
	    the matrix has more than one dimension, the elements must be
	    specified as a linear list.	 If too few values are specified,
	    the remaining values are set to zero.  If too many values are
	    specified, a runtime error will result.  Examples of some
	    initializations are:

		    mat table1[5] = {77, 44, 22};
		    mat table2[2,2] = {1, 2, 3, 4};

	    When an initialization is done, the bounds of the matrix
	    can optionally be left out of the square brackets, and the
	    correct bounds (zero based) will be set.  This can only be
	    done for one-dimensional matrices.	An example of this is:

		    mat fred[] = {99, 98, 97};

	    The MAT statement can also be used in declarations to set
	    variables as being matrices from the beginning.  For example:

		    local mat temp[5];
		    static mat strtable[] = {"hi", "there", "folks");


    object
    ------
    obj type { elementnames } optionalvariables
    obj type variable
	    These create a new object type, or create one or more
	    variables of the specified type.  For this calculator,
	    an object is just a structure which is implicitly acted
	    on by user defined routines.  The user defined routines
	    implement common operations for the object, such as plus
	    and minus, multiply and divide, comparison and printing.
	    The calculator will automatically call these routines in
	    order to perform many operations.

	    To create an object type, the data elements used in
	    implementing the object are specified within a pair
	    of braces, separated with commas.  For example, to
	    define an object will will represent points in 3-space,
	    whose elements are the three coordinate values, the
	    following could be used:

		    obj point {x, y, z};

	    This defines an object type called point, whose elements
	    have the names x, y, and z.	 The elements are accessed
	    similarly to structure element accesses, by using a period.
	    For example, given a variable 'v' which is a point object,
	    the three coordinates of the point can be referenced by:

		    v.x
		    v.y
		    v.z

	    A particular object type can only be defined once, and
	    is global throughout all functions.	 However, different
	    object types can be used at the same time.

	    In order to create variables of an object type, they
	    can either be named after the right brace of the object
	    creation statement, or else can be defined later with
	    another obj statement.  To create two points using the
	    second (and most common) method, the following is used:

		    obj point p1, p2;

	    This statement is executed, and is not a declaration.
	    Thus within a function, the variables p1 and p2 must have
	    been previously defined, and are just changed to be the
	    new object type.  For convenience, at the top level command
	    level, object variables are automatically defined as being
	    global when necessary.

	    Initial values for an object can be specified by following
	    the variable name by an equals sign and a list of values
	    enclosed in a pair of braces.  For example:

		    obj point pt = {5, 6};

	    The OBJ statement can also be used in declarations to set
	    variables as being objects from the beginning.  If multiple
	    variables are specified, then each one is defined as the
	    specified object type.  Examples of declarations are:

		    local obj point temp1;
		    static obj point temp2 = {4, 3};
		    global obj point p1, p2, p3;


    print expressions
    -----------------
    print expr
    print expr, ... expr
    print expr: ... expr
	    For interactive expression evaluation, the values of all
	    typed-in expressions are automatically displayed to the
	    user.  However, within a function or loop, the printing of
	    results must be done explicitly.  This can be done using
	    the 'printf' or 'fprintf' functions, as in standard C, or
	    else by using the built-in 'print' statement.  The advantage
	    of the print statement is that a format string is not needed.
	    Instead, the given values are simply printed with zero or one
	    spaces between each value.

	    Print accepts a list of expressions, separated either by
	    commas or colons.  Each expression is evaluated in order
	    and printed, with no other output, except for the following
	    special cases.  The comma which separates expressions prints
	    a single space, and a newline is printed after the last
	    expression unless the statement ends with a colon.	As
	    examples:

		    print 3, 4;			prints "3 4" and newline.
		    print 5:;			prints "5" with no newline.
		    print 'a' : 'b' , 'c';	prints "ab c" and newline.
		    print;			prints a newline.

	    For numeric values, the format of the number depends on the
	    current "mode" configuration parameter.  The initial mode
	    is to print real numbers, but it can be changed to other
	    modes such as exponential, decimal fractions, or hex.

	    If a matrix or list is printed, then the elements contained
	    within the matrix or list will also be printed, up to the
	    maximum number specified by the "maxprint" configuration
	    parameter.	If an element is also a matrix or a list, then
	    their values are not recursively printed.  Objects are printed
	    using their user-defined routine.  Printing a file value
	    prints the name of the file that was opened.


    Also see the help topic:

	    help command	top level commands
	    help expression	calc expression syntax
	    help builtin	calc builtin functions
	    help usage	    	how to invoke the calc command and calc -options

    You may obtain help on individual builtin functions.  For example:

	    help asinh
	    help round

    See:
    	    help builtin

    for a list of builtin functions.

    Some calc operators have their own help pages:

	    help ->
	    help *
	    help .
	    help %
	    help //
	    help #

    See also:

	    help help


## Copyright (C) 1999-2007  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: statement,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/statement,v $
##
## Under source code control:	1991/07/21 04:37:23
## File existed as early as:	1991
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    freebernoulli - free stored Bernoulli numbers

SYNOPSIS
    freebernoulli()

TYPES
    return	none

DESCRIPTION
    The memory used to store calculated bernoulli numbers is freed by
    freebernoulli().

EXAMPLE
    ; freebernoulli();

LIMITS
    none

LINK LIBRARY
    void qfreebern(void);

SEE ALSO
    bernoulli

## Copyright (C) 2000  Ernest Bowen
##
## 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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: freebernoulli,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/freebernoulli,v $
##
## Under source code control:	2000/07/13
## File existed as early as:	2000
##
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    errcount - return or set the internal error count

SYNOPSIS
    errcount([num])

TYPES
    num		integer

    return	integer

DESCRIPTION
    An internal variable keeps count of the number of functions
    evaluating to an error value either internally or by a call to
    error() or newerror().

    The errcount() with no args returns the current error count.  Calling
    errcount(num) returns the current error count and resets it to num.

    If the count exceeds the current value of errmax, execution is aborted
    with a message displaying the errno for the error.

    If an error value is assigned to a variable as in:

			infty = 1/0;

    then a function returning that variable does not contribute to
    errcount.

EXAMPLE
    ; errmax(10)
	    0
    ; errcount()
	    0
    ; a = 1/0; b = 2 + ""; c = error(27); d = newerror("a");
    ; print errcount(), a, errcount(), errmax();
    4 Error 10001 4 10

LIMITS
    0 <= num < 2^32

LINK LIBRARY
    none

SEE ALSO
    errmax, error, strerror, iserror, errno, newerror, errorcodes,
    stoponerror

## Copyright (C) 1999-2006  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: errcount,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/errcount,v $
##
## Under source code control:	1997/03/08 08:51:14
## File existed as early as:	1997
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������We welcome and encourage you to send us:

    * calc resource files
    * calc shell scripts
    * any builtin functions that you have modified or written
    * custom functions that you have modified or written
    * any other source code modifications

Prior to doing so, you should consider applying your changes to the most
recent version of calc.

Landon Noll maintains the official calc home page at:

	http://www.isthe.com/chongo/tech/comp/calc/

See:

	http://www.isthe.com/chongo/tech/comp/calc/calc-download.html

for information on how to obtain up a recent version of calc.

=-=

In order to consider integrating your code, we need:

    * the calc version you are working with (use the latest calc, see above)
    * new help files or help file patches, if applicable (documentation)
    * proposed text for the CHANGES file (brief description of what it does)
    * regress.cal test patch, if applicable
    * your source code and/or source code changes (:-))

The best way to send us new code, if your changes are small, is
via a patch (diff -c from the latest alpha code to your code).
If your change is large, you should send entire files (either
as a diff -c /dev/null your-file patch, or as a uuencoded and
gziped (or compressed) tar file).

To contribute code, scripts, resource files and/or to help please
join the low volume calc mailing list by sending EMail to:

    calc-contrib at asthe dot com

    [[ NOTE: Replace 'at' with @, 'dot' is with . and remove the spaces ]]
    [[ NOTE: The EMail address uses 'asthe' and the web site URL uses 'isthe' ]]

Your subject must contain the words:

    calc mailing list subscription

You may have additional words in your subject line.

Feel free to follow the name line with additional EMail text as desired.

Thanks for considering submitting code to calc.	 Calc is a collective
work by a number of people.  It would not be what it is today without
your efforts and submissions!

=-=

Calc bug reports and calc bug fixes should be sent to:

    calc-bugs at asthe dot com

    [[ NOTE: Replace 'at' with @, 'dot' is with . and remove the spaces ]]
    [[ NOTE: The EMail address uses 'asthe' and the web site URL uses 'isthe' ]]

Your subject must contain the words:

       calc bug report

You may have additional words in your subject line.

See the BUGS file or try the help command:

    help bugs

for details on bug reporting.

=-=

Landon Curt Noll
http://www.isthe.com/chongo/

chongo (share and enjoy) /\../\

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: contrib,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/contrib,v $
##
## Under source code control:	1997/03/09 16:33:22
## File existed as early as:	1997
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    iroot - integer part of specified root

SYNOPSIS
    iroot(x, n)

TYPES
    x		nonnegative real
    n		positive integer

    return	nonnegative real

DESCRIPTION
    Return the greatest integer v for which v^n <= x.

EXAMPLE
    ; print iroot(100,3), iroot(274,3), iroot(1,9), iroot(pi()^8,5)
    4 6 1 6

LIMITS
    n > 0

LINK LIBRARY
    NUMBER *qiroot(NUMBER *x, NUMBER* n)

SEE ALSO
    isqrt, sqrt

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: iroot,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/iroot,v $
##
## Under source code control:	1995/10/25 04:03:45
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    root - root of a number

SYNOPSIS
    root(x, n, [, eps])

TYPES
    x		number
    n		positive integer
    eps		nonzero real, defaults to epsilon()

    return	real number

DESCRIPTION
    For real x and positive integer n, n being odd if x is negative,
    root(x,n,eps) returns a multiple of eps differing from the
    real n-th root of x (nonnegative if x is positive) by less than
    0.75 eps, usually by less than 0.5 eps.  If the n-th root of
    x is a multiple of eps, it will be returned exactly.

    For complex x and positive integer n, or negative x with positive even
    n, root(x, n, eps) returns a real or complex numbers whose real
    and imaginary parts are multiples of eps differing from the real
    and imaginary parts of the principal n-th root of x by less than
    0.75 eps, usually by less than 0.5 eps.

    For negative x and odd n, the principal n-th root of x may be
    obtained by using power(x, 1/n, eps).

EXAMPLE
    ; print root(7, 4, 1e-5), root(7, 4, 1e-10), root(7, 4, 1e-15)
    1.62658 1.6265765617 1.626576561697786

    ; print root(1+3i, 3, 1e-5), root(1 + 3i, 3, 1e-10)
    1.34241+.59361i 1.3424077452+.5936127825i

    ; print root(-8, 3, 1e-5), root(-8, 34, 1e-5)
    -2 ~1.05853505050032399594+~.09807874962631613016i

    ; print root(1i, 100, 1e-20)
    .99987663248166059864+.01570731731182067575i

LIMITS
    n >= 0
    eps > 0

LINK LIBRARY
    void rootvalue(VALUE *x, VALUE *n, VALUE *eps, VALUE *result)
    NUMBER *qroot(NUMBER *x, NUMBER *n, NUMBER *eps)
    COMPLEX *c_root(COMPLEX *x, NUMBER *n, NUMBER *eps)

SEE ALSO
    power

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: root,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/root,v $
##
## Under source code control:	1995/10/25 04:03:46
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    avg - average (arithmetic) mean of values

SYNOPSIS
    avg(x_1, x_2, ...)

TYPES
    x_1, ...	arithmetic or list

    return	as determined by types of items averaged

DESCRIPTION
    If there are n non-list arguments x_1, x_2, ..., x_n,
    for which the required additions and division by n are defined,
    avg(x_1, x_2, ..., x_n) returns the value of:

	(x_1 + x_2 + ... + x_n)/n.

    If the x_i are real, the result will be a real number; if the
    x_i are real or complex numbers, the result will be a real or complex
    number.  If the x_i are summable matrices the result will be a matrix
    of the same size (e.g. if the x_i are all 3 x 4 matrices with real
    entries, the result will be a 3 x 4 matrix with real entries).

    If an argument x_i is list-valued, e.g. list(y_1, y_2, ...), this
    is treated as contributing y_1, y_2, ... to the list of items to
    be averaged.

EXAMPLE
    ; print avg(1,2,3,4,5), avg(list(1,2,3,4,5)), avg(1,2,list(3,4,5))
    3 3 3

    ; mat x[2,2] = {1,2,3,4}
    ; mat y[2,2] = {1,2,4,8}
    ; avg(x,y)

    mat [2,2] (4 elements, 4 nonzero):
      [0,0] = 1
      [0,1] = 2
      [1,0] = 3.5
      [1,1] = 6

LIMITS
   The number of arguments is not to exceed 1024.

LINK LIBRARY
    none

SEE ALSO
    hmean

## Copyright (C) 1999-2006  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: avg,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/avg,v $
##
## Under source code control:	1994/09/25 20:22:31
## File existed as early as:	1994
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    usertime - user CPU time used by the current process

SYNOPSIS
    usertime()

TYPES
    return	nonnegative real

DESCRIPTION
    In POSIX based systems, this function will return the CPU seconds
    used by the current process while in user mode.  Time spent in the
    kernel executing system calls is not included.

    On non-POSIX based systems, this function will always return 0.
    In particular, most MS windows based systems do not have the required
    POSIX system call and so this function will always return 0.

EXAMPLE
    The result for this example will depend on the speed of the CPU
    and precision of the operating CPU time accounting sub-system:

    ; t = usertime();
    ; x = ptest(2^4253-1);
    ; usertime() - t;
	1.287804

LIMITS
    On non-POSIX based systems, this function always returns 0.

LINK LIBRARY
    none

SEE ALSO
    config, ctime, usertime, systime, time

## Copyright (C) 2006  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: usertime,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/usertime,v $
##
## Under source code control:	2006/12/16 10:31:08
## File existed as early as:	2006
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    join - form a list by concatenation of specified lists

SYNOPSIS
    join(x, y, ...)

TYPES
    x, y, ...	lists

    return	list or null

DESCRIPTION
    For lists x, y, ..., join(x, y, ...) returns the list whose length
    is the sum of the lengths of x, y, ..., in which the members of each
    argument immediately follow those of the preceding argument.
    The lists x, y, ... are not changed.

    If any argument is not a list, a null value is returned.

EXAMPLE
    ; A = list(1, 2, 3)
    ; B = list(4, 5)
    ; join(A, B)

    list (5 elements, 5 nonzero):
	  [[0]] = 1
	  [[1]] = 2
	  [[2]] = 3
	  [[3]] = 4
	  [[4]] = 5

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    reverse, sort

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: join,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/join,v $
##
## Under source code control:	1995/07/09 19:41:40
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    blkcpy, copy - copy items from a structure to a structure

SYNOPSIS
    blkcpy(dst, src [, num [, dsi [, ssi]]]
    copy(src, dest [, [ssi [, num [, dsi]]])

TYPES
    src		block, file, string, matrix, or list
    dest	block, file, matrix or list - compatible with src

    ssi		nonnegative integer, defaults to zero
    num		nonnegative integer, defaults to maximum possible
    dsi		nonnegative integer, defaults to datalen for a block, filepos
			for a file, zero for other structures

    return	null if successful, error value otherwise

DESCRIPTION
    A call to:

	blkcpy(dst, src, num, dsi, ssi)

    attempts to copy 'num' consecutive items (octets or values) starting
    from the source item 'src' with index 'ssi'.  By default, 'num'
    is the maximum possible and 'ssi' is 0.

    A call to:

	copy(src, dst, ssi, num, dsi)

    does the same thing, but with a different arg order.

    A copy fails if ssi or num is too large for the number of items in
    the source, if sdi is too large for the number of positions
    available in the destination, or, in cases involving a file stream,
    if the file is not open in the required mode.  The source and
    destination need not be of the same type, e.g. when a block is
    copied to a matrix the octets are converted to numbers.

    The following pairs of source-type, destination-type are permitted:

	block to
		 int
		 block
		 matrix
		 file

	matrix to
		 block
		 matrix
		 list

	string to
		 block
		 file

	list to
		 list
		 matrix

	file to
		 block

	int to
		 block

    In the above table, int refers to integer values.  However if a
    rational value is supplied, only the numerator is copied.

    Each copied octet or value replaces the octet or value in the
    corresponding place in the destination structure.  When copying values
    to values, the new values are stored in a buffer, the old values are
    removed, and the new values copied from the buffer to the destination.
    This permits movement of data within one matrix or list, and copying
    of an element of structure to the structure.

    Except for copying to files or blocks, the destination is already to have
    sufficient memory allocated for the copying.  For example, to copy
    a matrix M of size 100 to a newly created list, one may use:

	; L = makelist(100);
	; copy(M, L);
   or:
	; L = makelist(100);
	; blkcpy(L, M);

    For copying from a block B (named or unnamed), the total number of octets
    available for copying is taken to the the datalen for that block,
    so that num can be at most size(B) - ssi.

    For copying to a block B (named or unnamed), reallocation will be
    required if dsi + num > sizeof(B).	(This will not be permitted if
    protect(B) has bit 4 set.)

    For copying from a file stream fs, num can be at most size(fs) - ssi.

    For copying from a string str, the string is taken to include the
    terminating '\0', so the total number of octets available is
    strlen(str) + 1 and num can be at most strlen(str) + 1 - ssi.
    If num <= strlen(str) - ssi, the '\0' is not copied.

    For copying from or to a matrix M, the total number of values in
    M is size(M), so in the source case, num <= size(M) - ssi, and
    in the destination case, num <= size(M) - dsi.  The indices ssi
    and dsi refer to the double-bracket method of indexing, i.e. the
    matrix is as if its elements were indexed 0, 1, ..., size(M) - 1.


EXAMPLE
    ; A = blk() = {1,2,3,4}
    ; B = blk()
    ; blkcpy(B,A)
    ; B
	chunksize = 256, maxsize = 256, datalen = 4
	01020304
    ; blkcpy(B,A)
    ; B
	chunksize = 256, maxsize = 256, datalen = 8
	0102030401020304
    ; blkcpy(B, A, 2, 10)
    ; B
	chunksize = 256, maxsize = 256, datalen = 12
	010203040102030400000102
    ; blkcpy(B,32767)
    ; B
	chunksize = 256, maxsize = 256, datalen = 16
	010203040102030400000102ff7f0000
    ; mat M[2,2]
    ; blkcpy(M, A)
    ; M
	mat [2,2] (4 elements, 4 nonzero):
	  [0,0] = 1
	  [0,1] = 2
	  [1,0] = 3
	  [1,1] = 4
    ; blkcpy(M, A, 2, 2)
    ; M
	mat [2,2] (4 elements, 4 nonzero):
	  [0,0] = 1
	  [0,1] = 2
	  [1,0] = 1
	  [1,1] = 2

    ; A = blk() = {1,2,3,4}
    ; B = blk()
    ; copy(A,B)
    ; B
	chunksize = 256, maxsize = 256, datalen = 4
	01020304
    ; copy(A,B)
    ; B
	chunksize = 256, maxsize = 256, datalen = 8
	0102030401020304
    ; copy(A,B,1,2)
    ; B
	chunksize = 256, maxsize = 256, datalen = 10
	01020304010203040203
    ; mat M[2,2]
    ; copy(A,M)
    ; M
	mat [2,2] (4 elements, 4 nonzero):
	  [0,0] = 1
	  [0,1] = 2
	  [1,0] = 3
	  [1,1] = 4

    ; copy(A,M,2)
    ; M
	mat [2,2] (4 elements, 4 nonzero):
	  [0,0] = 3
	  [0,1] = 4
	  [1,0] = 3
	  [1,1] = 4

    ; copy(A,M,0,2,2)
    ; M
	mat [2,2] (4 elements, 4 nonzero):
	  [0,0] = 3
	  [0,1] = 4
	  [1,0] = 1
	  [1,1] = 2

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    blk, mat, file, list, str

## Copyright (C) 1999-2006  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: blkcpy,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/blkcpy,v $
##
## Under source code control:	1997/04/05 14:08:50
## File existed as early as:	1997
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
�������������������������������������������������������������������������������������������������������������SYMBOL and NAME
    ->	- arrow operator

SYNOPSIS
    p -> X

TYPES
    p		pointer to an lvalue
    X		identifier

    return	lvalue

DESCRIPTION
    p->X returns the same as (*p).X.  Thus the current value of *p is
    to be an object of a type for which X identifies one element.
    p->X then returns the lvalue corresponding to that element of the
    value of *p.

    The expression *p.X will cause a runtime error since this is
    interpreted as *(p.X) in which p is expected to be an object of
    an appropriate type.

    Spaces or tabs on either side of -> are optional.

EXAMPLES
    ; obj pair {one, two}
    ; obj pair A, B
    ; p = &A
    ; p->one = 1; p->two = 2
    ; A
	    obj pair {1, 2}

    ; A->two = &B
    ; p->two->one = 3; p->two->two = 4

    ; *p->ptwo
	    obj pair {3, 4}

    ; B = {5,6}
    ; *p->two
	    obj pair {5, 6}


LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    address, dereference, isptr, dot

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: arrow,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/arrow,v $
##
## Under source code control:	1997/09/06 20:03:34
## File existed as early as:	1997
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    error - generate a value of specified error type

SYNOPSIS
    error([n])

TYPES
    n		integer, 0 <= n <= 32767; defaults to errno()

    return	null value or error value

DESCRIPTION

    If n is zero,  error(n) returns the null value.

    For positive n, error(n) returns a value of error type n.

    error(n) sets calc_errno to n so that until another error-value
    is returned by some function, errno() will return the value n.

EXAMPLE
    ; errmax(errcount()+1)
	   20
    ; a = error(10009)
    ; a
	   Error 10009
    ; strerror(a)
	   "Bad argument for inverse"

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    errcount, errmax, errorcodes, iserror, errno, strerror, newerror,
    stoponerror

## Copyright (C) 1999-2006  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: error,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/error,v $
##
## Under source code control:	1995/12/18 03:30:59
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    coth - hyperbolic cotangent

SYNOPSIS
    coth(x [,eps])

TYPES
    x		nonzero real
    eps		nonzero real, defaults to epsilon()

    return	real

DESCRIPTION
    Calculate the coth of x to a multiple of eps with error less in
    absolute value than .75 * eps.

    coth(x) = (exp(2*x) + 1)/(exp(2*x) - 1)

EXAMPLE
    ; print coth(1, 1e-5), coth(1, 1e-10), coth(1, 1e-15), coth(1, 1e-20)
    1.31304 1.3130352855 1.313035285499331 1.31303528549933130364

LIMITS
    none

LINK LIBRARY
    NUMBER *qcoth(NUMBER *x, NUMBER *eps)

SEE ALSO
    sinh, cosh, tanh, sech, csch, epsilon

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: coth,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/coth,v $
##
## Under source code control:	1995/11/13 03:49:00
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
   strscan - scan a string for possible assignment to variables

SYNOPSIS
   strscan(str, x_1, x_2, ..., x_n)

TYPES
    str			string
    x_1, x_2, ...	any

    return		integer

DESCRIPTION
   Successive fields of str separated by white space are read and
   evaluated so long as values remain in the x_i arguments;  when the
   x_i corresponding to the field is an lvalue the value obtained for the
   i-th field is assigned to x_i.

   The function returns the number of fields evaluated.

EXAMPLE
    global a,b
    ; strscan(" 2+3  a^2  print(b)", a, b, 0);
    25
	3
    ; print a,b
    5 25

LIMITS
    The number of arguments is not to exceed 1024.

LINK LIBRARY
    none

SEE ALSO
    strcat, strcpy, strerror, strlen, strncmp, strncpy, strpos,
    strprintf, strscanf, substr

## Copyright (C) 1999-2006  Ernest Bowen
##
## 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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: strscan,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/strscan,v $
##
## Under source code control:	1996/04/30 03:05:18
## File existed as early as:	1996
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
����������������������������������������������������������������������������������������������������������������NAME
    lfactor - smallest prime factor in first specified number of primes

SYNOPSIS
    lfactor(n, m)

TYPES
    n		integer
    m		nonnegative integer <= 203280221 (= number of primes < 2^32)

    return	positive integer

DESCRIPTION
    This function ignores the signs of n and m, so here we shall
    assume n and limit are both nonnegative.

    If n is nonzero and abs(n) has a prime proper factor in the first
    m primes (2, 3, 5, ...), then lfactor(n, m) returns the smallest
    such factor.  Otherwise 1 is returned.

    If n is nonzero and m = pix(limit), then lfactor(n, m) returns the
    same as factor(n, limit).

    Both lfactor(n, 0) and lfactor(1, m) return 1 for all n and m.
    Also lfactor(0, m) always returns 1, and factor(0, limit) always
    returns 2 if limit >= 2.

EXAMPLE
    ; print lfactor(35,2), lfactor(35,3), lfactor(-35, 3)
    1 5 5

    ; print lfactor(2^32+1,115), lfactor(2^32+1,116), lfactor(2^59-1,1e5)
    1 641 179951

LIMITS
    m <= 203280221 (= number of primes < 2^32)

LINK LIBRARY
    NUMBER *qlowfactor(NUMBER *n, NUMBER *count)
    FULL zlowfactor(ZVALUE z, long count)

SEE ALSO
    factor, isprime, nextcand, nextprime, prevcand, prevprime,
    pfact, pix, ptest

## Copyright (C) 1999-2006  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: lfactor,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/lfactor,v $
##
## Under source code control:	1995/12/18 12:34:57
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    isnum - whether a value is a numeric value

SYNOPSIS
    isnum(x)

TYPES
    x		any, &any

    return	int

DESCRIPTION
    Determine if x is a numeric value.	This function will return 1 if x
    is a a numeric value, 0 otherwise.

EXAMPLE
    ; print isnum(2.0), isnum(1), isnum("0")
    1 1 0

    ; print isnum(2i), isnum(1e20), isnum(1/3)
    1 1 1

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    isassoc, isatty, isblk, isconfig, isdefined, iserror, iseven, isfile,
    ishash, isident, isint, islist, ismat, ismult, isnull, isobj,
    isobjtype, isodd, isprime, isrand, israndom, isreal, isrel,
    issimple, issq, isstr, istype

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: isnum,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/isnum,v $
##
## Under source code control:	1994/10/21 02:21:28
## File existed as early as:	1994
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    isident - returns 1 if matrix is an identity matrix

SYNOPSIS
    isident(m)

TYPES
    m		any

    return	int

DESCRIPTION
    This function returns 1 if m is an 2 dimensional identity matrix,
    0 otherwise.

EXAMPLE
    ; mat x[3,3] = {1,0,0,0,1,0,0,0,1};
    ; isident(x)
	    1

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    mat, matdim, matfill, matmax, matmin, matsum, mattrans,
    isassoc, isatty, isblk, isconfig, isdefined, iserror, iseven, isfile,
    ishash, isint, islist, ismat, ismult, isnull, isnum, isobj,
    isobjtype, isodd, isprime, isrand, israndom, isreal, isrel,
    issimple, issq, isstr, istype

## Copyright (C) 1999  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.1 $
## @(#) $Id: isident,v 30.1 2007/03/16 11:10:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/isident,v $
##
## Under source code control:	1995/07/09 18:25:36
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������NAME
    ishash - whether a value is a hash state

SYNOPSIS
    ishash(x)

TYPES
    x		any

    return	integer

DESCRIPTION
    The value returned by ishash(x) is:

	0 if x is not a hash state,
	2 if x is a sha1 hash state,

EXAMPLE
    ; a = 1; b = sha1(0); c = sha1(a)
    ; print ishash(0), ishash(a), ishash(b), ishash(c), ishash(sha1(a))
    0 0 2 2 2

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    isassoc, isatty, isblk, isconfig, isdefined, iserror, iseven, isfile,
    isident, isint, islist, ismat, ismult, isnull, isnum, isobj,
    isobjtype, isodd, isprime, isrand, israndom, isreal, isrel,
    issimple, issq, isstr, istype, sha1

## Copyright (C) 1999-2007  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## @(#) $Revision: 30.2 $
## @(#) $Id: ishash,v 30.2 2007/07/05 17:37:41 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/ishash,v $
##
## Under source code control:	1995/11/11 05:09:41
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/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 /usr/lib.
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.

You need to include the following file to get the symbols and variables
related to error handling:

	lib_calc.h

External programs may want to compile with:

	-I${INCDIR} -L/usr/lib -lcalc

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

	-I${INCDIR} -L/usr/lib -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.

-------------------
MATH ERROR HANDLING
-------------------

The math_error() function is called by the math routines on an error
condition, such as malloc failures, division by zero, or some form of
an internal computation error.  The routine is called in the manner of
printf, with a format string and optional arguments:

	    void math_error(char *fmt, ...);

Your program must handle math errors in one of three ways:

    1) Print the error message and then exit

	There is a math_error() function supplied with the calc library.
	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.

    2) Use setjmp and longjmp in your program

	Use setjmp at some appropriate level in your program, and let
	the longjmp in math_error() return to that level and to allow you
	to recover from the error.  This is what the calc program does.

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

	For example:

	    #include <setjmp.h>
	    #include "lib_calc.h"

	    int error;

	    ...

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

		    /* report the error */
		    printf("Ouch: %s\n", calc_err_msg);

		    /* reinitialize calc after the longjmp */
		    reinitialize();
	    }
	    calc_use_matherr_jmpbuf = 1;

	If calc_use_matherr_jmpbuf is non-zero, then the jmp_buf value
	calc_matherr_jmpbuf must be initialized by the setjmp() function
	or your program will crash.

    3) Supply your own math_error function:

	    void math_error(char *fmt, ...);

	Your math_error() function may exit or transfer control to outside
	of the calc library, but it must never return or calc will crash.

External programs can obtain the appropriate calc symbols by compiling with:

	-I${INCDIR} -L/usr/lib -lcalc

-------------------------
PARSE/SCAN ERROR HANDLING
-------------------------

The scanerror() function is called when calc encounters a parse/scan
error.  For example, scanerror() is called when calc is given code
with a syntax error.

The variable, calc_print_scanerr_msg, controls if calc prints to stderr,
any parse/scan errors.  By default, this variable it set to 1 and so
parse/scan errors are printed to stderr.  By setting this value to zero,
parse/scan errors are not printed:

	#include "lib_calc.h"

	/* do not print parse/scan errors to stderr */
	calc_print_scanerr_msg = 0;

The last calc math error or calc parse/scan error message is kept
in the NUL terminated buffer:

	char calc_err_msg[MAXERROR+1];

The value of calc_print_scanerr_msg does not change the use
of the calc_err_msg[] buffer.  Messages are stored in that
buffer regardless of the calc_print_scanerr_msg value.

The calc_print_scanerr_msg and the calc_err_msg[] buffer are declared
lib_calc.h include file.  The initialized storage for these variables
comes from the calc library.  The MAXERROR symbol is also declared in
the lib_calc.h include file.

Your program must handle parse/scan errors in one of two ways:

    1) exit on error

	If you do not setup the calc_scanerr_jmpbuf, then when calc
	encounters a parse/scan error, a message will be printed to
	stderr and calc will exit.

    2) Use setjmp and longjmp in your program

	Use setjmp at some appropriate level in your program, and let
	the longjmp in scanerror() return to that level and to allow you
	to recover from the error.  This is what the calc program does.

	If one sets up calc_scanerr_jmpbuf, and then sets
	calc_use_scanerr_jmpbuf to non-zero then scanerror() will longjmp
	back with the return with a non-zero code.  In addition, the last
	calc error message will be found in calc_err_msg[]; this error is
	not printed to stderr.	The calc error message will not have a
	trailing newline.

	For example:

	    #include <setjmp.h>
	    #include "lib_calc.h"

	    int scan_error;

	    ...

	    /* delay the printing of the parse/scan error */
	    calc_use_scanerr_jmpbuf = 0;	/* this is optional */

	    if ((scan_error = setjmp(calc_scanerr_jmpbuf)) != 0) {

		    /* report the parse/scan */
		    if (calc_use_scanerr_jmpbuf == 0) {
			    printf("parse error: %s\n", calc_err_msg);
	    	    }

		    /* initialize calc after the longjmp */
		    initialize();
	    }
	    calc_use_scanerr_jmpbuf = 1;

	If calc_use_scanerr_jmpbuf is non-zero, then the jmp_buf value
	calc_scanerr_jmpbuf must be initialized by the setjmp() function
	or your program will crash.

External programs can obtain the appropriate calc symbols by compiling with:

	-I${INCDIR} -L/usr/lib -lcalc

---------------------------
PARSE/SCAN WARNING HANDLING
---------------------------

Calc parse/scan warning message are printed to stderr by the warning()
function.  The routine is called in the manner of printf, with a format
string and optional arguments:

	void warning(char *fmt, ...);

The variable, calc_print_scanwarn_msg, controls if calc prints to stderr,
any parse/scan warnings.  By default, this variable it set to 1 and so
parse/scan warnings are printed to stderr.  By setting this value to zero,
parse/scan warnings are not printed:

	#include "lib_calc.h"

	/* do not print parse/scan warnings to stderr */
	calc_print_scanwarn_msg = 0;

The last calc calc parse/scan warning message is kept in the NUL
terminated buffer:

	char calc_warn_msg[MAXERROR+1];

The value of calc_print_scanwarn_msg does not change the use
of the calc_warn_msg[] buffer.  Messages are stored in that
buffer regardless of the calc_print_scanwarn_msg value.

Your program must handle parse/scan warnings in one of two ways:

    1) print the warning to stderr and continue

	The warning() from libcalc prints warning messages to
	stderr and returns.  The flow of execution is not changed.
	This is what calc does by default.

    2) Supply your own warning function:

	    void warning(char *fmt, ...);

	Your warning function should simply return when it is finished.

External programs can obtain the appropriate calc symbols by compiling with:

	-I${INCDIR} -L/usr/lib -lcalc


---------------
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 dive