*************
* intro
*************

What is calc?

    Calc is an interactive calculator which provides for easy large
    numeric calculations, but which also can be easily programmed
    for difficult or long calculations.  It can accept a command line
    argument, in which case it executes that single command and exits.
    Otherwise, it enters interactive mode.  In this mode, it accepts
    commands one at a time, processes them, and displays the answers.
    In the simplest case, commands are simply expressions which are
    evaluated.  For example, the following line can be input:

            3 * (4 + 1)

    and the calculator will print:

            15

    Calc has the usual collection of arithmetic operators +, -, /, *
    as well as ^ (exponentiation), % (modulus) and // (integer divide).
    For example:

            3 * 19^43 - 1

     will produce:

            29075426613099201338473141505176993450849249622191102976

    Notice that calc values can be very large.  For example:

            2^23209-1

    will print:

           402874115778988778181873329071 ... many digits ... 3779264511

    The special '.' symbol (called dot), represents the result of the
    last command expression, if any.  This is of great use when a series
    of partial results are calculated, or when the output mode is changed
    and the last result needs to be redisplayed.  For example, the above
    result (2^23209-1) can be modified by typing:

            . % (2^127-1)

    and the calculator will print:

            39614081257132168796771975167

    For more complex calculations, variables can be used to save the
    intermediate results.  For example, the result of adding 7 to the
    previous result can be saved by typing:

            curds = 15
            whey = 7 + 2*curds

    Functions can be used in expressions.  There are a great number of
    pre-defined functions.  For example, the following will calculate
    the factorial of the value of 'whey':

            fact(whey)

    and the calculator prints:

            13763753091226345046315979581580902400000000

    The calculator also knows about complex numbers, so that typing:

            (2+3i) * (4-3i)
            cos(.)

    will print:

            17+6i
            -55.50474777265624667147+193.9265235748927986537i

    The calculator can calculate transcendental functions, and accept and
    display numbers in real or exponential format. For example, typing:

            config("display", 70)
            epsilon(1e-70)
            sin(1)

    prints:

        0.8414709848078965066525023216302989996225630607983710656727517099919104

    Calc can output values in terms of fractions, octal or hexadecimal.
    For example:

            config("mode", "fraction"),
            (17/19)^23
            base(16),
            (19/17)^29

     will print:

            19967568900859523802559065713/257829627945307727248226067259
            0x9201e65bdbb801eaf403f657efcf863/0x5cd2e2a01291ffd73bee6aa7dcf7d1

    All numbers are represented as fractions with arbitrarily large
    numerators and denominators which are always reduced to lowest terms.
    Real or exponential format numbers can be input and are converted
    to the equivalent fraction.  Hex, binary, or octal numbers can be
    input by using numbers with leading '0x', '0b' or '0' characters.
    Complex numbers can be input using a trailing 'i', as in '2+3i'.
    Strings and characters are input by using single or double quotes.

    Commands are statements in a C-like language, where each input
    line is treated as the body of a procedure.  Thus the command
    line can contain variable declarations, expressions, labels,
    conditional tests, and loops.  Assignments to any variable name
    will automatically define that name as a global variable.  The
    other important thing to know is that all non-assignment expressions
    which are evaluated are automatically printed.  Thus, you can evaluate
    an expression's value by simply typing it in.

    Many useful built-in mathematical functions are available.  Use
    the:

            help builtin

    command to list them.

    You can also define your own functions by using the 'define' keyword,
    followed by a function declaration very similar to C.

            define f2(n)
            {
                    local       ans;

                    ans = 1;
                    while (n > 1)
                            ans *= (n -= 2);
                    return ans;
            }

    Thus the input:

            f2(79)

    will produce:

            1009847364737869270905302433221592504062302663202724609375

    Functions which only need to return a simple expression can be defined
    using an equals sign, as in the example:

            define sc(a,b) = a^3 + b^3

    Thus the input:

            sc(31, 61)

    will produce:

            256772

    Variables in functions can be defined as either 'global', 'local',
    or 'static'.  Global variables are common to all functions and the
    command line, whereas local variables are unique to each function
    level, and are destroyed when the function returns.  Static variables
    are scoped within single input files, or within functions, and are
    never destroyed.  Variables are not typed at definition time, but
    dynamically change as they are used.

    For more information about the calc language and features, try:

            help overview

    In particular, check out the other help functions listed in the
    overview help file.

## Copyright (C) 1999,2021  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.
##
## Under source code control:   1991/07/21 04:37:21
## 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/

*************
* overview
*************

                    CALC - An arbitrary precision calculator.
                            by David I. Bell


    This is a calculator program with arbitrary precision arithmetic.
    All numbers are represented as fractions with arbitrarily large
    numerators and denominators which are always reduced to lowest terms.
    Real or exponential format numbers can be input and are converted
    to the equivalent fraction.  Hex, binary, or octal numbers can be
    input by using numbers with leading '0x', '0b' or '0' characters.
    Complex numbers can be input using a trailing 'i', as in '2+3i'.
    Strings and characters are input by using single or double quotes.

    Commands are statements in a C-like language, where each input
    line is treated as the body of a procedure.  Thus the command
    line can contain variable declarations, expressions, labels,
    conditional tests, and loops.  Assignments to any variable name
    will automatically define that name as a global variable.  The
    other important thing to know is that all non-assignment expressions
    which are evaluated are automatically printed.  Thus, you can evaluate
    an expression's value by simply typing it in.

    Many useful built-in mathematical functions are available.  Use
    the 'show builtins' command to list them.  You can also define
    your own functions by using the 'define' keyword, followed by a
    function declaration very similar to C.  Functions which only
    need to return a simple expression can be defined using an
    equals sign, as in the example 'define sc(a,b) = a^3 + b^3'.
    Variables in functions can be defined as either 'global', 'local',
    or 'static'.  Global variables are common to all functions and the
    command line, whereas local variables are unique to each function
    level, and are destroyed when the function returns.  Static variables
    are scoped within single input files, or within functions, and are
    never destroyed.  Variables are not typed at definition time, but
    dynamically change as they are used.  So you must supply the correct
    type of variable to those functions and operators which only work
    for a subset of types.

    Calc has a help command that will produce information about
    every builtin function, command as well as a number of other
    aspects of calc usage.  Try the command:

            help help

    for and overview of the help system.  The command:

            help builtin

    provides information on built-in mathematical functions, whereas:

            help asinh

    will provides information a specific function.  The following
    help files:

            help command
            help define
            help operator
            help statement
            help variable

    provide a good overview of the calc language.  If you are familiar
    with C, you should also try:

            help unexpected

    It contains information about differences between C and calc
    that may surprise you.

    To learn about calc standard resource files, try:

            help resource

    To learn how to invoke the calc command and about calc -flags, try:

            help usage

    To learn about calc shell scripts, try:

            help script

    A full and extensive overview of calc may be obtained by:

            help full

    The man command is an alias for the help command.  Try:

            man jacobi

    Only calc help files may be displayed by the help and man commands.

    By default, arguments to functions are passed by value (even
    matrices).  For speed, you can put an ampersand before any
    variable argument in a function call, and that variable will be
    passed by reference instead.  However, if the function changes
    its argument, the variable will change.  Arguments to built-in
    functions and object manipulation functions are always called
    by reference.  If a user-defined function takes more arguments
    than are passed, the undefined arguments have the null value.
    The 'param' function returns function arguments by argument
    number, and also returns the number of arguments passed.  Thus
    functions can be written to handle an arbitrary number of
    arguments.

    The mat statement is used to create a matrix.  It takes a
    variable name, followed by the bounds of the matrix in square
    brackets.  The lower bounds are zero by default, but colons can
    be used to change them.  For example 'mat foo[3, 1:10]' defines
    a two dimensional matrix, with the first index ranging from 0
    to 3, and the second index ranging from 1 to 10.  The bounds of
    a matrix can be an expression calculated at runtime.

    Lists of values are created using the 'list' function, and values can
    be inserted or removed from either the front or the end of the list.
    List elements can be indexed directly using double square brackets.

    The obj statement is used to create an object.  Objects are
    user-defined values for which user-defined routines are
    implicitly called to perform simple actions such as add,
    multiply, compare, and print. Objects types are defined as in
    the example 'obj complex {real, imag}', where 'complex' is the
    name of the object type, and 'real' and 'imag' are element
    names used to define the value of the object (very much like
    structures).  Variables of an object type are created as in the
    example 'obj complex x,y', where 'x' and 'y' are variables.
    The elements of an object are referenced using a dot, as in the
    example 'x.real'. All user-defined routines have names composed
    of the object type and the action to perform separated by an
    underscore, as in the example 'complex_add'.  The command 'show
    objfuncs' lists all the definable routines.  Object routines
    which accept two arguments should be prepared to handle cases
    in which either one of the arguments is not of the expected
    object type.

    These are the differences between the normal C operators and
    the ones defined by the calculator.  The '/' operator divides
    fractions, so that '7 / 2' evaluates to 7/2. The '//' operator
    is an integer divide, so that '7 // 2' evaluates to 3.  The '^'
    operator is a integral power function, so that 3^4 evaluates to
    81.  Matrices of any dimension can be treated as a zero based
    linear array using double square brackets, as in 'foo[[3]]'.
    Matrices can be indexed by using commas between the indices, as
    in foo[3,4].  Object and list elements can be referenced by
    using double square brackets.

    The print statement is used to print values of expressions.
    Separating values by a comma puts one space between the output
    values, whereas separating values by a colon concatenates the
    output values.  A trailing colon suppresses printing of the end
    of line.  An example of printing is

        print "The square of", x, "is", x^2

    The 'config' function is used to modify certain parameters that
    affect calculations or the display of values.  For example, the
    output display mode can be set using:

        config("mode", type)

    where 'type' is one of 'frac', 'int', 'real', 'exp', 'hex',
    'oct', or 'bin'.  The default output mode is real.  For the
    integer, real, or exponential formats, a leading '~' indicates
    that the number was truncated to the number of decimal places
    specified by the default precision.  If the '~' does not
    appear, then the displayed number is the exact value.

    The number of decimal places printed is set by using:

        config("display", n)

    The default precision for real-valued functions can be set by
    using 'epsilon(x)', where x is the required precision (such as
    1e-50).  For example:

        config("display", 70)
        epsilon(1e-70)
        sin(1)

    There is a command stack feature so that you can easily
    re-execute previous commands and expressions from the terminal.
    You can also edit the current command before it is completed.
    Both of these features use emacs-like commands.

    Files can be read in by using the 'read filename' command.
    These can contain both functions to be defined, and expressions
    to be calculated.  Global variables which are numbers can be
    saved to a file by using the 'write filename' command.

## Copyright (C) 1999-2017,2021  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.
##
## 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/

*************
* calc
*************

calc(1)                      General Commands Manual                     calc(1)



NNAAMMEE
       calc - arbitrary precision calculator

SSYYNNOOPPSSIISS
       _c_a_l_c [--cc] [--CC] [--dd]
            [--DD ccaallcc__ddeebbuugg[[::rreessoouurrccee__ddeebbuugg[[::uusseerr__ddeebbuugg]]]]]
            [--ee] [--ff ffiilleennaammee] [--hh] [--ii] [--mm mmooddee] [--OO]
            [--pp] [--qq] [--ss] [--uu] [--vv] [[[----]] ccaallcc__ccmmdd ......]

       _#_!_/_o_p_t_/_l_o_c_a_l_/_b_i_n_/_c_a_l_c [optional_other_flags ...] --ff


DDEESSCCRRIIPPTTIIOONN
       --cc     Continue reading command lines even after a scan/parse error has
              caused the abandonment of a line.  Note that this option only
              deals with scanning and parsing of the calc language.  It does not
              deal with execution or run-time errors.

              For example:

                   calc read many_errors.cal

              will cause ccaallcc to abort on the first syntax error, whereas:

                   calc -c read many_errors.cal

              will cause ccaallcc to try to process each line being read despite the
              scan/parse errors that it encounters.

              By default, calc startup resource files are silently ignored if
              not found.  This flag will report missing startup resource files
              unless --dd is also given.


       --CC     Permit the execution of custom builtin functions.  Without this
              flag, calling the custom() builtin function will simply generate
              an error.

              Use of this flag may cause ccaallcc to execute functions that are non-
              standard and that are not portable.  Custom builtin functions are
              disabled by default for this reason.


       --dd     Disable the printing of the opening title.  The printing of
              resource file debug and informational messages is also disabled as
              if ccoonnffiigg((""rreessoouurrccee__ddeebbuugg"",, 00)) had been executed.

              For example:

                   calc "read qtime; qtime(2)"

              will output something like:

                   qtime(utc_hr_offset) defined
                   It's nearly ten past six.

              whereas:

                   calc -d "read qtime; qtime(2)"

              will just print:

                   It's nearly ten past six.

              This flag disables the reporting of missing calc startup resource
              files.


              This flag also disables the printing the leading tilde. For
              example:

                   calc 2/3

              will print:

                   ~0.66666666666666666667


              whereas:

                   calc -d 2/3

              will just print:

                   0.66666666666666666667



       --DD calc_debug[:resource_debug[:user_debug]]
              Force the initial value of config("calc_debug"),
              config("resource_debug") and config("user_debug").

              The : separated strings are interpreted as signed 32 bit integers.
              After an optional leading sign a leading zero indicates octal
              conversion, and a leading ``0x'' or ``0X'' hexadecimal conversion.
              Otherwise, decimal conversion is assumed.

              By default, _c_a_l_c___d_e_b_u_g is 0, _r_e_s_o_u_r_c_e___d_e_b_u_g is 3 and _u_s_e_r___d_e_b_u_g is
              0.

              For more information use the following ccaallcc command:

                   help config


       --ee     Ignore any environment variables on startup.  The getenv() builtin
              will still return values, however.


       --ff filename
              This flag is normally only with calc shell scripts.

              This flag is required when using calc in sshheellll ssccrriipptt mmooddee.  It
              must be at the end of the initial ##!!  line of the script, as in:

                   _#_!_/_o_p_t_/_l_o_c_a_l_/_b_i_n_/_c_a_l_c [optional_other_flags ...] --ff

              the rest of the file will be processed in sshheellll ssccrriipptt mmooddee.


              A common flag to use, prior to the --ff on the #! line is the --qq
              flag.  For example:

                   _#_!_/_o_p_t_/_l_o_c_a_l_/_b_i_n_/_c_a_l_c --qq --ff


              See SSHHEELLLL SSCCRRIIPPTT MMOODDEE section of this man page below for details.

              While the actual form of this flag is:

                   --ff filename

              for systems that treat an executable that begins with ##!!  as a
              script, the path of the executable is appended by the kernel as
              the final argument to the exec() system call.  This is why the --ff
              flag at the very end of the ##!!  line.

              It is possible use --ff filename on the command line:

                   _c_a_l_c [optional_other_flags ...] --ff filename

              This will cause calc to process lines in ffiilleennaammee in sshheellll ssccrriipptt
              mmooddee.


              NNOOTTEE:: The use of --ff does NNOOTT imply --qq and thus one would need to
              use

                   _c_a_l_c [optional_other_flags ...] --qq --ff filename

              to disable the use of calc startup files as well.


              The use of --ff filename implies the --ss flag.


       --hh     Print a help message.  This option implies --qq.  This is equivalent
              to the ccaallcc command help help.  The help facility is disabled
              unless the mode is 5 or 7.  See --mm.


       --ii     Become interactive if possible.  This flag will cause ccaallcc to drop
              into interactive mode after the _c_a_l_c___c_m_d arguments on the command
              line are evaluated.  Without this flag, ccaallcc will exit after they
              are evaluated.

              For example:

                   calc 2+5

              will print the value 7 and exit whereas:

                   calc -i 2+5

              will print the value 7 and prompt the user for more ccaallcc commands.


       --mm mode
              This flag sets the permission mode of ccaallcc.  It controls the
              ability for ccaallcc to open files and execute programs.  _M_o_d_e may be
              a number from 0 to 7.

              The mode value is interpreted in a way similar to that of the
              cchhmmoodd(1) octal mode:

                   0  do not open any file, do not execute progs
                   1  do not open any file
                   2  do not open files for reading, do not execute progs
                   3  do not open files for reading
                   4  do not open files for writing, do not execute progs
                   5  do not open files for writing
                   6  do not execute any program
                   7  allow everything (default mode)

              If one wished to run ccaallcc from a privileged user, one might want
              to use --mm 0 in an effort to make ccaallcc somewhat more secure.

              Mode bits for reading and writing apply only on an open.  Files
              already open are not effected.  Thus if one wanted to use the --mm 0
              in an effort to make ccaallcc somewhat more secure, but still wanted
              to read and write a specific file, one might want to do in sshh(1),
              kksshh(1), bbaasshh(1)-like shells:

                   calc -m 0 3<a.file

              Files presented to ccaallcc in this way are opened in an unknown mode.
              CCaallcc will attempt to read or write them if directed.

              If the mode disables opening of files for reading, then the
              startup resource files are disabled as if --qq was given.  The
              reading of key bindings is also disabled when the mode disables
              opening of files for reading.


       --OO     Use the old classic defaults instead of the default configuration.
              This flag as the same effect as executing ccoonnffiigg((""aallll"",, ""oollddccffgg""))
              at startup time.

              NOTE: Older versions of calc used --nn to setup a modified form of
              the default calc configuration.  The --nn flag currently does
              nothing.  Use of the --nn flag is now deprecated and may be used for
              something else in the future.


       --pp     Pipe processing is enabled by use of --pp.  For example:

                   calc -p "2^21701-1" | fizzbin

              In pipe mode, ccaallcc does not prompt, does not print leading tabs
              and does not print the initial header.  The --pp flag overrides --ii.


              When running calc as a shell script (see SSHHEELLLL SSCCRRIIPPTT MMOODDEE for
              details), calc will close standard input (stdin) during startup
              UUNNLLEESSSS the --pp flag is given on the command line.  When calc is
              running in sshheellll ssccrriipptt mmooddee, shell scripts that call the
              pprroommpptt(str) builtin will not work properly (the prompt builtin
              will always fail) unless the --pp flag is given on the command line.


       --qq     Disable the reading of the startup scripts.

              This allows the script to run independently of startup scripts
              such those managed by the $$CCAALLCCRRCC environment variable.  For
              example, this will disable the use of the common calcrc file
              (usually ~/.calcrc).


       --ss     By default, all _c_a_l_c___c_m_d args are evaluated and executed.  This
              flag will disable their evaluation and instead make them available
              as strings for the argv() builtin function.


       --uu     Disable buffering of stdin and stdout.


       --vv     Print the ccaallcc version number and exit.


       ----     The double dash indicates to calc that no more options follow.
              Thus calc will ignore a later argument on the command line even if
              it starts with a dash.  This is useful when entering negative
              values on the command line as in:

                   calc -p -- -1 - -7



CCAALLCC CCOOMMMMAANNDD LLIINNEE
       With no _c_a_l_c___c_m_d arguments, ccaallcc operates interactively.  If one or more
       arguments are given on the command line and --ss is NOT given, then ccaallcc
       will read and execute them and either attempt to go interactive according
       as the --ii flag was present or absent.

       If --ss is given, ccaallcc will not evaluate any _c_a_l_c___c_m_d arguments but instead
       make them available as strings to the argv() builtin function.

       Sufficiently simple commands with no characters like parentheses,
       brackets, semicolons, '*', which have special interpretations in UNIX
       shells may be entered, possibly with spaces, until the terminating
       newline.  For example:

            calc 23 + 47

       will print 70.  However, command lines will have problems:

            calc 23 * 47

            calc -23 + 47

       The first example above fails because the shell interprets the '*' as a
       file glob.  The second example fails because '-23' is viewed as a calc
       option (which it is not) and do calc objects to that it thinks of as an
       unknown option.  These cases can usually be made to work as expected by
       enclosing the command between quotes:

            calc '23 * 47'

            calc "print sqrt(2), exp(1)"

       or in parentheses and quotes to avoid leading -'s as in:

            calc '(-23 + 47)'

       One may also use a double dash to denote that calc options have ended as
       in:

            calc -- -23 + 47

            calc -q -- -23 + 47

       If '!' is to be used to indicate the factorial function, for shells like
       ccsshh_(_1_) for which '!' followed by a non-space character is used for
       history substitution, it may be necessary to include a space or use a
       backslash to escape the special meaning of '!'.  For example, the
       command:

            print 27!^2

       may have to be replaced by:

            print 27! ^2    or      print 27\!^2

       Reading from standard input when calc is part of a pipe works as long as
       the -p flag is given to calc.  For example, this will print chongo was
       here:

            echo chongo was here | calc -p 'print fgetline(files(0));'


       while this does not:

            echo chongo was here | calc 'print fgetline(files(0));'


       nor will this print chongo was here:

            echo chongo was here | calc -i 'print fgetline(files(0));'


       This is because without --pp, the interactive parser, in an effort to parse
       interactive commands, flushes data on standard input.


CCAALLCC SSTTAARRTTUUPP FFIILLEESS
       Normally on startup, if the environment variable $$CCAALLCCRRCC is undefined and
       ccaallcc is invoked without the --qq flag, or if $$CCAALLCCRRCC is defined and calc is
       invoked with --ee, ccaallcc looks for a file "startup" in the calc resource
       directory ..ccaallccrrcc in the user's home directory, and ..ccaallcciinniitt iinn tthhee
       ccuurrrreenntt ddiirreeccttoorryy..  If one or more of these are found, they are read in
       succession as ccaallcc scripts and their commands executed.  When defined,
       $$CCAALLCCRRCC is to contain a ':' separated list of names of files, and if calc
       is then invoked without either the --qq or --ee flags, these files are read
       in succession and their commands executed.  No error condition is
       produced if a listed file is not found.

       If the mode specified by --mm disables opening of files for reading, then
       the reading of startup files is also disabled as if --qq was given.


CCAALLCC FFIILLEE SSEEAARRCCHH PPAATTHH
       If the environment variable $$CCAALLCCPPAATTHH is undefined, or if it is defined
       and ccaallcc is invoked with the --ee flag, when a file name not beginning with
       //, ~~ or ..//, is specified as in:

            calc read myfile

       ccaallcc searches in succession:

            ./myfile
            ./myfile.cal
            /opt/local/lib/myfile
            /opt/local/lib/myfile.cal
            /opt/local/share/calc/custom/myfile
            /opt/local/share/calc/custom/myfile.cal

       If the file is found, the search stops and the commands in the file are
       executed.  It is an error if no readable file with the specified name is
       found.  An alternative search path can be specified by defining $$CCAALLCCPPAATTHH
       in the same way as PATH is defined, as a ':' separated list of
       directories, and then invoking ccaallcc without the --ee flag.

       CCaallcc treats all open files, other than stdin, stdout and stderr as files
       available for reading and writing.  One may present ccaallcc with an already
       open file using sshh(1), kksshh(1), bbaasshh(1)-like shells is to:

            calc 3<open_file 4<open_file2

       For more information use the following ccaallcc commands:

            help help
            help overview
            help usage
            help environment
            help config



SSHHEELLLL SSCCRRIIPPTT MMOODDEE
       If the first line of an executable file begins ##!!  followed by the
       absolute pathname of the ccaallcc program and the first line ends with the
       flag --ff as in:

            _#_!_/_o_p_t_/_l_o_c_a_l_/_b_i_n_/_c_a_l_c [optional_other_flags ...] --ff

       the rest of the file will be processed in sshheellll ssccrriipptt mmooddee.  Note that
       --ss --ff must be at the end of the initial ``#!'' line.  Any other optional
       ooppttiioonnaall__ootthheerr__ffllaaggss must come before the --ff flag.

       In sshheellll ssccrriipptt mmooddee the contents of the file are read and executed as if
       they were in a file being processed by a read command, except that a
       "command" beginning with '#' followed by whitespace and ending at the
       next newline is treated as a comment.  Any optional ooppttiioonnaall__ootthheerr__ffllaaggss
       will be parsed first followed by the later lines within the script
       itself.

       In sshheellll ssccrriipptt mmooddee, --ss is always assumed.  In addition, --dd and --pp are
       automatically set if --ii is not given.

       NNOOTTEE:: The use of --ff does NNOOTT imply --qq and thus one would need to use

            _c_a_l_c [optional_other_flags ...] --qq --ff filename

       to disable the use of calc startup files as well.

       For example, if the file //ttmmpp//mmeerrsseennnnee:

            _#_!_/_o_p_t_/_l_o_c_a_l_/_b_i_n_/_c_a_l_c --qq --ff

            /* setup */
            argc = argv();
            program = argv(0);
            stderr = files(2);

            /* parse args */
            if (argc != 2) {
                fprintf(stderr, "usage: %s exp0, program);
                abort "must give one exponent arg";
            }
            exp = eval(argv(1));
            if (!isint(exp) || exp < 0) {
                fprintf(stderr, "%s: exp must be non-negative integer0, program);
                abort "must give one exponent arg";
            }

            /* print the mersenne number */
            print "2^": exp : "-1 =", 2^exp-1;

       is made an executable file by:

            chmod +x /tmp/mersenne

       then the command line:

            /tmp/mersenne 127

       will print:

            2^127-1 = 170141183460469231731687303715884105727

       Note that because --ss is required in sshheellll ssccrriipptt mmooddee non-dashed args are
       made available as strings via the aarrggvv() builtin function.  Therefore:

            2^eval(argv(1))-1

       will print the decimal value of 2^n-1 whereas

            2^argv(1)-1

       will not.


       By default, using calc startup in sshheellll ssccrriipptt mmooddee, calc will close
       standard input (stdin).  Thus builtin functions such as pprroommpptt(str) will
       fail (return a null value).  Calc shell scripts that call the pprroommpptt(str)
       builtin will not work properly (the prompt builtin will always fail and
       return a null value) unless the --pp flag is given on the command line.


       The following shell script will always print "got null" because stdin
       will be closed by calc during startup:


            #!/usr/bin/calc -q -f

            # The prompt will ALWAYS FAIL and return a null value
            n = prompt("Test> ");
            if (isnull(n)) {
              print("got null");
            } else {
              print("got " + n);
            }

       However the following shell script (note the --pp before the --ff in the 1st
       line) will be interactive, prompt with "Test> " and print the "got"
       result as expected:


            #!/usr/bin/calc -q -p -f

            n = prompt("Test> ");
            if (isnull(n)) {
              print("got null");
            } else {
              print("got " + n);
            }


       Note in the example above, the --pp flag must be given before the final --ff
       command line flag.


DDAATTAA TTYYPPEESS
       Fundamental builtin data types include integers, real numbers, rational
       numbers, complex numbers and strings.

       By use of an object, one may define an arbitrarily complex data types.
       One may define how such objects behave a wide range of operations such as
       addition, subtraction, multiplication, division, negation, squaring,
       modulus, rounding, exponentiation, equality, comparison, printing and so
       on.

       For more information use the following ccaallcc commands:

          help types
          help obj
          show objfuncs


VVAARRIIAABBLLEESS
       Variables in _c_a_l_c are typeless.  In other words, the fundamental type of
       a variable is determined by its content.  Before a variable is assigned a
       value it has the value of zero.

       The scope of a variable may be global, local to a file, or local to a
       procedure.  Values may be grouped together in a matrix, or into a list
       that permits stack and queue style operations.

       For more information use the following ccaallcc commands:

          help variable
          help mat
          help list
          show globals


IINNPPUUTT//OOUUTTPPUUTT
       A leading ``0x'' implies a hexadecimal value, a leading ``0b'' implies a
       binary value, and a ``0'' followed by a digit implies an octal value.
       Complex numbers are indicated by a trailing ``i'' such as in ``3+4i''.
       Strings may be delimited by either a pair of single or double quotes.  By
       default, _c_a_l_c prints values as if they were floating point numbers.  One
       may change the default to print values in a number of modes including
       fractions, integers and exponentials.

       A number of stdio-like file I/O operations are provided.  One may open,
       read, write, seek and close files.  Filenames are subject to `` ''
       expansion to home directories in a way similar to that of the Korn or C-
       Shell.

       For example:

          ~/.calcrc
          ~chongo/lib/fft_multiply.cal

       For more information use the following ccaallcc command:

          help file


CCAALLCC LLAANNGGUUAAGGEE
       The _c_a_l_c language is a C-like language.  The language includes commands
       such as variable declarations, expressions, tests, labels, loops, file
       operations, function calls.  These commands are very similar to their
       counterparts in C.

       The language also include a number of commands particular to _c_a_l_c itself.
       These include commands such as function definition, help, reading in
       resource files, dump files to a file, error notification, configuration
       control and status.

       For more information use the following ccaallcc command:

          help command
          help statement
          help expression
          help operator
          help config


FFIILLEESS
       /opt/local/bin/calc
            calc binary

       /opt/local/bin/cscript/*
            calc shell scripts

       /opt/local/lib/*.cal
            calc standard resource files

       /opt/local/lib/help/*
            help files

       /opt/local/lib/bindings
            non-GNU-readline command line editor bindings

       /opt/local/include/calc/*.h
            include files for C interface use

       /opt/local/lib/libcalc.a
            calc binary link library

       /opt/local/lib/libcustcalc.a
            custom binary link library

       /opt/local/share/calc/custom/*.cal
            custom resource files

       /opt/local/share/calc/custhelp/*
            custom help files


EENNVVIIRROONNMMEENNTT
       CALCPATH
            A :-separated list of directories used to search for calc resource
            filenames that do not begin with /, ./ or ~.

            Default value: .:./cal:~/.cal:/opt/local/share/calc:
            /opt/local/share/calc/custom

       CALCRC
            On startup (unless -h or -q was given on the command line), ccaallcc
            searches for files along this :-separated environment variable.

            Default value: ./.calcinit:~/.calcrc:/opt/local/share/calc/startup

       CALCBINDINGS
            On startup (unless _-_h or _-_q was given on the command line, or _-_m
            disallows opening files for reading), ccaallcc reads key bindings from
            the filename specified by this environment variable.  The key
            binding file is searched for along the $CALCPATH list of
            directories.

            Default value: binding

            This variable is not used if calc was compiled with GNU-readline
            support.  In that case, the standard readline mechanisms (see
            readline(3)) are used.

       CALCHISTFILE
            Location of the calc history file.

            Default value: ~/.calc_history

            This variable is not used if calc was compiled with GNU-readline
            support.

       CALCHELP
            Location of the calc help directory.

            Default value: /opt/local/share/calc/help

       CALCCUSTOMHELP
            Location of the calc custom help directory.

            Default value: /opt/local/share/calc/custhelp


CCRREEDDIITT
       The main chunk of ccaallcc was written by David I. Bell.

       The ccaallcc primary mirror, and calc bug report processing is performed by
       Landon Curt Noll.

       Landon Curt Noll maintains the master reference source, performs release
       control functions as well as other calc maintenance functions.

       Thanks for suggestions and encouragement from Peter Miller, Neil
       Justusson, and Landon Noll.

       Thanks to Stephen Rothwell for writing the original version of hist.c
       which is used to do the command line editing.

       Thanks to Ernest W. Bowen for supplying many improvements in accuracy and
       generality for some numeric functions.  Much of this was in terms of
       actual code which I gratefully accepted.  Ernest also supplied the
       original text for many of the help files.

       Portions of this program are derived from an earlier set of public domain
       arbitrarily precision routines which was posted to the net around 1984.
       By now, there is almost no recognizable code left from that original
       source.

CCOOPPYYIINNGG // CCAALLCC GGNNUU LLEESSSSEERR GGEENNEERRAALL PPUUBBLLIICC LLIICCEENNSSEE
       Calc is open software, and is covered under version 2.1 of the GNU Lesser
       General Public License.  You are welcome to change it and/or distribute
       copies of it under certain conditions.  The calc commands:

            help copyright
            help copying
            help copying-lgpl
            help credit

       should display the contents of the COPYING and COPYING-LGPL files.  Those
       files contain information about the calc's GNU Lesser General Public
       License, and in particular the conditions under which you are allowed to
       change it and/or distribute copies of it.

       You should have received a copy of the version 2.1 of the GNU Lesser
       General Public License.  If you do not have these files, write to:

            Free Software Foundation, Inc.
            51 Franklin Street
            Fifth Floor
            Boston, MA  02110-1301
            USA

       Calc is copyrighted in several different ways.  These ways include:

            Copyright (C) year  David I. Bell
            Copyright (C) year  David I. Bell and Landon Curt Noll
            Copyright (C) year  David I. Bell and Ernest Bowen
            Copyright (C) year  David I. Bell, Landon Curt Noll and Ernest Bowen
            Copyright (C) year  Landon Curt Noll
            Copyright (C) year  Ernest Bowen and Landon Curt Noll
            Copyright (C) year  Ernest Bowen
            Copyright (C) year  Petteri Kettunen and Landon Curt Noll
            Copyright (C) year  Christoph Zurnieden
            Copyright (C) year  Landon Curt Noll and Thomas Jones-Low
            Copyright (C) year  Klaus Alexander Seistrup and Landon Curt Noll

       This man page is:

            Copyright (C) 1999-2023  Landon Curt Noll

       and is covered under version 2.1 GNU Lesser General Public License.

       A few files in calc are covered under "The Unlicense".  For more
       information on this license, see:

            https://unlicense.org


CCAALLCC QQUUEESSTTIIOONNSS
       To ask the calc maintainers a general question about calc, see the output
       of the following calc command:


            ; help question

       or read the source file:


            QUESTIONS


       or visit the following URL:

            https://github.com/lcn2/calc/blob/master/QUESTIONS


BBUUGG RREEPPOORRTTSS // BBUUGG FFIIXXEESS
       To inform the calc maintainers about a bug, or to submit a bug fix, see
       the output of the following calc command:


            ; help bugs

       or read the source file:


            BUGS

       or visit the following URL:

            https://github.com/lcn2/calc/blob/master/BUGS


CCOONNTTRRIIBBUUTTIINNGG CCOODDEE TTOO CCAALLCC
       _C_a_l_c is open source.  You are welcome to contribute code to calc, or
       submit bug fixes to to calc.

       To contribute code to calc, please see see the output of the following
       calc command:


            ; help contrib


       or read the source file:


            CONTRIB-CODE

       or visit the following URL:

            https://github.com/lcn2/calc/blob/master/CONTRIB-CODE


CCAALLCC WWEEBB SSIITTEE
       Landon Noll maintains the ccaallcc web site is located at:

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

CCAALLCC SSOOUURRCCEE CCOODDEE
       The latest version of calc source code may be obtained at the following
       GitHub repo:

            https://github.com/lcn2/calc

       The very latest calc source is found at the top master branch.

       You may download the calc releases from:

            https://github.com/lcn2/calc/releases

       The releases marked ((((PPrree--rreelleeaassee)))) are beta releases.

       The most recent release that is NOT  marked ((((PPrree--rreelleeaassee)))) is the
       recommended stable release.



Share and enjoy!  :-)                 ^..^                               calc(1)

*************
* assoc
*************

NAME
    assoc - create a new association array

SYNOPSIS
    assoc()

TYPES
    return      association

DESCRIPTION
    This function returns an empty association array.

    After A = assoc(), elements can be added to the association by
    assignments of the forms

        A[a_1] = v_1
        A[a_1, a_2] = v_2
        A[a_1, a_2, a_3] = v_3
        A[a_1, a_2, a_3, a_4] = v_4

    There are no restrictions on the values of the "indices" a_i or
    the "values" v_i.

    After the above assignments, so long as no new values have been
    assigned to A[a_i], etc., the expressions A[a_1], A[a_1, a_2], etc.
    will return the values v_1, v_2, ...

    Until A[a_1], A[a_1, a_2], ... are defined as described above, these
    expressions return the null value.

    Thus associations act like matrices except that different elements
    may have different numbers (between 1 and 4 inclusive) of indices,
    and these indices need not be integers in specified ranges.

    Assignment of a null value to an element of an association does not
    delete the element, but a later reference to that element will return
    the null value as if the element is undefined.

    The elements of an association are stored in a hash table for
    quick access.  The index values are hashed to select the correct
    hash chain for a small sequential search for the element.  The hash
    table will be resized as necessary as the number of entries in
    the association becomes larger.

    The size function returns the number of elements in an association.
    This size will include elements with null values.

    Double bracket indexing can be used for associations to walk through
    the elements of the association.  The order that the elements are
    returned in as the index increases is essentially random.  Any
    change made to the association can reorder the elements, this making
    a sequential scan through the elements difficult.

    The search and rsearch functions can search for an element in an
    association which has the specified value.  They return the index
    of the found element, or a NULL value if the value was not found.

    Associations can be copied by an assignment, and can be compared
    for equality.  But no other operations on associations have meaning,
    and are illegal.

EXAMPLE
    ; A = assoc(); print A
     assoc (0 elements):

    ; A["zero"] = 0; A["one"] = 1; A["two"] = 2; A["three"] = 3;
    ; A["smallest", "prime"] = 2;
    ; print A
     assoc (5 elements);
     ["two"] = 2
     ["three"] = 3
     ["one"] = 1
     ["zero"] = 0
     ["smallest","prime"] = 2

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    isassoc, rsearch, search, size

## Copyright (C) 1999,2021  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.
##
## 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/

*************
* builtin
*************

Builtin functions

        There is a large number of built-in functions.  Many of the
        functions work on several types of arguments, whereas some only
        work for the correct types (e.g., numbers or strings).  In the
        following description, this is indicated by whether or not the
        description refers to values or numbers.  This display is generated
        by the 'show builtin' command.


	Name	Args	Description

	abs       1-2   absolute value, within accuracy b
	access    1-2   determine accessibility of file a for mode b
	acos      1-2   inverse cosine of a, within accuracy b
	acosh     1-2   inverse hyperbolic cosine of a, within accuracy b
	acot      1-2   inverse cotangent of a, within accuracy b
	acoth     1-2   inverse hyperbolic cotangent of a, within accuracy b
	acovercos 1-2   inverse coversed cosine of a, within accuracy b
	acoversin 1-2   inverse coversed sine of a, within accuracy b
	acrd      1-2   angle of unit circle chord with length a, within accuracy b
	acsc      1-2   inverse cosecant of a, within accuracy b
	acsch     1-2   inverse csch of a, within accuracy b
	aexcsc    1-2   inverse exterior cosecant of a, within accuracy b
	aexsec    1-2   inverse exterior secant of a, within accuracy b
	agd       1-2   inverse Gudermannian function
	ahacovercos 1-2   inverse half coversed cosine of a, within accuracy b
	ahacoversin 1-2   inverse half coversed sine of a, within accuracy b
	ahavercos 1-2   inverse half versed cosine of a, within accuracy b
	ahaversin 1-2   inverse half versed sine of a, within accuracy b
	append    1+    append values to end of list
	appr      1-3   approximate a by multiple of b using rounding c
	arg       1-2   argument (the angle) of complex number
	argv      0-1   calc argc or argv string
	asec      1-2   inverse secant of a, within accuracy b
	asech     1-2   inverse hyperbolic secant of a, within accuracy b
	asin      1-2   inverse sine of a, within accuracy b
	asinh     1-2   inverse hyperbolic sine of a, within accuracy b
	assoc     0     create new association array
	atan      1-2   inverse tangent of a, within accuracy b
	atan2     2-3   angle to point (b,a) within accuracy c
	atanh     1-2   inverse hyperbolic tangent of a, within accuracy b
	avercos   1-2   inverse versed cosine of a, within accuracy b
	aversin   1-2   inverse versed sine of a, within accuracy b
	avg       0+    arithmetic mean of values
	base      0-1   set default output base
	base2     0-1   set default secondary output base
	bernoulli 1     Bernoulli number for index a
	bit       2     whether bit b in value a is set
	blk       0-3   block with or without name, octet number, chunksize
	blkcpy    2-5   copy value to/from a block: blkcpy(d,s,len,di,si)
	blkfree   1     free all storage from a named block
	blocks    0-1   named block with specified index, or null value
	bround    1-3   round value a to b number of binary places
	btrunc    1-2   truncate a to b number of binary places
	calclevel 0     current calculation level
	calcpath  0     current CALCPATH search path value
	calc_tty  0     set tty for interactivity
	cas       1-2   cosine plus sine, within accuracy b
	catalan   1     catalan number for index a
	ceil      1     smallest integer greater than or equal to number
	cfappr    1-3   approximate a, within accuracy b using
				continued fractions
	cfsim     1-2   simplify number using continued fractions
	char      1     character corresponding to integer value
	cis       1-2   Euler's formula, within accuracy b
	cmdbuf    0     command buffer
	cmp       2     compare values returning -1, 0, or 1
	comb      2     combinatorial number a!/b!(a-b)!
	config    1-2   set or read configuration value
	conj      1     complex conjugate of value
	copy      2-5   copy value to/from a block: copy(s,d,len,si,di)
	cos       1-2   cosine of value a, within accuracy b
	cosh      1-2   hyperbolic cosine of a, within accuracy b
	cot       1-2   cotangent of a, within accuracy b
	coth      1-2   hyperbolic cotangent of a, within accuracy b
	count     2     count listr/matrix elements satisfying some condition
	covercos  1-2   coversed cosine of value a, within accuracy b
	coversin  1-2   coversed sine of value a, within accuracy b
	cp        2     cross product of two vectors
	crd       1-2   length of unit circle chord with angle a, within accuracy b
	csc       1-2   cosecant of a, within accuracy b
	csch      1-2   hyperbolic cosecant of a, within accuracy b
	ctime     0     date and time as string
	custom    0+    custom builtin function interface
	d2dm      3-4   convert a to b deg, c min, rounding type d

	d2dms     4-5   convert a to b deg, c min, d sec, rounding type e

	d2g       1-2   convert degrees to gradians
	d2r       1-2   convert degrees to radians
	delete    2     delete element from list a at position b
	den       1     denominator of fraction
	det       1     determinant of matrix
	digit     2-3   digit at specified decimal place of number
	digits    1-2   number of digits in base b representation of a
	display   0-1   number of decimal digits for displaying numbers
	dm2d      2-3   convert a deg, b min to degrees, rounding type c

	dms2d     3-4   convert a deg, b min, c sec to degrees, rounding type d

	dp        2     dot product of two vectors
	epsilon   0-1   set or read allowed error for real calculations
	errcount  0-1   set or read error count
	errmax    0-1   set or read maximum for error count
	errno     0-1   set or read calc_errno
	error     0-1   generate error value
	errsym    1     convert between E_STRING errsym into a errnum number
	estr      1     exact text string representation of value
	euler     1     Euler number
	eval      1     evaluate expression from string to value
	excsc     1-2   exterior cosecant of a, within accuracy b
	exp       1-2   exponential of value a, within accuracy b
	exsec     1-2   exterior secant of a, within accuracy b
	fact      1     factorial
	factor    1-3   lowest prime factor < b of a, return c if error
	fclose    0+    close file
	fcnt      2     count of times one number divides another
	feof      1     whether EOF reached for file
	ferror    1     whether error occurred for file
	fflush    0+    flush output to file(s)
	fgetc     1     read next char from file
	fgetfield 1     read next white-space delimited field from file
	fgetfile  1     read to end of file
	fgetline  1     read next line from file, newline removed
	fgets     1     read next line from file, newline is kept
	fgetstr   1     read next null-terminated string from file, null
				character is kept
	fib       1     Fibonacci number F(n)
	files     0-1   return opened file or max number of opened files
	floor     1     greatest integer less than or equal to number
	fopen     2     open file name a in mode b
	forall    2     do function for all elements of list or matrix
	fpathopen 2-3   open file name a in mode b, search for a along
				CALCPATH or path c
	fprintf   2+    print formatted output to opened file
	fputc     2     write a character to a file
	fputs     2+    write one or more strings to a file
	fputstr   2+    write one or more null-terminated strings to a file
	frac      1     fractional part of value
	free      0+    free listed or all global variables
	freebernoulli 0     free stored Bernoulli numbers
	freeeuler 0     free stored Euler numbers
	freeglobals 0     free all global and visible static variables
	freeredc  0     free redc data cache
	freestatics 0     free all un-scoped static variables
	frem      2     number with all occurrences of factor removed
	freopen   2-3   reopen a file stream to a named file
	fscan     2+    scan a file for assignments to one or
				more variables
	fscanf    2+    formatted scan of a file for assignment to one
				or more variables
	fseek     2-3   seek to position b (offset from c) in file a
	fsize     1     return the size of the file
	ftell     1     return the file position
	g2d       1-2   convert gradians to degrees
	g2gm      3-4   convert a to b grads, c min, rounding type d

	g2gms     4-5   convert a to b grads, c min, d sec, rounding type e

	g2r       1-2   convert gradians to radians
	gcd       1+    greatest common divisor
	gcdrem    2     a divided repeatedly by gcd with b
	gd        1-2   Gudermannian function
	getenv    1     value of environment variable (or NULL)
	gm2g      2-3   convert a grads, b min to grads, rounding type c

	gms2g     3-4   convert a grads, b min, c sec to grads, rounding type d

	h2hm      3-4   convert a to b hours, c min, rounding type d

	h2hms     4-5   convert a to b hours, c min, d sec, rounding type e

	hacovercos 1-2   half coversed cosine of value a, within accuracy b
	hacoversin 1-2   half coversed sine of value a, within accuracy b
	hash      1+    return non-negative hash value for one or
				more values
	havercos  1-2   half versed cosine of value a, within accuracy b
	haversin  1-2   half versed sine of value a, within accuracy b
	head      2     return list of specified number at head of a list
	highbit   1     high bit number in base 2 representation
	hm2h      2-3   convert a hours, b min to hours, rounding type c

	hmean     0+    harmonic mean of values
	hms2h     3-4   convert a hours, b min, c sec to hours, rounding type d

	hnrmod    4     v mod h*2^n+r, h>0, n>0, r  =  -1, 0 or 1
	hypot     2-3   hypotenuse of right triangle, within accuracy c
	ilog      2     integral log of a to integral base b
	ilog10    1     integral log of a number base 10
	ilog2     1     integral log of a number base 2
	ilogn     2     same is ilog
	im        1     imaginary part of complex number
	indices   2     indices of a specified assoc or mat value
	inputlevel 0     current input depth
	insert    2+    insert values c ... into list a at position b
	int       1     integer part of value
	inverse   1     multiplicative inverse of value
	iroot     2     integer b'th root of a
	isalnum   1     whether character is alpha-numeric
	isalpha   1     whether character is alphabetic
	isassoc   1     whether a value is an association
	isatty    1     whether a file is a tty
	isblk     1     whether a value is a block
	iscntrl   1     whether character is a control character
	isconfig  1     whether a value is a config state
	isdefined 1     whether a string names a function
	isdigit   1     whether character is a digit
	iserror   1     where a value is an error
	iseven    1     whether a value is an even integer
	isfile    1     whether a value is a file
	isgraph   1     whether character is a graphical character
	ishash    1     whether a value is a hash state
	isident   1     returns 1 if identity matrix
	isint     1     whether a value is an integer
	islist    1     whether a value is a list
	islower   1     whether character is lower case
	ismat     1     whether a value is a matrix
	ismult    2     whether a is a multiple of b
	isnull    1     whether a value is the null value
	isnum     1     whether a value is a number
	isobj     1     whether a value is an object
	isobjtype 1     whether a string names an object type
	isoctet   1     whether a value is an octet
	isodd     1     whether a value is an odd integer
	isprime   1-2   whether a is a small prime, return b if error
	isprint   1     whether character is printable
	isptr     1     whether a value is a pointer
	ispunct   1     whether character is a punctuation
	isqrt     1     integer part of square root
	isrand    1     whether a value is a subtractive 100 state
	israndom  1     whether a value is a Blum state
	isreal    1     whether a value is a real number
	isrel     2     whether two numbers are relatively prime
	issimple  1     whether value is a simple type
	isspace   1     whether character is a space character
	issq      1     whether or not number is a square
	isstr     1     whether a value is a string
	istype    2     whether the type of a is same as the type of b
	isupper   1     whether character is upper case
	isxdigit  1     whether character is a hexadecimal digit
	jacobi    2     -1  = > a is not quadratic residue mod b
				1  = > b is composite, or a is quad residue of b
	join      1+    join one or more lists into one list
	lcm       1+    least common multiple
	lcmfact   1     lcm of all integers up till number
	lfactor   2     lowest prime factor of a in first b primes
	links     1     links to number or string value
	list      0+    create list of specified values
	ln        1-2   natural logarithm of value a, within accuracy b
	log       1-2   base 10 logarithm of value a, within accuracy b
	log2      1-2   base 2 logarithm of value a, within accuracy b
	logn      2-3   base b logarithm of value a, within accuracy c
	lowbit    1     low bit number in base 2 representation
	ltol      1-2   leg-to-leg of unit right triangle (sqrt(1 - a^2))
	makelist  1     create a list with a null elements
	matdim    1     number of dimensions of matrix
	matfill   2-3   fill matrix with value b (value c on diagonal)
	matmax    2     maximum index of matrix a dim b
	matmin    2     minimum index of matrix a dim b
	matsum    1     sum the numeric values in a matrix
	mattrace  1     return the trace of a square matrix
	mattrans  1     transpose of matrix
	max       0+    maximum value
	memsize   1     number of octets used by the value, including overhead
	meq       3     whether a and b are equal modulo c
	min       0+    minimum value
	minv      2     inverse of a modulo b
	mmin      2     a mod b value with smallest abs value
	mne       3     whether a and b are not equal modulo c
	mod       2-3   residue of a modulo b, rounding type c
	modify    2     modify elements of a list or matrix
	name      1     name assigned to block or file
	near      2-3   sign of (abs(a-b) - c)
	newerror  0-1   create new error type with message a
	nextcand  1-5   smallest value  =  =  d mod e > a, ptest(a,b,c) true
	nextprime 1-2   return next small prime, return b if err
	norm      1     norm of a value (square of absolute value)
	null      0+    null value
	num       1     numerator of fraction
	ord       1     integer corresponding to character value
	param     1     value of parameter n (or parameter count if n
				is zero)
	perm      2     permutation number a!/(a-b)!
	pfact     1     product of primes up till number
	pi        0-1   value of pi, within accuracy a
	pix       1-2   number of primes < =  a < 2^32, return b if error
	places    1-2   places after "decimal" point (-1 if infinite)
	pmod      3     mod of a power (a ^ b (mod c))
	polar     2-3   complex value of polar coordinate (a * exp(b*1i))
	poly      1+    evaluates a polynomial given its coefficients
				or coefficient-list
	pop       1     pop value from front of list
	popcnt    1-2   number of bits in a that match b (or 1)
	power     2-3   value a raised to the power b, within accuracy c
	prevcand  1-5   largest value  =  =  d mod e < a, ptest(a,b,c) true
	prevprime 1-2   return previous small prime, return b if err
	printf    1+    print formatted output to stdout
	prompt    1     prompt for input line using value a
	protect   1-3   read or set protection level for variable
	ptest     1-3   probabilistic primality test
	push      1+    push values onto front of list
	putenv    1-2   define an environment variable
	quo       2-3   integer quotient of a by b, rounding type c
	quomod    4-5   set c and d to quotient and remainder of a
				divided by b
	r2d       1-2   convert radians to degrees
	r2g       1-2   convert radians to gradians
	rand      0-2   subtractive 100 random number [0,2^64), [0,a), or [a,b)
	randbit   0-1   subtractive 100 random number [0,2^a)
	random    0-2   Blum-Blum-Shub random number [0,2^64), [0,a), or [a,b)
	randombit 0-1   Blum-Blum-Sub random number [0,2^a)
	randperm  1     random permutation of a list or matrix
	rcin      2     convert normal number a to REDC number mod b
	rcmul     3     multiply REDC numbers a and b mod c
	rcout     2     convert REDC number a mod b to normal number
	rcpow     3     raise REDC number a to power b mod c
	rcsq      2     square REDC number a mod b
	re        1     real part of complex number
	remove    1     remove value from end of list
	reverse   1     reverse a copy of a matrix or list
	rewind    0+    rewind file(s)
	rm        1+    remove file(s), -f turns off no-such-file errors
	root      2-3   value a taken to the b'th root, within accuracy c
	round     1-3   round value a to b number of decimal places
	rsearch   2-4   reverse search matrix or list for value b
				starting at index c
	runtime   0     user and kernel mode CPU time in seconds
	saveval   1     set flag for saving values
	scale     2     scale value up or down by a power of two
	scan      1+    scan standard input for assignment to one
				or more variables
	scanf     2+    formatted scan of standard input for assignment
				to variables
	search    2-4   search matrix or list for value b starting
				at index c
	sec       1-2   secant of a, within accuracy b
	sech      1-2   hyperbolic secant of a, within accuracy b
	seed      0     return a 64 bit seed for a pseudo-random generator
	segment   2-3   specified segment of specified list
	select    2     form sublist of selected elements from list
	setbit    2-3   set specified bit in string
	sgn       1     sign of value (-1, 0, 1)
	sha1      0+    Secure Hash Algorithm (SHS-1 FIPS Pub 180-1)
	sin       1-2   sine of value a, within accuracy b
	sinh      1-2   hyperbolic sine of a, within accuracy b
	size      1     total number of elements in value
	sizeof    1     number of octets used to hold the value
	sleep     0-1   suspend operation for a seconds
	sort      1     sort a copy of a matrix or list
	sqrt      1-3   square root of value a, within accuracy b
	srand     0-1   seed the rand() function
	srandom   0-4   seed the random() function
	ssq       1+    sum of squares of values
	stoponerror 0-1   assign value to stoponerror flag
	str       1     simple value converted to string
	strcasecmp 2     compare two strings case independent
	strcat    1+    concatenate strings together
	strcmp    2     compare two strings
	strcpy    2     copy string to string
	strerror  0-1   string describing error type
	strlen    1     length of string
	strncasecmp 3     compare strings a, b to c characters case independent
	strncmp   3     compare strings a, b to c characters
	strncpy   3     copy up to c characters from string to string
	strpos    2     index of first occurrence of b in a
	strprintf 1+    return formatted output as a string
	strscan   2+    scan a string for assignments to one or more variables
	strscanf  2+    formatted scan of string for assignments to variables
	strtolower 1     Make string lower case
	strtoupper 1     Make string upper case
	substr    3     substring of a from position b for c chars
	sum       0+    sum of list or object sums and/or other terms
	swap      2     swap values of variables a and b (can be dangerous)
	system    1     call Unix command
	systime   0     kernel mode CPU time in seconds
	tail      2     retain list of specified number at tail of list
	tan       1-2   tangent of a, within accuracy b
	tanh      1-2   hyperbolic tangent of a, within accuracy b
	test      1     test that value is nonzero
	time      0     number of seconds since 00:00:00 1 Jan 1970 UTC
	trunc     1-2   truncate a to b number of decimal places
	ungetc    2     unget char read from file
	usertime  0     user mode CPU time in seconds
	vercos    1-2   versed cosine of value a, within accuracy b
	versin    1-2   versed sine of value a, within accuracy b
	version   0     calc version string
	xor       1+    logical xor


        The config function sets or reads the value of a configuration
        parameter.  The first argument is a string which names the parameter
        to be set or read.  If only one argument is given, then the current
        value of the named parameter is returned.  If two arguments are given,
        then the named parameter is set to the value of the second argument,
        and the old value of the parameter is returned.  Therefore you can
        change a parameter and restore its old value later.  The possible
        parameters are explained in the next section.

        The scale function multiplies or divides a number by a power of 2.
        This is used for fractional calculations, unlike the << and >>
        operators, which are only defined for integers.  For example,
        scale(6, -3) is 3/4.

        The quomod function is used to obtain both the quotient and remainder
        of a division in one operation.  The first two arguments a and b are
        the numbers to be divided.  The last two arguments c and d are two
        variables which will be assigned the quotient and remainder.  For
        nonnegative arguments, the results are equivalent to computing a//b
        and a%b.  If a is negative and the remainder is nonzero, then the
        quotient will be one less than a//b.  This makes the following three
        properties always hold:  The quotient c is always an integer.  The
        remainder d is always 0 <= d < b.  The equation a = b * c + d always
        holds.  This function returns 0 if there is no remainder, and 1 if
        there is a remainder.  For examples, quomod(10, 3, x, y) sets x to 3,
        y to 1, and returns the value 1, and quomod(-4, 3.14159, x, y) sets x
        to -2, y to 2.28318, and returns the value 1.

        The eval function accepts a string argument and evaluates the
        expression represented by the string and returns its value.
        The expression can include function calls and variable references.
        For example, eval("fact(3) + 7") returns 13.  When combined with
        the prompt function, this allows the calculator to read values from
        the user.  For example, x=eval(prompt("Number: ")) sets x to the
        value input by the user.

        The digit and bit functions return individual digits of a number,
        either in base 10 or in base 2, where the lowest digit of a number
        is at digit position 0.  For example, digit(5678, 3) is 5, and
        bit(0b1000100, 2) is 1.  Negative digit positions indicate places
        to the right of the decimal or binary point, so that for example,
        digit(3.456, -1) is 4.

        The ptest builtin is a primality testing function.  The
        1st argument is the suspected prime to be tested.  The
        absolute value of the 2nd argument is an iteration count.

        If ptest is called with only 2 args, the 3rd argument is
        assumed to be 0.  If ptest is called with only 1 arg, the
        2nd argument is assumed to be 1.  Thus, the following
        calls are equivalent:

                ptest(a)
                ptest(a,1)
                ptest(a,1,0)

        Normally ptest performs a some checks to determine if the
        value is divisible by some trivial prime.  If the 2nd
        argument is < 0, then the trivial check is omitted.

        For example, ptest(a,10) performs the same work as:

                ptest(a,-3)     (7 tests without trivial check)
                ptest(a,-7,3)   (3 more tests without the trivial check)

        The ptest function returns 0 if the number is definitely not
        prime, and 1 is the number is probably prime.  The chance
        of a number which is probably prime being actually composite
        is less than 1/4 raised to the power of the iteration count.
        For example, for a random number p, ptest(p, 10) incorrectly
        returns 1 less than once in every million numbers, and you
        will probably never find a number where ptest(p, 20) gives
        the wrong answer.

        The first 3 args of nextcand and prevcand functions are the same
        arguments as ptest.  But unlike ptest, nextcand and prevcand return
        the next and previous values for which ptest is true.

        For example, nextcand(2^1000) returns 2^1000+297 because
        2^1000+297 is the smallest value x > 2^1000 for which
        ptest(x,1) is true.  And for example, prevcand(2^31-1,10,5)
        returns 2147483629 (2^31-19) because 2^31-19 is the largest
        value y < 2^31-1 for which ptest(y,10,5) is true.

        The nextcand and prevcand functions also have a 5 argument form:

                nextcand(num, count, skip, modval, modulus)
                prevcand(num, count, skip, modval, modulus)

        return the smallest (or largest) value ans > num (or < num) that
        is also == modval % modulus for which ptest(ans,count,skip) is true.

        The builtins nextprime(x) and prevprime(x) return the
        next and previous primes with respect to x respectively.
        As of this release, x must be < 2^32.  With one argument, they
        will return an error if x is out of range.  With two arguments,
        they will not generate an error but instead will return y.

        The builtin function pix(x) returns the number of primes <= x.
        As of this release, x must be < 2^32.  With one argument, pix(x)
        will return an error if x is out of range.  With two arguments,
        pix(x,y) will not generate an error but instead will return y.

        The builtin function factor may be used to search for the
        smallest factor of a given number.  The call factor(x,y)
        will attempt to find the smallest factor of x < min(x,y).
        As of this release, y must be < 2^32.  If y is omitted, y
        is assumed to be 2^32-1.

        If x < 0, factor(x,y) will return -1.  If no factor <
        min(x,y) is found, factor(x,y) will return 1.  In all other
        cases, factor(x,y) will return the smallest prime factor
        of x.  Note except for the case when abs(x) == 1, factor(x,y)
        will not return x.

        If factor is called with y that is too large, or if x or y
        is not an integer, calc will report an error.  If a 3rd argument
        is given, factor will return that value instead.  For example,
        factor(1/2,b,c) will return c instead of issuing an error.

        The builtin lfactor(x,y) searches a number of primes instead
        of below a limit.  As of this release, y must be <= 203280221
        (y <= pix(2^32-1)).  In all other cases, lfactor is operates
        in the same way as factor.

        If lfactor is called with y that is too large, or if x or y
        is not an integer, calc will report an error.  If a 3rd argument
        is given, lfactor will return that value instead.  For example,
        lfactor(1/2,b,c) will return c instead of issuing an error.

        The lfactor function is slower than factor.  If possible factor
        should be used instead of lfactor.

        The builtin isprime(x) will attempt to determine if x is prime.
        As of this release, x must be < 2^32.  With one argument, isprime(x)
        will return an error if x is out of range.  With two arguments,
        isprime(x,y) will not generate an error but instead will return y.

        The functions rcin, rcmul, rcout, rcpow, and rcsq are used to
        perform modular arithmetic calculations for large odd numbers
        faster than the usual methods.  To do this, you first use the
        rcin function to convert all input values into numbers which are
        in a format called REDC format.  Then you use rcmul, rcsq, and
        rcpow to multiply such numbers together to produce results also
        in REDC format.  Finally, you use rcout to convert a number in
        REDC format back to a normal number.  The addition, subtraction,
        negation, and equality comparison between REDC numbers are done
        using the normal modular methods.  For example, to calculate the
        value 13 * 17 + 1 (mod 11), you could use:

                p = 11;
                t1 = rcin(13, p);
                t2 = rcin(17, p);
                t3 = rcin(1, p);
                t4 = rcmul(t1, t2, p);
                t5 = (t4 + t3) % p;
                answer = rcout(t5, p);

        The swap function exchanges the values of two variables without
        performing copies.  For example, after:

                x = 17;
                y = 19;
                swap(x, y);

        then x is 19 and y is 17.  This function should not be used to
        swap a value which is contained within another one.  If this is
        done, then some memory will be lost.  For example, the following
        should not be done:

                mat x[5];
                swap(x, x[0]);

        The hash function returns a relatively small non-negative integer
        for one or more input values.  The hash values should not be used
        across runs of the calculator, since the algorithms used to generate
        the hash value may change with different versions of the calculator.

        The base function allows one to specify how numbers should be
        printed.  The base function provides a numeric shorthand to the
        config("mode") interface.  With no args, base() will return the
        current mode.  With 1 arg, base(val) will set the mode according to
        the arg and return the previous mode.

        The following convention is used to declare modes:

                 base    config
                value    string

                   2    "binary"        binary fractions
                   8    "octal"         octal fractions
                  10    "real"          decimal floating point
                  16    "hex"           hexadecimal fractions
                 -10    "int"           decimal integer
                 1/3    "frac"          decimal fractions
                1e20    "exp"           decimal exponential

        For convenience, any non-integer value is assumed to mean "frac",
        and any integer >= 2^64 is assumed to mean "exp".

## Copyright (C) 1999-2017,2021  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.
##
## Under source code control:   1995/07/10 01:17:53
## 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/

*************
* command
*************

Command sequence

    This is a sequence of any the following command formats, where
    each command is terminated by a semicolon or newline.  Long command
    lines can be extended by using a back-slash followed by a newline
    character.  When this is done, the prompt shows a double angle
    bracket to indicate that the line is still in progress.  Certain
    cases will automatically prompt for more input in a similar manner,
    even without the back-slash.  The most common case for this is when
    a function is being defined, but is not yet completed.

    Each command sequence terminates only on an end of file.  In
    addition, commands can consist of expression sequences, which are
    described in the next section.


    define a function
    -----------------
    define function(params) { body }
    define function(params) = expression

        This first form defines a full function which can consist
        of declarations followed by many statements which implement
        the function.

        The second form defines a simple function which calculates
        the specified expression value from the specified parameters.
        The expression cannot be a statement.  However, the comma
        and question mark operators can be useful.      Examples of
        simple functions are:

                define sumcubes(a, b) = a^3 + b^3
                define pimod(a) = a % pi()
                define printnum(a, n, p)
                {
                    if (p == 0) {
                        print a: "^": n, "=", a^n;
                    } else {
                        print a: "^": n, "mod", p, "=", pmod(a,n,p);
                    }
                }


    read calc commands
    ------------------
    read $var
    read -once $var
    read filename
    read -once filename

        This reads definitions from the specified calc resource filename.

        In the 1st and 2nd forms, if var is a global variable string
        value, then the value of that variable is used as a filename.

        The following is equivalent to read lucas.cal or read "lucas.cal":

            global var = "lucas.cal";
            read $var;

        In the 3rd or 4th forms, the filename argument is treated
        as a literal string, not a variable.  In these forms, the
        name can be quoted if desired.

        The calculator uses the CALCPATH environment variable to
        search through the specified directories for the filename,
        similarly to the use of the PATH environment variable.
        If CALCPATH is not defined, then a default path which is
        usually ":/usr/local/lib/calc" is used.

        The ".cal" extension is defaulted for input files, so that
        if "filename" is not found, then "filename.cal" is then
        searched for.  The contents of the filename are command
        sequences which can consist of expressions to evaluate or
        functions to define, just like at the top level command level.

        When -once is given, the read command acts like the regular
        read expect that it will ignore filename if is has been
        previously read.

        The read -once form is particularly useful in a resource
        file that needs to read a 2nd resource file.  By using the
        READ -once command, one will not reread that 2nd resource
        file, nor will once risk entering into a infinite READ loop
        (where that 2nd resource file directly or indirectly does
        a READ of the first resource file).

        If the -m mode disallows opening of files for reading,
        this command will be disabled.

        To read a calc resource file without printing various
        messages about defined functions, the "resource_debug"
        config should be set to zero.  For example:

            read lucas;

        will, by default, print messages such as:

            lucas(h,n) defined
            gen_u2(h,n,v1) defined
            gen_u0(h,n,v1) defined
            rodseth_xhn(x,h,n) defined
            gen_v1(h,n) defined
            ldebug(funct,str) defined
            legacy_gen_v1(h,n) defined

        When "resource_debug" is zero, such messages are silenced.

            config("resource_debug", 0),;
            read lucas;

        To silence such messages on the calc command line, try:

            calc -p -D :0 'read -once lucas; lucas(1, 23209);'


    write calc commands
    -------------------
    write $var
    write filename

        This writes the values of all global variables to the
        specified filename, in such a way that the file can be
        later read in order to recreate the variable values.
        For speed reasons, values are written as hex fractions.
        This command currently only saves simple types, so that
        matrices, lists, and objects are not saved.      Function
        definitions are also not saved.

        In the 1st form, if var is a global variable string
        value, then the value of that variable is used as a filename.

        The following is equivalent to write dump.out or
        write "dump.out":

            global var = "dump.out";
            write $var;

        In the 2nd form, the filename argument is treated as a literal
        string, not a variable.  In this form, the name can be quoted
        if desired.

        If the -m mode disallows opening of files for writing,
        this command will be disabled.


    quit or exit
    ------------
    quit
    quit string
    exit
    exit string

        The action of these commands depends on where they are used.
        At the interactive level, they will cause calc to exit.
        This is the normal way to leave the calculator.  In any
        other use, they will stop the current calculation as if
        an error had occurred.

        If a string is given, then the string is printed as the reason
        for quitting, otherwise a general quit message is printed.
        The routine name and line number which executed the quit is
        also printed in either case.

        Exit is an alias for quit.

        Quit is useful when a routine detects invalid arguments,
        in order to stop a calculation cleanly.  For example,
        for a square root routine, an error can be given if the
        supplied parameter was a negative number, as in:

                define mysqrt(n)
                {
                    if (! isnum(n))
                        quit "non-numeric argument";
                    if (n < 0)
                        quit "Negative argument";
                    return sqrt(n);
                }

        See 'more information about abort and quit' below for
        more information.


    abort
    -----
    abort
    abort string

        This command behaves like QUIT except that it will attempt
        to return to the interactive level if permitted, otherwise
        calc exit.

        See 'more information about abort and quit' below for
        more information.


    change current directory
    ------------------------
    cd
    cd dir

        Change the current directory to 'dir'.  If 'dir' is omitted,
        change the current directory to the home directory, if $HOME
        is set in the environment.


    show information
    ----------------
    show item

        This command displays some information where 'item' is
        one of the following:

                blocks          unfreed named blocks
                builtin         built in functions
                config          config parameters and values
                constants       cache of numeric constants
                custom          custom functions if calc -C was used
                errors          new error-values created
                files           open files, file position and sizes
                function        user-defined functions
                globaltypes     global variables
                objfunctions    possible object functions
                objtypes        defined objects
                opcodes         internal opcodes for function `func'
                sizes           size in octets of calc value types
                realglobals     numeric global variables
                statics         un-scoped static variables
                numbers         calc number cache
                redcdata        REDC data defined
                strings         calc string cache
                literals        calc literal cache

        Only the first 4 characters of item are examined, so:

                show globals
                show global
                show glob

        do the same thing.


    calc help
    ---------
    help $var
    help name

        This displays a help related to 'name' or general
        help of none is given.

        In the 1st form, if var is a global variable string
        value, then the value of that variable is used as a name.

        The following is equivalent to help command or help "command":

            global var = "command";
            help $var;

        In the 2nd form, the filename argument is treated as a literal
        string, not a variable.  In this form, the name can be quoted
        if desired.


    =-=

    more information about abort and quit
    =====================================

    Consider the following calc file called myfile.cal:

        print "start of myfile.cal";
        define q() {quit "quit from q()"; print "end of q()"}
        define a() {abort "abort from a()"}
        x = 3;
        {print "start #1"; if (x > 1) q()} print "after #1";
        {print "start #2"; if (x > 1) a()} print "after #2";
        {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
        print "end of myfile.cal";

    The command:

        calc read myfile

    will produce:

        q() defined
        a() defined
        start statement #1
        quit from q()
        after statement #1
        start statement #2
        abort from a()

    The QUIT within the q() function prevented the ``end of q()''
    statement from being evaluated.  This QUIT command caused
    control to be returned to just after the place where q()
    was called.

    Notice that unlike QUIT, the ABORT inside function a() halts
    the processing of statements from the input source (myfile.cal).
    Because calc was not interactive, ABORT causes calc to exit.

    The command:

        calc -i read myfile

    will produce:

        q() defined
        a() defined
        start statement #1
        quit from q()
        after statement #1
        start statement #2
        abort from a()
        ;               <==== calc interactive prompt

    because the '-i' calc causes ABORT to drop into an
    interactive prompt.  However typing a QUIT or ABORT
    at the interactive prompt level will always calc to exit,
    even when calc is invoked with '-i'.

    Also observe that both of these commands:

        cat myfile.cal | calc
        cat myfile.cal | calc -i

    will produce:

        q() defined
        a() defined
        start statement #1
        quit from q()
        after statement #1
        start statement #2
        abort from a()

    The ABORT inside function a() halts the processing of statements
    from the input source (standard input).  Because standard input
    is not a terminal, using '-i' does not force it to drop into
    an interactive prompt.

    If one were to type in the contents of myfile.cal interactively,
    calc will produce:

        ; print "start of myfile.cal";
        start of myfile.cal
        ; define q() {quit "quit from q()"; print "end of q()"}
        q() defined
        ; define a() {abort "abort from a()"}
        a() defined
        ; x = 3;
        ; {print "start #1"; if (x > 1) q()} print "after #1";
        start statement #1
        quit from q()
        after statement #1
        ; {print "start #2"; if (x > 1) a()} print "after #2";
        start statement #2
        abort from a()
        ; {print "start #3"; if (x > 1) quit "quit from 3rd statement"}
        start #3
        quit from 3rd statement

    The ABORT from within the a() function returned control to
    the interactive level.

    The QUIT (after the if (x > 1) ...) will cause calc to exit
    because it was given at the interactive prompt level.

    =-=

    Also see the help topic:

        statement   flow control and declaration statements
        usage       how to invoke the calc command and calc -options

## Copyright (C) 1999-2006,2018,2021  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.
##
## Under source code control:   1991/07/21 04:37:17
## 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/

*************
* config
*************

NAME
    config - configuration parameters

SYNOPSIS
    config(parameter [,value])

TYPES
    parameter   string
    value       int, string, config state

    return      config state

DESCRIPTION
    The config() builtin affects how the calculator performs certain
    operations.  Among features that are controlled by these parameters
    are the accuracy of some calculations, the displayed format of results,
    the choice from possible alternative algorithms, and whether or not
    debugging information is displayed.  The parameters are
    read or set using the "config" built-in function; they remain in effect
    until their values are changed by a config or equivalent instruction.

    The following parameters can be specified:

            "all"               all configuration values listed below

            "trace"             turns tracing features on or off
            "display"           sets number of digits in prints.
            "epsilon"           sets error value for transcendental.
            "maxprint"          sets maximum number of elements printed.
            "mode"              sets printout mode.
            "mode2"             sets 2nd base printout mode.
            "mul2"              sets size for alternative multiply.
            "sq2"               sets size for alternative squaring.
            "pow2"              sets size for alternate powering.
            "redc2"             sets size for alternate REDC.
            "tilde"             enable/disable printing of the roundoff '~'
            "tilde_space"       enable/disable printing space after roundoff tilde '~ '
            "tab"               enable/disable printing of leading tabs
            "quomod"            sets rounding mode for quomod
            "quo"               sets rounding mode for //, default for quo
            "mod"               sets "rounding" mode for %, default for mod
            "sqrt"              sets rounding mode for sqrt
            "appr"              sets rounding mode for appr
            "cfappr"            sets rounding mode for cfappr
            "cfsim"             sets rounding mode for cfsim
            "round"             sets rounding mode for round and bround
            "triground"         sets rounding mode for trigonometric and hyperbolic functions
            "outround"          sets rounding mode for printing of numbers
            "leadzero"          enables/disables printing of 0 as in 0.5
            "fullzero"          enables/disables padding zeros as in 0.5000
            "maxscan"           maximum number of scan errors before abort
            "prompt"            default interactive prompt
            "more"              default interactive multi-line input prompt
            "blkmaxprint"       number of block octets to print, 0 means all
            "blkverbose"        TRUE => print all lines, FALSE=>skip duplicates
            "blkbase"           block output base
            "blkfmt"            block output format
            "calc_debug"        controls internal calc debug information
            "resource_debug"    controls resource file debug information
            "user_debug"        for user defined debug information
            "verbose_quit"      TRUE => print message on empty quit or abort
            "ctrl_d"            The interactive meaning of ^D (Control D)
            "program"           Read-only calc program or shell script path
            "basename"          Read-only basename of the program value
            "windows"           Read-only indicator of MS windows
            "cygwin"            TRUE=>calc compiled with cygwin, Read-only
            "compile_custom"    TRUE=>calc was compiled with custom functions
            "allow_custom"      TRUE=>custom functions are enabled
            "version"           Read-only calc version
            "baseb"             bits in calculation base, a read-only value
            "redecl_warn"       TRUE => warn when redeclaring
            "dupvar_warn"       TRUE => warn when variable names collide
            "hz"                Read-only operating system tick rate or 0

    The "all" config value allows one to save/restore the configuration
    set of values.  The return of:

            config("all")

    is a CONFIG type which may be used as the 2rd arg in a later call.
    One may save, modify and restore the configuration state as follows:

            oldstate = config("all")
            ...
            config("tab", 0)
            config("mod", 10)
            ...
            config("all", oldstate)

    This save/restore method is useful within functions.
    It allows functions to control their configuration without impacting
    the calling function.

    There are two configuration state aliases that may be set.  To
    set the backward compatible standard configuration:

            config("all", "oldstd")

    The "oldstd" will restore the configuration to the default at startup.

    A new configuration that some people prefer may be set by:

            config("all", "newstd")

    The "newstd" is not backward compatible with the historic
    configuration.  Even so, some people prefer this configuration
    and place the config("all", "newstd") command in their CALCRC
    startup files; newstd may also be established by invoking calc
    with the flag -n.

    The following are synonyms for true:

            "on"
            "true"
            "t"
            "yes"
            "y"
            "set"
            "1"
            any non-zero number

    The following are synonyms for false:

            "off"
            "false"
            "f"
            "no"
            "n"
            "unset"
            "0"
            the number zero (0)

    Examples of setting some parameters are:

            config("mode", "exp");          exponential output
            config("display", 50);          50 digits of output
            epsilon(epsilon() / 8);         3 bits more accuracy
            config("tilde", 0)              disable roundoff tilde printing
            config("tilde_space", 1)        enable printing space after roundoff tilde
            config("tab", "off")            disable leading tab printing

    =-=

    config("trace", bitflag)

    When nonzero, the "trace" parameter activates one or more features
    that may be useful for debugging.  These features correspond to
    powers of 2 which contribute additively to config("trace"):

        1: opcodes are displayed as functions are evaluated

        2: disables the inclusion of debug lines in opcodes for functions
           whose definitions are introduced with a left-brace.

        4: the number of links for real and complex numbers are displayed
           when the numbers are printed; for real numbers "#" or for
           complex numbers "##", followed by the number of links, are
           printed immediately after the number.

        8: the opcodes for a new functions are displayed when the function
           is successfully defined.

    See also resource_debug, calc_debug and user_debug below for more
    debug levels.

    =-=

    config("display", int)

    The "display" parameter specifies the maximum number of digits after
    the decimal point to be printed in real, exponential or engineering
    mode in normal unformatted printing (print, strprint, fprint) or in
    formatted printing (printf, strprintf, fprintf) when precision is not
    specified.  The initial value for oldstd is 20, for newstd 10.
    The parameter may be changed to the value d by either
    config("display", d) or by display (d).  This parameter does not change
    the stored value of a number.  Where rounding is necessary to
    display up to d decimal places, the type of rounding to be used is
    controlled by config("outround").

    =-=

    config("epsilon", real)
    epsilon(real)

    The "epsilon" parameter specifies the default accuracy for the
    calculation of functions for which exact values are not possible or
    not desired.  For most functions, the

                remainder = exact value - calculated value

    has absolute value less than epsilon, but, except when the sign of
    the remainder is controlled by an appropriate parameter, the
    absolute value of the remainder usually does not exceed epsilon/2.
    Functions which require an epsilon value accept an
    optional argument which overrides this default epsilon value for
    that single call.  The value v can be assigned to the "epsilon"
    parameter by either config("epsilon", v) or epsilon(v); each of
    these functions return the current epsilon value; config("epsilon")
    or epsilon() returns but does not change the epsilon value.
    For the transcendental functions and the functions sqrt() and
    appr(), the calculated value is always a multiple of epsilon.

    =-=

    config("mode", "mode_string")
    config("mode2", "mode_string")

    The "mode" parameter is a string specifying the mode for printing of
    numbers by the unformatted print functions, and the default
    ("%d" specifier) for formatted print functions.  The initial mode
    is "real".  The available modes are:

          config("mode")        meaning                         equivalent
              string                                            base() call

            "binary"            base 2 fractions                base(2)
            "bin"

            "octal"             base 8 fractions                base(8)
            "oct"

            "real"              base 10 floating point          base(10)
            "float"
            "default"

            "integer"           base 10 integer                 base(-10)
            "int"

            "hexadecimal"       base 16 fractions               base(16)
            "hex"

            "fraction"          base 10 fractions               base(1/3)
            "frac"

            "scientific"        base 10 scientific notation     base(1e20)
            "sci"
            "exp"

            "engineering"       base 10 notation with exponent  base(10e6)
            "eng"               multiple of 3

    Where multiple strings are given, the first string listed is what
    config("mode") will return.

    The "mode2" controls the double base output.  When set to a value
    other than "off", calc outputs files in both the "base" mode as
    well as the "base2" mode.  The "mode2" value may be any of the
    "mode" values with the addition of:

            "off"               disable 2nd base output mode    base2(0)

    The base() builtin function sets and returns the "mode" value.
    The base2() builtin function sets and returns the "mode2" value.

    The default "mode" is "real".  The default "mode2" is "off".

    =-=

    config("maxprint", int)

    The "maxprint" parameter specifies the maximum number of elements to
    be displayed when a matrix or list is printed.  The initial value is 16.

    =-=

    config("mul2", int)
    config("sq2", int)

    Both "mul2" and "sq2" specify the sizes of numbers at which calc switches
    from its first to its second algorithm for multiplying and squaring.
    The first algorithm is the usual method of cross multiplying, which
    runs in a time of O(N^2).  The second method is a recursive and
    complicated method which runs in a time of O(N^1.585).  The argument
    for these parameters is the number of binary words at which the
    second algorithm begins to be used.  The minimum value is 2, and
    the maximum value is very large.  If 2 is used, then the recursive
    algorithm is used all the way down to single digits, which becomes
    slow since the recursion overhead is high.  If a number such as
    1000000 is used, then the recursive algorithm is almost never used,
    causing calculations for large numbers to slow down.

    Units refer to internal calculation digits where each digit
    is BASEB bits in length.  The value of BASEB is returned by
    config("baseb").

    The default value for config("sq2") is 3388.  This default was
    established on a 1.8GHz AMD 32-bit CPU of ~3406 BogoMIPS when
    the two algorithms are about equal in speed.  For that CPU test,
    config("baseb") was 32.  This means that by default numbers up to
    (3388*32)+31 = 108447 bits in length (< 32645 decimal digits) use
    the 1st algorithm, for squaring.

    The default value for config("mul2") is 1780.  This default was
    established on a 1.8GHz AMD 32-bit CPU of ~3406 BogoMIPS when
    the two algorithms are about equal in speed.  For that CPU test,
    config("baseb") was 32.  This means that by default numbers up to
    (1779*32)+31 = 56927 bits in length (< 17137 decimal digits) use
    the 1st algorithm, for multiplication.

    A value of zero resets the parameter back to their default values.

    The value of 1 and values < 0 are reserved for future use.

    Usually there is no need to change these parameters.

    =-=

    config("pow2", int)

    The "pow2" specifies the sizes of numbers at which calc switches from
    its first to its second algorithm for calculating powers modulo
    another number.  The first algorithm for calculating modular powers
    is by repeated squaring and multiplying and dividing by the modulus.
    The second method uses the REDC algorithm given by Peter Montgomery
    which avoids divisions.  The argument for pow2 is the size of the
    modulus at which the second algorithm begins to be used.

    Units refer to internal calculation digits where each digit
    is BASEB bits in length.  The value of BASEB is returned by
    config("baseb").

    The default value for config("pow2") is 176.  This default was
    established on a 1.8GHz AMD 32-bit CPU of ~3406 BogoMIPS when
    the two algorithms are about equal in speed.  For that CPU test,
    config("baseb") was 32.  This means that by default numbers up to
    (176*32)+31 = 5663 bits in length (< 1704 decimal digits) use the
    1st algorithm, for calculating powers modulo another number.

    A value of zero resets the parameter back to their default values.

    The value of 1 and values < 0 are reserved for future use.

    Usually there is no need to change these parameters.

    =-=

    config("redc2", int)

    The "redc2" specifies the sizes of numbers at which calc switches from
    its first to its second algorithm when using the REDC algorithm.
    The first algorithm performs a multiply and a modular reduction
    together in one loop which runs in O(N^2).  The second algorithm
    does the REDC calculation using three multiplies, and runs in
    O(N^1.585).  The argument for redc2 is the size of the modulus at
    which the second algorithm begins to be used.

    Units refer to internal calculation digits where each digit
    is BASEB bits in length.  The value of BASEB is returned by
    config("baseb").

    The default value for config("redc2") is 220.  This default was
    established as 5/4 (the historical ratio of config("pow2") to
    config("pow2")) of the config("pow2") value.  This means that if
    config("baseb") is 32, then by default numbers up to (220*32)+31 =
    7071 bits in length (< 2128 decimal digits) use the REDC algorithm,
    for calculating powers modulo another number.

    A value of zero resets the parameter back to their default values.

    The value of 1 and values < 0 are reserved for future use.

    Usually there is no need to change these parameters.

    =-=

    config("tilde", boolean)

    The "tilde" controls whether or not a leading tilde ('~') is
    printed to indicate that a number has not been printed exactly
    because the number of decimal digits required would exceed the
    specified maximum number.

    If config("tilde") is false, then config("tilde_space") has no effect.

    The initial "tilde" value is 1 (on).

    =-=

    config("tilde_space", boolean)

    The "tilde_space" controls whether or not a space (' ') is
    printed after leading tilde ('~').  See config("tilde") above.
    If config("tilde") is false, then config("tilde_space") has no effect.

    NOTE: Use of config("tilde_space", 1) can break printing and scanning
          of complex values via "%c".

    The initial "tilde_space" value is 0 (off)

    =-=

    config("fraction_space", boolean)

    The "fraction_space" controls whether or not a space (' ') is
    printed both before and after '/' when printing a fraction.

    NOTE: Use of config("fraction_space", 1) can break printing and scanning
          of fractional values via "%r".

    NOTE: Use of config("fraction_space", 1) can break printing and scanning
          of complex values via "%c".

    The initial "fraction_space" value is 0 (off).

    =-=

    config("tab", boolean)

    config("tab") controls the printing of a tab before results
    automatically displayed when working interactively.  It does not
    affect the printing by the functions print, printf, etc.  The initial
    "tab" value is 1.

    =-=

    config("quomod", bitflag)
    config("quo", bitflag)
    config("mod", bitflag)
    config("sqrt", bitflag)
    config("appr", bitflag)
    config("cfappr", bitflag)
    config("cfsim", bitflag)
    config("outround", bitflag)
    config("round", bitflag)
    config("triground", bitflag)

    The "quomod", "quo", "mod", "sqrt", "appr", "cfappr", "cfsim", and
    "round" control the way in which any necessary rounding occurs.
    Rounding occurs when for some reason, a calculated or displayed
    value (the "approximation") has to differ from the "true value",
    e.g. for quomod and quo, the quotient is to be an integer, for sqrt
    and appr, the approximation is to be a multiple of an explicit or
    implicit "epsilon", for round and bround (both controlled by
    config("round")) the number of decimal places or fractional bits
    in the approximation is limited.  Zero value for any of these
    parameters indicates that the true value is greater than the approximation,
    i.e. the rounding is "down", or in the case of mod, that the
    residue has the same sign as the divisor.  If bit 4 of the
    parameter is set, the rounding of to the nearest acceptable candidate
    when this is uniquely determined; in the remaining ambiguous cases,
    the type of rounding is determined by the lower bits of the parameter
    value.  If bit 3 is set, the rounding for quo, appr and sqrt,
    is to the nearest even integer or the nearest even multiple of epsilon,
    and for round to the nearest even "last decimal place".  The effects
    of the 3 lowest bits of the parameter value are as follows:

        Bit 0: Unconditional reversal (down to up, even to odd, etc.)
        Bit 1: Reversal if the exact value is negative
        Bit 2: Reversal if the divisor or epsilon is negative

    (Bit 2 is irrelevant for the functions round and bround since the
    equivalent epsilon (a power of 1/10 or 1/2) is always positive.)

    For quomod, the quotient is rounded to an integer value as if
    evaluating quo with config("quo") == config("quomod").  Similarly,
    quomod and mod give the same residues if config("mod") == config("quomod").

    For the sqrt function, if bit 5 of config("sqrt") is set, the exact
    square-root is returned when this is possible; otherwise the
    result is rounded to a multiple of epsilon as determined by the
    five lower order bits.  Bit 6 of config("sqrt") controls whether the
    principal or non-principal square-root is returned.

    For the functions cfappr and cfsim, whether the "rounding" is down
    or up, etc. is controlled by the appropriate bits of config("cfappr")
    and config("cfsim") as for quomod, quo, etc.

    The "outround" parameter determines the type of rounding to be used
    by the various kinds of printing to the output: bits 0, 1, 3 and 4
    are used in the same way as for the functions round and bround.

    The C language method of modulus and integer division is:

            config("quomod", 2)
            config("quo", 2)
            config("mod", 2)

    The config("triground") controls rounding for the following
    trigonometric and hyperbolic functions:

        sin, cos, tan, cot, sec, csc
        asin, acos, atan, acot, asec, acsc
        versin, coversin, vercos, covercos
        aversin, acoversin, avercos, acovercos
        haversin, hacoversin, havercos, hacovercos
        ahaversin, hacoversin, havercos, ahacovercos
        exsec, aexsec, excsc, aexcsc
        crd, acrd
        cas, cis
        sinh, cosh, tanh, coth, sech, csch
        asinh, acosh, atanh, acoth, asech, acsch

    In addition to taking a complex root (such as via the power
    function on a complex value), "triground" is used for:

        exp, polar

    For the above mentioned functions, the rounding mode used to
    round the result to the nearest epsilon value is controlled by,
    and defaults to:

        config("triground", 24)

    As with other config options, the call returns the previous mode,
    without a 2nd argument, returns the current mode without changing it:

        config("triground")

    =-=

    config("leadzero", boolean)

    The "leadzero" parameter controls whether or not a 0 is printed
    before the decimal point in non-zero fractions with absolute value
    less than 1, e.g. whether 1/2 is printed as 0.5 or .5.   The
    initial value is 0, corresponding to the printing .5.

    =-=

    config("fullzero", boolean)

    The "fullzero" parameter controls whether or not in decimal floating-
    point printing, the digits are padded with zeros to reach the
    number of digits specified by config("display") or by a precision
    specification in formatted printing.  The initial value for this
    parameter is 0, so that, for example, if config("display") >= 2,
    5/4 will print in "real" mode as 1.25.

    =-=

    config("maxscan", int)

    The maxscan value controls how many scan errors are allowed
    before the compiling phase of a computation is aborted.  The initial
    value of "maxscan" is 20.  Setting maxscan to 0 disables this feature.

    =-=

    config("prompt", str)

    The default prompt when in interactive mode is "> ".  One may change
    this prompt to a more cut-and-paste friendly prompt by:

            config("prompt", "; ")

    On windowing systems that support cut/paste of a line, one may
    cut/copy an input line and paste it directly into input.  The
    leading ';' will be ignored.

    =-=

    config("more", str)

    When inside multi-line input, the more prompt is used.  One may
    change it by:

            config("more", ";; ")

    =-=

    config("blkmaxprint", int)

    The "blkmaxprint" config value limits the number of octets to print
    for a block.  A "blkmaxprint" of 0 means to print all octets of a
    block, regardless of size.

    The default is to print only the first 256 octets.

    =-=

    config("blkverbose", boolean)

    The "blkverbose" determines if all lines, including duplicates
    should be printed.  If TRUE, then all lines are printed.  If false,
    duplicate lines are skipped and only a "*" is printed in a style
    similar to od.  This config value has not meaning if "blkfmt" is "str".

    The default value for "blkverbose" is FALSE: duplicate lines are
    not printed.

    =-=

    config("blkbase", "blkbase_string")

    The "blkbase" determines the base in which octets of a block
    are printed.  Possible values are:

        "hexadecimal"           Octets printed in 2 digit hex
        "hex"
        "default"

        "octal"                 Octets printed in 3 digit octal
        "oct"

        "character"             Octets printed as chars with non-printing
        "char"                      chars as \123 or \n, \t, \r

        "binary"                Octets printed as 0 or 1 chars
        "bin"

        "raw"                   Octets printed as is, i.e. raw binary
        "none"

    Where multiple strings are given, the first string listed is what
    config("blkbase") will return.

    The default "blkbase" is "hexadecimal".

    =-=

    config("blkfmt", "blkfmt_string")

    The "blkfmt" determines for format of how block are printed:

        "lines"         print in lines of up to 79 chars + newline
        "line"

        "strings"       print as one long string
        "string"
        "str"

        "od_style"      print in od-like format, with leading offset,
        "odstyle"          followed by octets in the given base
        "od"

        "hd_style"      print in hex dump format, with leading offset,
        "hdstyle"          followed by octets in the given base, followed
        "hd"               by chars or '.' if no-printable or blank
        "default"

    Where multiple strings are given, the first string listed is what
    config("blkfmt") will return.

    The default "blkfmt" is "hd_style".

    =-=

    config("calc_debug", bitflag)

    The "calc_debug" is intended for controlling internal calc routines
    that test its operation, or collect or display information that
    might be useful for debug purposes.  Much of the output from these
    will make sense only to calc wizards.   Zero value (the default for
    both oldstd and newstd) of config("resource_debug") corresponds to
    switching off all these routines.  For nonzero value, particular
    bits currently have the following meanings:

        n               Meaning of bit n of config("calc_debug")

        0       outputs shell commands prior to execution

        1       outputs currently active functions when a quit instruction
                is executed

        2       some details of hash states are included in the output
                when these are printed

        3       when a function constructs a block value, tests are
                made that the result has the properties required for use of
                that block, e.g. that the pointer to the start of the
                block is not NULL, and that its "length" is not negative.
                A failure will result in a runtime error.

        4       Report on changes to the state of stdin as well as changes
                to internal variables that control the setting and restoring
                of stdin.

        5       Report on changes to the run state of calc.

        6       Report on rand() subtractive 100 shuffle generator issues.

        7       Report on custom function issues.

    Bits >= 8 are reserved for future use and should not be used at this time.

    By default, "calc_debug" is 0.  The initial value may be overridden
    by the -D command line option.

    =-=

    config("resource_debug", bitflag)
    config("lib_debug", bitflag)

    The "resource_debug" parameter is intended for controlling the possible
    display of special information relating to functions, objects, and
    other structures created by instructions in calc scripts.
    Zero value of config("resource_debug") means that no such information
    is displayed.  For other values, the non-zero bits which currently
    have meanings are as follows:

        n               Meaning of bit n of config("resource_debug")

        0       When a function is defined, redefined or undefined at
                interactive level, a message saying what has been done
                is displayed.

        1       When a function is defined, redefined or undefined during
                the reading of a file, a message saying what has been done
                is displayed.

        2       Show func will display more information about a functions
                arguments and argument summary information.

        3       During execution, allow calc standard resource files
                to output additional debugging information.

    The value for config("resource_debug") in both oldstd and newstd
    is 3, but if calc is invoked with the -d flag, its initial value
    is zero.  Thus, if calc is started without the -d flag, until
    config("resource_debug") is changed, a message will be output when
    a function is defined either interactively or during the reading of
    a file.

    The name config("lib_debug") is equivalent to config("resource_debug")
    and is included for backward compatibility.

    By default, "resource_debug" is 3.  The -d flag changes this default to 0.
    The initial value may be overridden by the -D command line option.

    =-=

    config("user_debug", int)

    The "user_debug" is provided for use by users.  Calc ignores this value
    other than to set it to 0 by default (for both "oldstd" and "newstd").
    No calc code or standard resource should change this value.  Users
    should feel free to use it in any way.   In particular they may
    use particular bits for special purposes as with "calc_debug", or
    they may use it to indicate a debug level with larger values
    indicating more stringent and more informative tests with presumably
    slower operation or more memory usage, and a particular value (like
    -1 or 0) corresponding to "no tests".

    By default, "user_debug" is 0.  The initial value may be overridden
    by the -D command line option.

    =-=

    config("verbose_quit", boolean)

    The "verbose_quit" controls the print of the message:

        quit or abort executed

    when a non-interactive quit or abort without an argument is encountered.
    A quit of abort without an argument does not display a message when
    invoked at the interactive level.

    By default, "verbose_quit" is false.

    =-=

    config("ctrl_d", "ctrl_d_string")

    For calc that is using the calc binding (not GNU-readline) facility:

        The "ctrl_d" controls the interactive meaning of ^D (Control D):

            "virgin_eof"  If ^D is the only character that has been typed
            "virgineof"   on a line, then calc will exit.  Otherwise ^D
            "virgin"      will act according to the calc binding, which
            "default"     by default is a Emacs-style delete-char.

            "never_eof"   The ^D never exits calc and only acts according
            "nevereof"    calc binding, which by default is a Emacs-style
            "never"       delete-char.

            "empty_eof"   The ^D always exits calc if typed on an empty line.
            "emptyeof"    This condition occurs when ^D either the first
            "empty"       character typed, or when all other characters on
                          the line have been removed (say by deleting them).

        Where multiple strings are given, the first string listed is what
        config("ctrl_d") will return.

        Note that config("ctrl_d") actually controls each and every character
        that is bound to ``delete_char''.  By default, ``delete_char'' is
        Control D.  Any character(s) bound to ``delete_char'' will cause calc
        to exit (or not exit) as directed by config("ctrl_d").

        See the ``binding'' help for information on the default calc bindings.

        The default "ctrl_d", without GNU-readline is "virgin_eof".

    For calc that was compiled with the GNU-readline facility:

        The "ctrl_d" controls the interactive meaning of ^D (Control D):

            "virgin_eof"  Same as "empty_eof"
            "virgineof"
            "virgin"
            "default"

            "never_eof"   The ^D never exits calc and only acts according
            "nevereof"    calc binding, which by default is a Emacs-style
            "never"       delete-char.

            "empty_eof"   The ^D always exits calc if typed on an empty line.
            "emptyeof"    This condition occurs when ^D either the first
            "empty"       character typed, or when all other characters on

        Where multiple strings are given, the first string listed is what
        config("ctrl_d") will return.

        The default "ctrl_d", with GNU-readline is effectively "empty_eof".

        Literally it is "virgin_eof", but since "virgin_eof" is the
        same as "empty_eof", the default is effectively "empty_eof".

    Emacs users may find the default behavior objectionable, particularly
    when using the GNU-readline facility.  Such users may want to add the line:

        config("ctrl_d", "never_eof"),;

    to their ~/.calcrc startup file to prevent ^D from causing calc to exit.

    =-=

    config("program")           <== NOTE: This is a read-only config value

    The full path to the calc program, or the calc shell script can be
    obtained by:

        config("program")

    This config parameter is read-only and cannot be set.

    =-=

    config("basename")          <== NOTE: This is a read-only config value

    The calc program, or the calc shell script basename can be obtained by:

        config("basename")

    The config("basename") is the config("program") without any leading
    path.  If config("program") has a / in it, config("basename") is
    everything after the last /, otherwise config("basename") is the
    same as config("program").

    This config parameter is read-only and cannot be set.

    =-=

    config("windows")           <== NOTE: This is a read-only config value

    Returns TRUE if you are running on a MS windows system, false if you
    are running on an operating system that does not hate you.

    This config parameter is read-only and cannot be set.

    =-=

    config("cygwin")            <== NOTE: This is a read-only config value

    Returns TRUE if you calc was compiled with cygwin, false otherwise.

    This config parameter is read-only and cannot be set.

    =-=

    config("compile_custom")    <== NOTE: This is a read-only config value

    Returns TRUE if you calc was compiled with -DCUSTOM.  By default,
    the calc Makefile uses ALLOW_CUSTOM= -DCUSTOM so by default
    config("compile_custom") is TRUE.  If, however, calc is compiled
    with ALLOW_CUSTOM="-UCUSTOM", then config("compile_custom") will be FALSE.

    The config("compile_custom") value is only affected by compile
    flags.   The calc -D runtime command line option does not change
    the config("compile_custom") value.

    See also config("allow_custom").

    This config parameter is read-only and cannot be set.

    =-=

    config("allow_custom")      <== NOTE: This is a read-only config value

    Returns TRUE if you custom functions are enabled.  To allow the use
    of custom functions, calc must be compiled with -DCUSTOM (which it
    is by default) AND calc run be run with the -D runtime command line
    option (which it is not by default).

    If config("allow_custom") is TRUE, then custom functions are allowed.
    If config("allow_custom") is FALSE, then custom functions are not
    allowed.

    See also config("compile_custom").

    This config parameter is read-only and cannot be set.

    =-=

    config("version")           <== NOTE: This is a read-only config value

    The version string of the calc program can be obtained by:

        config("version")

    This config parameter is read-only and cannot be set.

    =-=

    config("baseb")             <== NOTE: This is a read-only config value

    Returns the number of bits in the fundamental base in which
    internal calculations are performed.  For example, a value of
    32 means that calc will perform many internal calculations in
    base 2^32 with digits that are 32 bits in length.

    For libcalc programmers, this is the value of BASEB as defined
    in the zmath.h header file.

    This config parameter is read-only and cannot be set.

    =-=

    config("redecl_warn", boolean)

    Config("redecl_warn") controls whether or not a warning is issued
    when redeclaring variables.

    The initial "redecl_warn" value is 1.

    =-=

    config("dupvar_warn", boolean)

    Config("dupvar_warn") controls whether or not a warning is issued
    when a variable name collides with an exist name of a higher scope.
    Examples of collisions are when:

        * both local and static variables have the same name
        * both local and global variables have the same name
        * both function parameter and local variables have the same name
        * both function parameter and global variables have the same name

    The initial "redecl_warn" value is 1.

    =-=

    config("hz")                <== NOTE: This is a read-only config value

    Returns the rate at which the operating system advances the clock
    on POSIX based systems.  Returns 0 on non-POSIX based systems.
    The non-zero value returned is in Hertz.

    This config parameter is read-only and cannot be set.

EXAMPLE
    ; current_cfg = config("all");
    ; config("tilde", off),;
    ; config("calc_debug", 15),;
    ; config("all") == current_cfg
        0
    ; config("all", current_cfg),;
    ; config("all") == current_cfg
        1

    ; config("version")
                "2.12.0"

    ; config("all")
        mode            "real"
        mode2           "off"
        display         20
        epsilon         0.00000000000000000001
        trace           0
        maxprint        16
        mul2            20
        sq2             20
        pow2            40
        redc2           50
        tilde           1
        tilde_space     0
        tab             1
        quomod          0
        quo             2
        mod             0
        sqrt            24
        appr            24
        cfappr          0
        cfsim           8
        outround        24
        round           24
        leadzero        1
        fullzero        0
        maxscan         20
        prompt          "; "
        more            ";; "
        blkmaxprint     256
        blkverbose      0
        blkbase         "hexadecimal"
        blkfmt          "hd_style"
        resource_debug  3
        lib_debug       3
        calc_debug      0
        user_debug      0
        verbose_quit    0
        ctrl_d          "virgin_eof"
        program         "calc"
        basename        "calc"
        windows         0
        cygwin          0
        compile_custom  1
        allow_custom    0
        version         "2.12.0"
        baseb           32
        redecl_warn     1
        dupvar_warn     1
        hz              100
        fraction_space     0

    ; display()
        20
    ; config("display", 50),;
    ; display()
        50

    ; /*
       * NOTE: When displaying many digits after the decimal point
       *       be sure to set display(digits) (see 'help display') to
       *       large enough AND to set epsilon(eps) (see 'help epsilon')
       *       small enough (or if the function has a esp argument,
       *       give a eps argument that is small enough) to display
       *       the value correctly.
       */
    ; config("tilde", 1),;

    ; ## NOTE: display has too few digits and epsilon is not small enough

    ; config("display", 12),;           /* or display(12),; */
    ; printf("%f\n", pi(1e-10));
    3.1415926536
    ; config("epsilon", 1e-10),;        /* or epsilon(1e-10),; */
    ; printf("%f\n", pi());
    3.1415926536

    ; ## NOTE: display has too few digits yet epsilon is small enough

    ; config("display", 12),;           /* or display(12),; */
    ; printf("%f\n", pi(1e-72));
    ~3.141592653590
    ; config("epsilon", 1e-72),;        /* or epsilon(1e-72),; */
    ; printf("%f\n", pi());
    ~3.141592653590

    ; ## NOTE: display has enough digits but epsilon is not small enough

    ; config("display", 72),;           /* or display(72),; */
    ; printf("%f\n", pi(1e-10));
    3.1415926536
    ; config("epsilon", 1e-10),;        /* or epsilon(1e-10),; */
    ; printf("%f\n", pi());
    3.1415926536

    ; ## NOTE: display has enough digits and epsilon is small enough

    ; config("display", 72),;           /* or display(72),; */
    ; printf("%f\n", pi(1e-72));
    3.141592653589793238462643383279502884197169399375105820974944592307816406
    ; config("epsilon", 1e-72),;        /* or epsilon(1e-72),; */
    ; printf("%f\n", pi());
    3.141592653589793238462643383279502884197169399375105820974944592307816406

LIMITS
    0 < epsilon < 1

LINK LIBRARY
     none

SEE ALSO
     custom, custom_cal, display, epsilon, fprintf, printf, strprintf, usage

## Copyright (C) 1999-2007,2018,2021,2023  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.
##
## Under source code control:   1991/07/21 04:37:17
## 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/

*************
* custom
*************

NAME
    custom - custom builtin interface

SYNOPSIS
    custom([custname [, arg ...]])

TYPES
    custname    string
    arg         any

    return      any

DESCRIPTION
    This function will invoke the custom function interface.  Custom
    functions are accessed by the custname argument.  The remainder
    of the args, if any, are passed to the custom function.  The
    custom function may return any value, including null.  Calling
    custom with no args is equivalent to the command 'show custom'.

    In order to use the custom interface, two things must happen:

        1) Calc must be built to allow custom functions.  By default,
           the master Makefile is shipped with ALLOW_CUSTOM= -DCUSTOM
           which causes custom functions to be compiled in.

        2) Calc must be invoked with an argument of -C as in:

                calc -C

    In other words, explicit action must be taken in order to
    enable the use of custom functions.  By default (no -C arg)
    custom functions are compiled in but disabled so that only
    portable calc scripts may be used.

    The main focus for calc is to provide a portable platform for
    multi-precision calculations in a C-like environment.  You should
    consider implementing algorithms in the calc language as a first
    choice.  Sometimes an algorithm requires use of special hardware, a
    non-portable OS or pre-compiled C library.  In these cases a custom
    interface may be needed.

    The custom function interface is intended to make is easy for
    programmers to add functionality that would be otherwise
    un-suitable for general distribution.  Functions that are
    non-portable (machine, hardware or OS dependent) or highly
    specialized are possible candidates for custom functions.

    To add a new custom function requires access to calc source.
    For information on how to add a new custom function, try:

            help new_custom

    To serve as examples, calc is shipped with a few custom functions.
    If calc if invoked with -C, then either of the following will
    display information about the custom functions that are available:

            show custom
    or:

            custom()

    A few resource files that uses these function are also provided
    to serve as usage examples.

    We welcome submissions for new custom functions.  For information
    on how to submit new custom functions for general distribution, see:

            help contrib

EXAMPLE
    If calc compiled with ALLOW_CUSTOM="-UCUSTOM", the custom system
    is disabled, even when -C is used on the command line:

    ; print custom("sysinfo", "baseb")
            Calc was built with custom functions disabled
    Error E_NO_C_ARG

    If calc compiled with ALLOW_CUSTOM= -DCUSTOM and is invoked without -C:

    ; print custom("sysinfo", "baseb")
            Calc must be run with a -C argument to use custom function
    Error E_NO_C_ARG

    If calc compiled with ALLOW_CUSTOM= -DCUSTOM and is invoked with -C:

    ; print custom("sysinfo", "baseb")
    32

LIMITS
    By default, custom is limited to 100 args.

LINK LIBRARY
    none

SEE ALSO
    custom_cal, new_custom, contrib

## Copyright (C) 1999,2023  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.
##
## 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/

*************
* define
*************

NAME
    define - command keyword to start a function definition

SYNTAX
    define fname([param_1 [= default_1], ...]) = [expr]
    define fname([param_1 [= default_1], ...]) { [statement_1 ... ] }

TYPES
    fname               identifier, not a builtin function name
    param_1, ...        identifiers, no two the same
    default_1, ...      expressions
    expr                expression
    statement_1, ...    statements

DESCRIPTION
    The intention of a function definition is that the identifier fname
    becomes the name of a function which may be called by an expression
    of the form  fname(arg_1, arg_2, ...), where arg_1, arg_2, ... are
    expressions (including possibly blanks, which are treated as
    null values).  Evaluation of the function begins with evaluation
    of arg_1, arg_2, ...; then, in increasing order of i, if arg_i is
    null-valued and  "= default_i" has been included in the definition,
    default_i is evaluated and its value becomes the value of arg_i.
    The instructions in expr or the listed statements are then executed
    with each occurrence of param_i replaced by the value obtained
    for arg_i.

    In a call, arg_i may be preceded by a backquote (`)  to indicate that
    evaluation of arg_i is not to include a final evaluation of an lvalue.
    For example, suppose a function f and a global variable A have been
    defined by:

        ; define f(x) = (x = 3);
        ; global mat A[3];

    If g() is  a function that evaluates to 2:

        ; f(A[g()]);

    assigns the value of A[2] to the parameter x and then assigns the
    value 3 to x:

        ; f(`A[g()]);

    has essentially the effect of assigning A[2] as an lvalue to x and
    then assigning the value 3 to A[2].  (Very old versions of calc
    achieved the same result by using '&' as in  f(&A[g()]).)

    The number of arguments arg_1, arg_2, ... in a call need not equal the
    number of parameters.  If there are fewer arguments than parameters,
    the "missing" values are assigned the null value.

    In the definition of a function, the builtin function param(n)
    provides a way of referring to the parameters.  If n (which may
    result from evaluating an expression) is zero, it returns the number
    of arguments in a call to the function, and if 1 <= n <= param(0),
    param(n) refers to the parameter with index n.

    If no error occurs and no quit statement or abort statement is
    encountered during evaluation of the expression or the statements,
    the function call returns a value.  In the expression form, this is
    simply the value of the expression.

    In the statement form, if a return statement is encountered,
    the "return" keyword is to be either immediately followed by an
    expression or by a statement terminator (semicolon or right-brace);
    in the former case, the expression is evaluated, evaluation of
    the function ceases, and the value obtained for the expression is
    returned as the "value of the function";  in the no-expression case,
    evaluation ceases immediately and the null-value is returned.

    In the expression form of definition, the end of the expression expr
    is to be indicated by either a semicolon or a newline not within
    a part enclosed by parentheses; the definition may extend over
    several physical lines by ending each line with a '\' character or by
    enclosing the expression in parentheses.  In interactive mode, that
    a definition has not been completed is indicated by the continuation
    prompt.   A ctrl-C interrupt at this stage will abort the definition.

    If the expr is omitted from an expression definition, as in:

        ; define h() = ;

    any call to the function will evaluate the arguments and return the
    null value.

    In the statement form, the definition ends when a matching right
    brace completes the "block" started by the initial left brace.
    Newlines within the block are treated as white space; statements
    within the block end with a ';' or a '}' matching an earlier '{'.

    If a function with name fname had been defined earlier, the old
    definition has no effect on the new definition, but if the definition
    is completed successfully, the new definition replaces the old one;
    otherwise the old definition is retained.  The number of parameters
    and their names in the new definition may be quite different from
    those in the old definition.

    An attempt at a definition may fail because of scanerrors as the
    definition is compiled.  Common causes of these are: bad syntax,
    using identifiers as names of variables not yet defined.  It is
    not a fault to have in the definition a call to a function that has
    not yet been defined; it is sufficient that the function has been
    defined when a call is made to the function.

    After fname has been defined, the definition may be removed by the command:

        ; undefine fname

    The definitions of all user-defined functions may be removed by:

        ; undefine *

    If bit 0 of config("resource_debug") is set and the define command is
    at interactive level, a message saying that fname has been defined
    or redefined is displayed.  The same message is displayed if bit 1
    of config("resource_debug") is set and the define command is read
    from a file.

    The identifiers used for the parameters in a function definition do
    not form part of the completed definition.  For example,

        ; define f(a,b) = a + b;
        ; define g(alpha, beta) = alpha + beta;

    result in identical code for the functions f, g.

    If config("trace") & 8 is nonzero, the opcodes of a newly defined
    function are displayed on completion of its definition, parameters
    being specified by names used in the definition.  For example:

        ; config("trace", 8),
        ; define f(a,b) = a + b
        0: PARAMADDR a
        2: PARAMADDR b
        4: ADD
        5: RETURN
        f(a,b) defined

    The opcodes may also be displayed later using the show opcodes command;
    parameters will be specified by indices instead of by names.  For example:

        ; show opco f
        0: PARAMADDR 0
        2: PARAMADDR 1
        4: ADD
        5: RETURN

    When a function is defined by the statement mode, the opcodes normally
    include DEBUG opcodes which specify statement boundaries at which
    SIGINT interruptions are likely to be least risky.  Inclusion of
    the DEBUG opcodes is disabled if config("trace") & 2 is nonzero.
    For details, see help interrupt.

    While config("trace") & 1 is nonzero, the opcodes are displayed as
    they are being evaluated.  The current function is identified by its
    name, or "*" in the case of a command-line and "**" in the case of
    an eval(str) evaluation.

    When a function is called, argument values may be of any type for
    which the operations and any functions used within the body of the
    definition can be executed.  For example, whatever the intention at
    the time they were defined, the functions f1(), f2() defined above
    may be called with integer, fractional, or complex-number values, or
    with both arguments strings, or under some compatibility conditions,
    matrices or objects.

EXAMPLE
    ; define f(a,b) = 2*a + b;
    ; define g(alpha, beta)
    ;; {
    ;;     local a, pi2;
    ;;
    ;;     pi2 = 2 * pi();
    ;;     a = sin(alpha % pi2);
    ;;     if (a > 0.0) {
    ;;         return a*beta;
    ;;     }
    ;;     if (beta > 0.0) {
    ;;         a *= cos(-beta % pi2);
    ;;     }
    ;;     return a;
    ;; }

LIMITS
    The number of arguments in a function-call cannot exceed 1024.

LIBRARY
    none

SEE ALSO
    param, variable, undefine, show

## Copyright (C) 2000-2006,2021  David I. Bell, Landon Curt Noll
##                               and 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.
##
##
## Under source code control:   1991/07/21 04:37:18
## 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/

*************
* environment
*************

Environment variables

    CALCPATH

        A :-separated list of directories used to search for
        resource filenames (*.cal files) that do not begin with:

                /       ./      ../     ~

        If this variable does not exist, or if this
        variable is an empty string, a compiled value
        is used.  Typically compiled in value is:

                    .:./cal:~/cal:${CALC_SHAREDIR}:${CUSTOMCALDIR}

        which is usually:

                    .:./cal:~/cal:/usr/share/calc:/usr/share/calc/custom

        This value is used by the READ command.  It is an error
        if no such readable file is found.

        The CALCBINDINGS file searches the CALCPATH as well.

    CALCRC

        On startup (unless -h or -q was given on the command
        line), calc searches for files along the :-separated
        $CALCRC environment variable.

        If this variable does not exist, or if this
        variable is an empty string, a compiled value
        is used.  Typically compiled in value is:

                    ${CALC_SHAREDIR}/startup:~/.calcrc:./.calcinit

        which is usually:

                    /usr/share/calc/startup:~/.calcrc:./.calcinit

        Missing files along the $CALCRC path are silently ignored.

    CALCBINDINGS

        On startup (unless -h or -q was given on the command
        line), calc reads key bindings from the filename specified
        in the $CALCRC environment variable.  These key bindings
        are used for command line editing and the command history.

        If this variable does not exist, a compiled value is used.
        Typically compiled in value is:

                    bindings

        The bindings file is searched along the CALCPATH.  Unlike
        the READ command, a .cal extension is not added.

        If the file could not be opened, or if standard input is not
        a terminal, then calc will still run, but fancy command line
        editing is disabled.

        NOTE: If calc was compiled with GNU-readline support, the
              CALCBINDINGS facility is ignored and the standard
              readline mechanisms (see readline(3)) are used.

    HOME

        This value is taken to be the home directory of the
        current user.  It is used when files begin with '~/'.

        If this variable does not exist, or if this
        variable is an empty string, the home directory password
        entry of the current user is used.  If that information
        is not available, '.' is used.

    PAGER

        When invoking help, this environment variable is used
        to display a help file.

        If this variable does not exist, or if this
        variable is an empty string, a compiled value
        is used.  Typically compiled in value is something
        such as 'more', 'less', 'pg' or 'cat'.

    SHELL

        When a !-command is used, the program indicated by
        this environment variable is used.

        If this variable does not exist, or if this
        variable is an empty string, a compiled value
        is used.  Typically compiled in value is something
        such as 'sh' is used.

    CALCHISTFILE

        This value is taken to be the calc history file.

        If this variable does not exist, or if this
        variable is an empty string, then ~/.calc_history
        is used.

     CALCHELP

        Location of the calc help directory.

        If this variable does not exist, or if this
        variable is an empty string, then ${HELPDIR}

     CALCCUSTOMHELP

        Location of the calc custom help directory.

        If this variable does not exist, or if this
        variable is an empty string, then ${CUSTOMHELPDIR}
        is used.

## Copyright (C) 1999,2021  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.
##
## Under source code control:   1991/07/23 05:47:25
## 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/

*************
* errorcodes
*************

## DO NOT EDIT - This file was generated by errcode -e via the Makefile
Calc computation error codes

"E_STRING"	errnum	Calc computation error message
----------	------	------------------------------

"E__NONE"	0	calc_errno cleared: libc errno codes above here
"E__BASE"	10000	Reserved for "No error" calc internal state

"E_DIVBYZERO"	10001	Division by zero
"E_ZERODIVZERO"	10002	Indeterminate (0/0)
"E_ADD"		10003	Bad arguments for +
"E_SUB"		10004	Bad arguments for binary -
"E_MUL"		10005	Bad arguments for *
"E_DIV"		10006	Bad arguments for /
"E_NEG"		10007	Bad argument for unary -
"E_SQUARE"	10008	Bad argument for squaring
"E_INV"		10009	Bad argument for inverse
"E_INCV"	10010	Bad argument for ++
"E_DECV"	10011	Bad argument for --
"E_INT"		10012	Bad argument for int
"E_FRAC"	10013	Bad argument for frac
"E_CONJ"	10014	Bad argument for conj
"E_APPR_1"	10015	Bad first argument for appr
"E_APPR_2"	10016	Bad second argument for appr
"E_APPR_3"	10017	Bad third argument for appr
"E_ROUND_1"	10018	Bad first argument for round
"E_ROUND_2"	10019	Bad second argument for round
"E_ROUND_3"	10020	Bad third argument for round
"E_BROUND_1"	10021	Bad first argument for bround
"E_BROUND_2"	10022	Bad second argument for bround
"E_BROUND_3"	10023	Bad third argument for bround
"E_SQRT_1"	10024	Bad first argument for sqrt
"E_SQRT_2"	10025	Bad second argument for sqrt
"E_SQRT_3"	10026	Bad third argument for sqrt
"E_ROOT_1"	10027	Bad first argument for root
"E_ROOT_2"	10028	Bad second argument for root
"E_ROOT_3"	10029	Bad third argument for root
"E_NORM"	10030	Bad argument for norm
"E_SHIFT_1"	10031	Bad first argument for << or >>
"E_SHIFT_2"	10032	Bad second argument for << or >>
"E_SCALE_1"	10033	Bad first argument for scale
"E_SCALE_2"	10034	Bad second argument for scale
"E_POWI_1"	10035	Bad first argument for ^
"E_POWI_2"	10036	Bad second argument for ^
"E_POWER_1"	10037	Bad first argument for power
"E_POWER_2"	10038	Bad second argument for power
"E_POWER_3"	10039	Bad third argument for power
"E_QUO_1"	10040	Bad first argument for quo or //
"E_QUO_2"	10041	Bad second argument for quo or //
"E_QUO_3"	10042	Bad third argument for quo
"E_MOD_1"	10043	Bad first argument for mod or %
"E_MOD_2"	10044	Bad second argument for mod or %
"E_MOD_3"	10045	Bad third argument for mod
"E_SGN"		10046	Bad argument for sgn
"E_ABS_1"	10047	Bad first argument for abs
"E_ABS_2"	10048	Bad second argument for abs
"E_EVAL"	10049	Scan error in argument for eval
"E_STR"		10050	Non-simple type for str
"E_EXP_1"	10051	Non-real epsilon for exp
"E_EXP_2"	10052	Bad first argument for exp
"E_FPUTC_1"	10053	Non-file first argument for fputc
"E_FPUTC_2"	10054	Bad second argument for fputc
"E_FPUTC_3"	10055	File not open for writing for fputc
"E_FGETC_1"	10056	Non-file first argument for fgetc
"E_FGETC_2"	10057	File not open for reading for fgetc
"E_FOPEN_1"	10058	Non-string arguments for fopen
"E_FOPEN_2"	10059	Unrecognized mode for fopen
"E_FREOPEN_1"	10060	Non-file first argument for freopen
"E_FREOPEN_2"	10061	Non-string or unrecognized mode for freopen
"E_FREOPEN_3"	10062	Non-string third argument for freopen
"E_FCLOSE_1"	10063	Non-file argument for fclose
"E_FFLUSH"	10064	Non-file argument for fflush
"E_FPUTS_1"	10065	Non-file first argument for fputs
"E_FPUTS_2"	10066	Non-string argument after first for fputs
"E_FPUTS_3"	10067	File not open for writing for fputs
"E_FGETS_1"	10068	Non-file argument for fgets
"E_FGETS_2"	10069	File not open for reading for fgets
"E_FPUTSTR_1"	10070	Non-file first argument for fputstr
"E_FPUTSTR_2"	10071	Non-string argument after first for fputstr
"E_FPUTSTR_3"	10072	File not open for writing for fputstr
"E_FGETSTR_1"	10073	Non-file first argument for fgetstr
"E_FGETSTR_2"	10074	File not open for reading for fgetstr
"E_FGETLINE_1"	10075	Non-file  argument for fgetline
"E_FGETLINE_2"	10076	File not open for reading for fgetline
"E_FGETFIELD_1"	10077	Non-file argument for fgetfield
"E_FGETFIELD_2"	10078	File not open for reading for fgetfield
"E_REWIND_1"	10079	Non-file argument for rewind
"E_FILES"	10080	Non-integer argument for files
"E_PRINTF_1"	10081	Non-string fmt argument for fprint
"E_PRINTF_2"	10082	Stdout not open for writing to ???
"E_FPRINTF_1"	10083	Non-file first argument for fprintf
"E_FPRINTF_2"	10084	Non-string second (fmt) argument for fprintf
"E_FPRINTF_3"	10085	File not open for writing for fprintf
"E_STRPRINTF_1"	10086	Non-string first (fmt) argument for strprintf
"E_STRPRINTF_2"	10087	Error in attempting strprintf ???
"E_FSCAN_1"	10088	Non-file first argument for fscan
"E_FSCAN_2"	10089	File not open for reading for fscan
"E_STRSCAN"	10090	Non-string first argument for strscan
"E_FSCANF_1"	10091	Non-file first argument for fscanf
"E_FSCANF_2"	10092	Non-string second (fmt) argument for fscanf
"E_FSCANF_3"	10093	Non-lvalue argument after second for fscanf
"E_FSCANF_4"	10094	File not open for reading or other error for fscanf
"E_STRSCANF_1"	10095	Non-string first argument for strscanf
"E_STRSCANF_2"	10096	Non-string second (fmt) argument for strscanf
"E_STRSCANF_3"	10097	Non-lvalue argument after second for strscanf
"E_STRSCANF_4"	10098	Some error in attempting strscanf ???
"E_SCANF_1"	10099	Non-string first (fmt) argument for scanf
"E_SCANF_2"	10100	Non-lvalue argument after first for scanf
"E_SCANF_3"	10101	Some error in attempting scanf ???
"E_FTELL_1"	10102	Non-file argument for ftell
"E_FTELL_2"	10103	File not open or other error for ftell
"E_FSEEK_1"	10104	Non-file first argument for fseek
"E_FSEEK_2"	10105	Non-integer or negative second argument for fseek
"E_FSEEK_3"	10106	File not open or other error for fseek
"E_FSIZE_1"	10107	Non-file argument for fsize
"E_FSIZE_2"	10108	File not open or other error for fsize
"E_FEOF_1"	10109	Non-file argument for feof
"E_FEOF_2"	10110	File not open or other error for feof
"E_FERROR_1"	10111	Non-file argument for ferror
"E_FERROR_2"	10112	File not open or other error for ferror
"E_UNGETC_1"	10113	Non-file argument for ungetc
"E_UNGETC_2"	10114	File not open for reading for ungetc
"E_UNGETC_3"	10115	Bad second argument or other error for ungetc
"E_BIGEXP"	10116	Exponent too big in scanning
"E_ISATTY_1"	10117	UNUSED ERROR: E_ISATTY_1 is no longer used
"E_ISATTY_2"	10118	UNUSED ERROR: E_ISATTY_2 is no longer used
"E_ACCESS_1"	10119	Non-string first argument for access
"E_ACCESS_2"	10120	Bad second argument for access
"E_SEARCH_1"	10121	Bad first argument for search
"E_SEARCH_2"	10122	Bad second argument for search
"E_SEARCH_3"	10123	Bad third argument for search
"E_SEARCH_4"	10124	Bad fourth argument for search
"E_SEARCH_5"	10125	Cannot find fsize or fpos for search
"E_SEARCH_6"	10126	File not readable for search
"E_RSEARCH_1"	10127	Bad first argument for rsearch
"E_RSEARCH_2"	10128	Bad second argument for rsearch
"E_RSEARCH_3"	10129	Bad third argument for rsearch
"E_RSEARCH_4"	10130	Bad fourth argument for rsearch
"E_RSEARCH_5"	10131	Cannot find fsize or fpos for rsearch
"E_RSEARCH_6"	10132	File not readable for rsearch
"E_MANYOPEN"	10133	Too many open files
"E_REWIND_2"	10134	Attempt to rewind a file that is not open
"E_STRERROR_1"	10135	Bad argument type for strerror
"E_STRERROR_2"	10136	Numeric argument is outside valid errnum range for strerror
"E_COS_1"	10137	Bad epsilon for cos
"E_COS_2"	10138	Bad first argument for cos
"E_SIN_1"	10139	Bad epsilon for sin
"E_SIN_2"	10140	Bad first argument for sin
"E_EVAL_2"	10141	Non-string argument for eval
"E_ARG_1"	10142	Bad epsilon for arg
"E_ARG_2"	10143	Bad first argument for arg
"E_POLAR_1"	10144	Non-real argument for polar
"E_POLAR_2"	10145	Bad epsilon for polar
"E_FCNT"	10146	UNUSED ERROR: Non-integral argument for fcnt
"E_MATFILL_1"	10147	Non-variable first argument for matfill
"E_MATFILL_2"	10148	Non-matrix first argument-value for matfill
"E_MATDIM"	10149	Non-matrix argument for matdim
"E_MATSUM"	10150	Non-matrix argument for matsum
"E_ISIDENT"	10151	UNUSED ERROR: E_ISIDENT is no longer used
"E_MATTRANS_1"	10152	Non-matrix argument for mattrans
"E_MATTRANS_2"	10153	Non-two-dimensional matrix for mattrans
"E_DET_1"	10154	Non-matrix argument for det
"E_DET_2"	10155	Matrix for det not of dimension 2
"E_DET_3"	10156	Non-square matrix for det
"E_MATMIN_1"	10157	Non-matrix first argument for matmin
"E_MATMIN_2"	10158	Non-positive-integer second argument for matmin
"E_MATMIN_3"	10159	Second argument for matmin exceeds dimension
"E_MATMAX_1"	10160	Non-matrix first argument for matmin
"E_MATMAX_2"	10161	Second argument for matmax not positive integer
"E_MATMAX_3"	10162	Second argument for matmax exceeds dimension
"E_CP_1"	10163	Non-matrix argument for cp
"E_CP_2"	10164	Non-one-dimensional matrix for cp
"E_CP_3"	10165	Matrix size not 3 for cp
"E_DP_1"	10166	Non-matrix argument for dp
"E_DP_2"	10167	Non-one-dimensional matrix for dp
"E_DP_3"	10168	Different-size matrices for dp
"E_STRLEN"	10169	Non-string argument for strlen
"E_STRCAT"	10170	Non-string argument for strcat
"E_SUBSTR_1"	10171	Non-string first argument for strcat
"E_SUBSTR_2"	10172	Non-non-negative integer second argument for strcat
"E_CHAR"	10173	Bad argument for char
"E_ORD"		10174	Non-string argument for ord
"E_INSERT_1"	10175	Non-list-variable first argument for insert
"E_INSERT_2"	10176	Non-integral second argument for insert
"E_PUSH"	10177	Non-list-variable first argument for push
"E_APPEND"	10178	Non-list-variable first argument for append
"E_DELETE_1"	10179	Non-list-variable first argument for delete
"E_DELETE_2"	10180	Non-integral second argument for delete
"E_POP"		10181	Non-list-variable argument for pop
"E_REMOVE"	10182	Non-list-variable argument for remove
"E_LN_1"	10183	Bad epsilon argument for ln
"E_LN_2"	10184	Non-numeric first argument for ln
"E_ERROR_1"	10185	Invalid argument type for error
"E_ERROR_2"	10186	Numeric argument is outside valid errnum range for error
"E_EVAL_3"	10187	Attempt to eval at maximum input depth
"E_EVAL_4"	10188	Unable to open string for reading
"E_RM_1"	10189	First argument for rm is not a non-empty string
"E_RM_2"	10190	UNUSED ERROR: Unable to remove a file
"E_RDPERM"	10191	UNUSED ERROR: Operation allowed because calc mode disallows read operations
"E_WRPERM"	10192	Operation allowed because calc mode disallows write operations
"E_EXPERM"	10193	UNUSED ERROR: Operation allowed because calc mode disallows exec operations
"E_MIN"		10194	Unordered arguments for min
"E_MAX"		10195	Unordered arguments for max
"E_LISTMIN"	10196	Unordered items for minimum of list
"E_LISTMAX"	10197	Unordered items for maximum of list
"E_SIZE"	10198	Size undefined for argument type
"E_NO_C_ARG"	10199	Calc must be run with a -C argument to use custom function
"E_NO_CUSTOM"	10200	Calc was built with custom functions disabled
"E_UNK_CUSTOM"	10201	Custom function unknown, try: show custom
"E_BLK_1"	10202	Non-integral length for block
"E_BLK_2"	10203	Negative or too-large length for block
"E_BLK_3"	10204	Non-integral chunksize for block
"E_BLK_4"	10205	Negative or too-large chunksize for block
"E_BLKFREE_1"	10206	Named block does not exist for blkfree
"E_BLKFREE_2"	10207	Non-integral id specification for blkfree
"E_BLKFREE_3"	10208	Block with specified id does not exist
"E_BLKFREE_4"	10209	Block already freed
"E_BLKFREE_5"	10210	No-realloc protection prevents blkfree
"E_BLOCKS_1"	10211	Non-integer argument for blocks
"E_BLOCKS_2"	10212	Non-allocated index number for blocks
"E_COPY_01"	10213	Non-integer or negative source index for copy
"E_COPY_02"	10214	Source index too large for copy
"E_COPY_03"	10215	UNUSED ERROR: E_COPY_03 is no longer used
"E_COPY_04"	10216	Non-integer or negative number for copy
"E_COPY_05"	10217	Number too large for copy
"E_COPY_06"	10218	Non-integer or negative destination index for copy
"E_COPY_07"	10219	Destination index too large for copy
"E_COPY_08"	10220	Freed block source for copy
"E_COPY_09"	10221	Unsuitable source type for copy
"E_COPY_10"	10222	Freed block destination for copy
"E_COPY_11"	10223	Unsuitable destination type for copy
"E_COPY_12"	10224	Incompatible source and destination for copy
"E_COPY_13"	10225	No-copy-from source variable
"E_COPY_14"	10226	No-copy-to destination variable
"E_COPY_15"	10227	No-copy-from source named block
"E_COPY_16"	10228	No-copy-to destination named block
"E_COPY_17"	10229	No-relocate destination for copy
"E_COPYF_1"	10230	File not open for copy
"E_COPYF_2"	10231	fseek or fsize failure for copy
"E_COPYF_3"	10232	fwrite error for copy
"E_COPYF_4"	10233	fread error for copy
"E_PROTECT_1"	10234	Non-variable first argument for protect
"E_PROTECT_2"	10235	Bad second argument for protect
"E_PROTECT_3"	10236	Bad third argument for protect
"E_MATFILL_3"	10237	No-copy-to destination for matfill
"E_MATFILL_4"	10238	No-assign-from source for matfill
"E_MATTRACE_1"	10239	Non-matrix argument for mattrace
"E_MATTRACE_2"	10240	Non-two-dimensional argument for mattrace
"E_MATTRACE_3"	10241	Non-square argument for mattrace
"E_TAN_1"	10242	Bad epsilon for tan
"E_TAN_2"	10243	Bad argument for tan
"E_COT_1"	10244	Bad epsilon for cot
"E_COT_2"	10245	Bad argument for cot
"E_SEC_1"	10246	Bad epsilon for sec
"E_SEC_2"	10247	Bad argument for sec
"E_CSC_1"	10248	Bad epsilon for csc
"E_CSC_2"	10249	Bad argument for csc
"E_SINH_1"	10250	Bad epsilon for sinh
"E_SINH_2"	10251	Bad argument for sinh
"E_COSH_1"	10252	Bad epsilon for cosh
"E_COSH_2"	10253	Bad argument for cosh
"E_TANH_1"	10254	Bad epsilon for tanh
"E_TANH_2"	10255	Bad argument for tanh
"E_COTH_1"	10256	Bad epsilon for coth
"E_COTH_2"	10257	Bad argument for coth
"E_SECH_1"	10258	Bad epsilon for sech
"E_SECH_2"	10259	Bad argument for sech
"E_CSCH_1"	10260	Bad epsilon for csch
"E_CSCH_2"	10261	Bad argument for csch
"E_ASIN_1"	10262	Bad epsilon for asin
"E_ASIN_2"	10263	Bad argument for asin
"E_ACOS_1"	10264	Bad epsilon for acos
"E_ACOS_2"	10265	Bad argument for acos
"E_ATAN_1"	10266	Bad epsilon for atan
"E_ATAN_2"	10267	Bad argument for atan
"E_ACOT_1"	10268	Bad epsilon for acot
"E_ACOT_2"	10269	Bad argument for acot
"E_ASEC_1"	10270	Bad epsilon for asec
"E_ASEC_2"	10271	Bad argument for asec
"E_ACSC_1"	10272	Bad epsilon for acsc
"E_ACSC_2"	10273	Bad argument for acsc
"E_ASINH_1"	10274	Bad epsilon for asin
"E_ASINH_2"	10275	Bad argument for asinh
"E_ACOSH_1"	10276	Bad epsilon for acosh
"E_ACOSH_2"	10277	Bad argument for acosh
"E_ATANH_1"	10278	Bad epsilon for atanh
"E_ATANH_2"	10279	Bad argument for atanh
"E_ACOTH_1"	10280	Bad epsilon for acoth
"E_ACOTH_2"	10281	Bad argument for acoth
"E_ASECH_1"	10282	UNUSED ERROR: Bad epsilon for asech
"E_ASECH_2"	10283	Bad argument for asech
"E_ACSCH_1"	10284	Bad epsilon for acsch
"E_ACSCH_2"	10285	Bad argument for acsch
"E_GD_1"	10286	Bad epsilon for gd
"E_GD_2"	10287	Bad argument for gd
"E_AGD_1"	10288	Bad epsilon for agd
"E_AGD_2"	10289	Bad argument for agd
"E_LOGINF"	10290	Log of zero or infinity
"E_STRADD"	10291	String addition failure
"E_STRMUL"	10292	String multiplication failure
"E_STRNEG"	10293	String reversal failure
"E_STRSUB"	10294	String subtraction failure
"E_BIT_1"	10295	Bad argument type for bit
"E_BIT_2"	10296	Index too large for bit
"E_SETBIT_1"	10297	Non-integer second argument for setbit
"E_SETBIT_2"	10298	Out-of-range index for setbit
"E_SETBIT_3"	10299	Non-string first argument for setbit
"E_OR"		10300	Bad argument for or
"E_AND"		10301	Bad argument for and
"E_STROR"	10302	Allocation failure for string or
"E_STRAND"	10303	Allocation failure for string and
"E_XOR"		10304	Bad argument for xorvalue
"E_COMP"	10305	Bad argument for comp
"E_STRDIFF"	10306	Allocation failure for string diff
"E_STRCOMP"	10307	Allocation failure for string comp
"E_SEG_1"	10308	Bad first argument for segment
"E_SEG_2"	10309	Bad second argument for segment
"E_SEG_3"	10310	Bad third argument for segment
"E_STRSEG"	10311	Failure for string segment
"E_HIGHBIT_1"	10312	Bad argument type for highbit
"E_HIGHBIT_2"	10313	Non-integer argument for highbit
"E_LOWBIT_1"	10314	Bad argument type for lowbit
"E_LOWBIT_2"	10315	Non-integer argument for lowbit
"E_CONTENT"	10316	Bad argument type for unary hash op
"E_HASHOP"	10317	Bad argument type for binary hash op
"E_HEAD_1"	10318	Bad first argument for head
"E_HEAD_2"	10319	Bad second argument for head
"E_STRHEAD"	10320	Failure for strhead
"E_TAIL_1"	10321	Bad first argument for tail
"E_TAIL_2"	10322	UNUSED ERROR: Bad second argument for tail
"E_STRTAIL"	10323	Failure for strtail
"E_STRSHIFT"	10324	Failure for strshift
"E_STRCMP"	10325	Non-string argument for strcmp
"E_STRNCMP"	10326	Bad argument type for strncmp
"E_XOR_1"	10327	Varying types of argument for xor
"E_XOR_2"	10328	Bad argument type for xor
"E_STRCPY"	10329	Bad argument type for strcpy
"E_STRNCPY"	10330	Bad argument type for strncpy
"E_BACKSLASH"	10331	Bad argument type for unary backslash
"E_SETMINUS"	10332	Bad argument type for setminus
"E_INDICES_1"	10333	Bad first argument type for indices
"E_INDICES_2"	10334	Bad second argument for indices
"E_EXP_3"	10335	Too-large re(argument) for exp
"E_SINH_3"	10336	Too-large re(argument) for sinh
"E_COSH_3"	10337	Too-large re(argument) for cosh
"E_SIN_3"	10338	Too-large im(argument) for sin
"E_COS_3"	10339	Too-large im(argument) for cos
"E_GD_3"	10340	Infinite or too-large result for gd
"E_AGD_3"	10341	Infinite or too-large result for agd
"E_POWER_4"	10342	Too-large value for power
"E_ROOT_4"	10343	Too-large value for root
"E_DGT_1"	10344	Non-real first arg for digit
"E_DGT_2"	10345	Non-integral second arg for digit
"E_DGT_3"	10346	Bad third arg for digit
"E_PLCS_1"	10347	Bad first argument for places
"E_PLCS_2"	10348	Bad second argument for places
"E_DGTS_1"	10349	Bad first argument for digits
"E_DGTS_2"	10350	Bad second argument for digits
"E_ILOG"	10351	Bad first argument for ilog
"E_ILOGB"	10352	Bad second argument for ilog
"E_IBASE10_LOG"	10353	Bad argument for ilog10
"E_IBASE2_LOG"	10354	Bad argument for ilog2
"E_COMB_1"	10355	Non-integer second arg for comb
"E_COMB_2"	10356	Too-large second arg for comb
"E_CTLN"	10357	Bad argument for catalan
"E_BERN"	10358	Bad argument for bern
"E_EULER"	10359	Bad argument for euler
"E_SLEEP"	10360	Bad argument for sleep
"E_TTY"		10361	calc_tty failure
"E_ASSIGN_1"	10362	No-copy-to destination for octet assign
"E_ASSIGN_2"	10363	No-copy-from source for octet assign
"E_ASSIGN_3"	10364	No-change destination for octet assign
"E_ASSIGN_4"	10365	Non-variable destination for assign
"E_ASSIGN_5"	10366	No-assign-to destination for assign
"E_ASSIGN_6"	10367	No-assign-from source for assign
"E_ASSIGN_7"	10368	No-change destination for assign
"E_ASSIGN_8"	10369	No-type-change destination for assign
"E_ASSIGN_9"	10370	No-error-value destination for assign
"E_SWAP_1"	10371	No-copy argument for octet swap
"E_SWAP_2"	10372	No-assign-to-or-from argument for swap
"E_SWAP_3"	10373	Non-lvalue argument for swap
"E_QUOMOD_1"	10374	Non-lvalue argument 3 or 4 for quomod
"E_QUOMOD_2"	10375	Non-real-number arg 1 or 2 or bad arg 5 for quomod
"E_QUOMOD_3"	10376	No-assign-to argument 3 or 4 for quomod
"E_PREINC_1"	10377	No-copy-to or no-change argument for octet preinc
"E_PREINC_2"	10378	Non-variable argument for preinc
"E_PREINC_3"	10379	No-assign-to or no-change argument for preinc
"E_PREDEC_1"	10380	No-copy-to or no-change argument for octet predec
"E_PREDEC_2"	10381	Non-variable argument for predec
"E_PREDEC_3"	10382	No-assign-to or no-change argument for predec
"E_POSTINC_1"	10383	No-copy-to or no-change argument for octet postinc
"E_POSTINC_2"	10384	Non-variable argument for postinc
"E_POSTINC_3"	10385	No-assign-to or no-change argument for postinc
"E_POSTDEC_1"	10386	No-copy-to or no-change argument for octet postdec
"E_POSTDEC_2"	10387	Non-variable argument for postdec
"E_POSTDEC_3"	10388	No-assign-to or no-change argument for postdec
"E_INIT_01"	10389	Error-type structure for initialization
"E_INIT_02"	10390	No-copy-to structure for initialization
"E_INIT_03"	10391	Too many initializer values
"E_INIT_04"	10392	Attempt to initialize freed named block
"E_INIT_05"	10393	Bad structure type for initialization
"E_INIT_06"	10394	No-assign-to element for initialization
"E_INIT_07"	10395	No-change element for initialization
"E_INIT_08"	10396	No-type-change element for initialization
"E_INIT_09"	10397	No-error-value element for initialization
"E_INIT_10"	10398	No-assign-or-copy-from source for initialization
"E_LIST_1"	10399	No-relocate for list insert
"E_LIST_2"	10400	No-relocate for list delete
"E_LIST_3"	10401	No-relocate for list push
"E_LIST_4"	10402	No-relocate for list append
"E_LIST_5"	10403	No-relocate for list pop
"E_LIST_6"	10404	No-relocate for list remove
"E_MODIFY_1"	10405	Non-variable first argument for modify
"E_MODIFY_2"	10406	Non-string second argument for modify
"E_MODIFY_3"	10407	No-change first argument for modify
"E_MODIFY_4"	10408	Undefined function for modify
"E_MODIFY_5"	10409	Unacceptable type first argument for modify
"E_FPATHOPEN_1"	10410	Non-string arguments for fpathopen
"E_FPATHOPEN_2"	10411	Unrecognized mode for fpathopen
"E_LOG_1"	10412	Bad epsilon argument for log
"E_LOG_2"	10413	Non-numeric first argument for log
"E_LOG_3"	10414	Cannot calculate log for this value
"E_FGETFILE_1"	10415	Non-file argument for fgetfile
"E_FGETFILE_2"	10416	File argument for fgetfile not open for reading
"E_FGETFILE_3"	10417	Unable to set file position in fgetfile
"E_ESTR"	10418	UNUSED ERROR: Non-representable type for estr
"E_STRCASECMP"	10419	Non-string argument for strcasecmp
"E_STRNCASECMP"	10420	Bad argument type for strncasecmp
"E_ISUPPER"	10421	Bad argument for isupper
"E_ISLOWER"	10422	Bad argument for islower
"E_ISALNUM"	10423	Bad argument for isalnum
"E_ISALPHA"	10424	Bad argument for isalpha
"E_ISASCII"	10425	Bad argument for isascii
"E_ISCNTRL"	10426	Bad argument for iscntrl
"E_ISDIGIT"	10427	Bad argument for isdigit
"E_ISGRAPH"	10428	Bad argument for isgraph
"E_ISPRINT"	10429	Bad argument for isprint
"E_ISPUNCT"	10430	Bad argument for ispunct
"E_ISSPACE"	10431	Bad argument for isspace
"E_ISXDIGIT"	10432	Bad argument for isxdigit
"E_STRTOUPPER"	10433	Bad argument type for strtoupper
"E_STRTOLOWER"	10434	Bad argument type for strtolower
"E_TAN_3"	10435	UNUSED ERROR: Invalid value for calculating the sin numerator for tan
"E_TAN_4"	10436	UNUSED ERROR: Invalid value for calculating the cos denominator for tan
"E_COT_3"	10437	UNUSED ERROR: Invalid value for calculating the sin numerator for cot
"E_COT_4"	10438	UNUSED ERROR: Invalid value for calculating the cos denominator for cot
"E_SEC_3"	10439	UNUSED ERROR: Invalid value for calculating the cos reciprocal for sec
"E_CSC_3"	10440	UNUSED ERROR: Invalid value for calculating the sin reciprocal for csc
"E_TANH_3"	10441	Invalid value for calculating the sinh numerator for tanh
"E_TANH_4"	10442	Invalid value for calculating the cosh denominator for tanh
"E_COTH_3"	10443	Invalid value for calculating the sinh numerator for coth
"E_COTH_4"	10444	Invalid value for calculating the cosh denominator for coth
"E_SECH_3"	10445	Invalid value for calculating the cosh reciprocal for sech
"E_CSCH_3"	10446	Invalid value for calculating the sinh reciprocal for csch
"E_ASIN_3"	10447	Invalid value for calculating asin
"E_ACOS_3"	10448	Invalid value for calculating acos
"E_ASINH_3"	10449	Invalid value for calculating asinh
"E_ACOSH_3"	10450	Invalid value for calculating acosn
"E_ATAN_3"	10451	Invalid value for calculating atan
"E_ACOT_3"	10452	Invalid value for calculating acot
"E_ASEC_3"	10453	Invalid value for calculating asec
"E_ACSC_3"	10454	Invalid value for calculating acsc
"E_ATANH_3"	10455	Invalid value for calculating atan
"E_ACOTH_3"	10456	Invalid value for calculating acot
"E_ASECH_3"	10457	Invalid value for calculating asec
"E_ACSCH_3"	10458	Invalid value for calculating acsc
"E_D2R_1"	10459	Bad epsilon for converting degrees to radians
"E_D2R_2"	10460	Bad first argument converting degrees to radians
"E_R2D_1"	10461	Bad epsilon for converting radians to degrees
"E_R2D_2"	10462	Bad first argument converting radians to degrees
"E_G2R_1"	10463	Bad epsilon for converting gradians to radians
"E_G2R_2"	10464	Bad first argument converting gradians to radians
"E_R2G_1"	10465	Bad epsilon for converting radians to gradians
"E_R2G_2"	10466	Bad first argument converting radians to gradians
"E_D2G_1"	10467	Bad first argument converting degrees to gradians
"E_G2D_1"	10468	Bad first argument converting gradians to degrees
"E_D2DMS_1"	10469	Non-lvalue arguments 2, 3 or 4 for d2dms
"E_D2DMS_2"	10470	Non-real-number arg 1 for d2dms
"E_D2DMS_3"	10471	No-assign-to argument 2, 3 or 4 for d2dms
"E_D2DMS_4"	10472	Invalid rounding arg 5 for d2dms
"E_D2DM_1"	10473	Non-lvalue arguments 2 or 3 for d2dm
"E_D2DM_2"	10474	Non-real-number arg 1 for d2dm
"E_D2DM_3"	10475	No-assign-to argument 2 or 3 for d2dm
"E_D2DM_4"	10476	Invalid rounding arg 4 for d2dm
"E_G2GMS_1"	10477	Non-lvalue arguments 2, 3 or 4 for g2gms
"E_G2GMS_2"	10478	Non-real-number arg 1 for g2gms
"E_G2GMS_3"	10479	No-assign-to argument 2 or 3 for g2gms
"E_G2GMS_4"	10480	Invalid rounding arg 5 for g2gms
"E_G2GM_1"	10481	Non-lvalue arguments 2 or 3 for g2gm
"E_G2GM_2"	10482	Non-real-number arg 1 for g2gm
"E_G2GM_3"	10483	No-assign-to argument 2, 3 or 4 for g2gm
"E_G2GM_4"	10484	Invalid rounding arg 4 for g2gm
"E_H2HMS_1"	10485	Non-lvalue arguments 2, 3 or 4 for h2hms
"E_H2HMS_2"	10486	Non-real-number arg 1 for h2hms
"E_H2HMS_3"	10487	No-assign-to argument 2, 3 or 4 for h2hms
"E_H2HMS_4"	10488	Invalid rounding arg 5 for h2hms
"E_H2HM_1"	10489	Non-lvalue arguments 2 or 3 for h2hm
"E_H2HM_2"	10490	Non-real-number arg 1 for h2hm
"E_H2HM_3"	10491	No-assign-to argument 2 or 3 for h2hm
"E_H2HM_4"	10492	Invalid rounding arg 4 for h2hm
"E_DMS2D_1"	10493	Non-real-number arguments 1, 2 or 3 for dms2d
"E_DMS2D_2"	10494	Invalid rounding arg 4 for dms2d
"E_DM2D_1"	10495	Non-real-number arguments 1 or 2 for dm2d
"E_DM2D_2"	10496	Invalid rounding arg 4 for dm2d
"E_GMS2G_1"	10497	Non-real-number arguments 1, 2 or 3 for gms2g
"E_GMS2G_2"	10498	Invalid rounding arg 4 for gms2g
"E_GM2G_1"	10499	Non-real-number arguments 1 or 2 for gm2g
"E_GM2G_2"	10500	Invalid rounding arg 4 for gm2g
"E_HMS2H_1"	10501	Non-real-number arguments 1, 2 or 3 for hms2h
"E_HMS2H_2"	10502	Invalid rounding arg 4 for hms2h
"E_HM2H_1"	10503	UNUSED ERROR: Non-real-number arguments 1 or 2 for hm2h
"E_HM2H_2"	10504	UNUSED ERROR: Invalid rounding arg 4 for hm2h
"E_LOG2_1"	10505	Bad epsilon argument for log2
"E_LOG2_2"	10506	Non-numeric first argument for log2
"E_LOG2_3"	10507	Cannot calculate log2 for this value
"E_LOGN_1"	10508	Bad epsilon argument for logn
"E_LOGN_2"	10509	Non-numeric first argument for logn
"E_LOGN_3"	10510	Cannot calculate logn for this value
"E_LOGN_4"	10511	Cannot calculate logn for this log base
"E_LOGN_5"	10512	Non-numeric second argument for logn
"E_VERSIN_1"	10513	Bad epsilon for versin
"E_VERSIN_2"	10514	Bad first argument for versin
"E_VERSIN_3"	10515	Too-large im(argument) for versin
"E_AVERSIN_1"	10516	Bad epsilon for aversin
"E_AVERSIN_2"	10517	Bad first argument for aversin
"E_AVERSIN_3"	10518	Too-large im(argument) for aversin
"E_COVERSIN_1"	10519	Bad epsilon for coversin
"E_COVERSIN_2"	10520	Bad first argument for coversin
"E_COVERSIN_3"	10521	Too-large im(argument) for coversin
"E_ACOVERSIN_1"	10522	Bad epsilon for acoversin
"E_ACOVERSIN_2"	10523	Bad first argument for acoversin
"E_ACOVERSIN_3"	10524	Too-large im(argument) for acoversin
"E_VERCOS_1"	10525	Bad epsilon for vercos
"E_VERCOS_2"	10526	Bad first argument for vercos
"E_VERCOS_3"	10527	Too-large im(argument) for vercos
"E_AVERCOS_1"	10528	Bad epsilon for avercos
"E_AVERCOS_2"	10529	Bad first argument for avercos
"E_AVERCOS_3"	10530	Too-large im(argument) for avercos
"E_COVERCOS_1"	10531	Bad epsilon for covercos
"E_COVERCOS_2"	10532	Bad first argument for covercos
"E_COVERCOS_3"	10533	Too-large im(argument) for covercos
"E_ACOVERCOS_1"	10534	Bad epsilon for acovercos
"E_ACOVERCOS_2"	10535	Bad first argument for acovercos
"E_ACOVERCOS_3"	10536	Too-large im(argument) for acovercos
"E_TAN_5"	10537	Invalid complex argument for tan
"E_COT_5"	10538	Invalid zero argument for cot
"E_COT_6"	10539	Invalid complex argument for cot
"E_SEC_5"	10540	Invalid complex argument for sec
"E_CSC_5"	10541	Invalid zero argument for csc
"E_CSC_6"	10542	Invalid complex argument for csc
"E_ERROR_3"	10543	String argument is not a valid E_STRING for error
"E_ERROR_4"	10544	Numeric argument is not an integer for error
"E_STRERROR_3"	10545	String argument is not a valid E_STRING for strerror
"E_STRERROR_4"	10546	errnum_2_errmsg returned NULL as called from strerror
"E_STRERROR_5"	10547	Numeric argument is not an integer for strerror
"E_ERRNO_1"	10548	Invalid argument type for errno
"E_ERRNO_2"	10549	Numeric argument is outside valid errnum range for errno
"E_ERRNO_3"	10550	String argument is not a valid E_STRING for errno
"E_ERRNO_4"	10551	Numeric argument is not an integer for errno
"E_ERRSYM_1"	10552	Invalid argument type for errsym
"E_ERRSYM_2"	10553	Numeric argument is outside valid errnum range for errsym
"E_ERRSYM_3"	10554	String argument is not a valid E_STRING for errsym
"E_ERRSYM_4"	10555	Numeric argument is not an integer for errsym
"E_ERRSYM_5"	10556	Unable to create a valid E_STRING from the errnum for errsym
"E_HAVERSIN_1"	10557	Bad epsilon for haversin
"E_HAVERSIN_2"	10558	Bad first argument for haversin
"E_HAVERSIN_3"	10559	Too-large im(argument) for haversin
"E_AHAVERSIN_1"	10560	Bad epsilon for ahaversin
"E_AHAVERSIN_2"	10561	Bad first argument for ahaversin
"E_AHAVERSIN_3"	10562	Too-large im(argument) for ahaversin
"E_HACOVERSIN_1"	10563	Bad epsilon for hacoversin
"E_HACOVERSIN_2"	10564	Bad first argument for hacoversin
"E_HACOVERSIN_3"	10565	Too-large im(argument) for hacoversin
"E_AHACOVERSIN_1"	10566	Bad epsilon for ahacoversin
"E_AHACOVERSIN_2"	10567	Bad first argument for achaoversin
"E_AHACOVERSIN_3"	10568	Too-large im(argument) for ahacoversin
"E_HAVERCOS_1"	10569	Bad epsilon for havercos
"E_HAVERCOS_2"	10570	Bad first argument for havercos
"E_HAVERCOS_3"	10571	Too-large im(argument) for havercos
"E_AHAVERCOS_1"	10572	Bad epsilon for ahavercos
"E_AHAVERCOS_2"	10573	Bad first argument for ahavercos
"E_AHAVERCOS_3"	10574	Too-large im(argument) for ahavercos
"E_HACOVERCOS_1"	10575	Bad epsilon for hacovercos
"E_HACOVERCOS_2"	10576	Bad first argument for hacovercos
"E_HACOVERCOS_3"	10577	Too-large im(argument) for hacovercos
"E_AHACOVERCOS_1"	10578	Bad epsilon for ahacovercos
"E_AHACOVERCOS_2"	10579	Bad first argument for achaovercos
"E_AHACOVERCOS_3"	10580	Too-large im(argument) for ahacovercos
"E_EXSEC_1"	10581	Bad epsilon for exsec
"E_EXSEC_2"	10582	Bad argument for exsec
"E_EXSEC_3"	10583	Invalid complex argument for exsec
"E_AEXSEC_1"	10584	Bad epsilon for aexsec
"E_AEXSEC_2"	10585	Bad argument for aexsec
"E_AEXSEC_3"	10586	Invalid value for calculating aexsec
"E_EXCSC_1"	10587	Bad epsilon for excsc
"E_EXCSC_2"	10588	Bad argument for excsc
"E_EXCSC_3"	10589	Invalid zero argument for excsc
"E_EXCSC_4"	10590	Invalid complex argument for excsc
"E_AEXCSC_1"	10591	Bad epsilon for aexcsc
"E_AEXCSC_2"	10592	Bad argument for aexcsc
"E_AEXCSC_3"	10593	Invalid value for calculating aexcsc
"E_CRD_1"	10594	Bad epsilon for crd
"E_CRD_2"	10595	Bad argument for crd
"E_CRD_3"	10596	Invalid complex argument for crd
"E_ACRD_1"	10597	Bad epsilon for acrd
"E_ACRD_2"	10598	Bad argument for acrd
"E_ACRD_3"	10599	Invalid value for calculating acrd
"E_CAS_1"	10600	Bad epsilon for cas
"E_CAS_2"	10601	Bad argument for cas
"E_CAS_3"	10602	Invalid complex argument for cas
"E_CIS_1"	10603	Non-real epsilon for cis
"E_CIS_2"	10604	Bad first argument for cis
"E_CIS_3"	10605	Too-large re(argument) for cis
"E_LN_3"	10606	Cannot calculate ln of 0
"E_LOG_5"	10607	Cannot calculate log of 0
"E_LOG2_4"	10608	Cannot calculate log base 2 of 0
"E_LOGN_6"	10609	Cannot calculate log base n of 0

"E__HIGHEST"	10609	highest assigned calc computation error code
"E__USERDEF"	20000	user defined error codes start here
"E__USERMAX"	32767	maximum user defined error code

## Copyright (C) 2023  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.
##
## Under source code control:   n/a
## File existed as early as:    n/a
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/

*************
* expression
*************

Expression sequences

    This is a sequence of statements, of which expression statements
    are the commonest case.  Statements are separated with semicolons,
    and the newline character generally ends the sequence.  If any
    statement is an expression by itself, or is associated with an
    'if' statement which is true, then two special things can happen.
    If the sequence is executed at the top level of the calculator,
    then the value of '.' is set to the value of the last expression.
    Also, if an expression is a non-assignment, then the value of the
    expression is automatically printed if its value is not NULL.
    Some operations such as     pre-increment and plus-equals are also
    treated as assignments.

    Examples of this are the following:

    expression              sets '.' to         prints
    ----------              -----------         ------
    3+4                         7                  7
    2*4; 8+1; fact(3)           6               8, 9, and 6
    x=3^2                       9                  -
    if (3 < 2) 5; else 6        6                  6
    x++                         old x              -
    print fact(4)               -                  24
    null()                      null()             -

    Variables can be defined at the beginning of an expression sequence.
    This is most useful for local variables, as in the following example,
    which sums the square roots of the first few numbers:

    local s, i; s = 0; for (i = 0; i < 10; i++) s += sqrt(i); s

    If a return statement is executed in an expression sequence, then
    the result of the expression sequence is the returned value.  In
    this case, '.' is set to the value, but nothing is printed.

## 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.
##
## Under source code control:   1991/07/21 04:37:18
## 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/

*************
* file
*************

Using files

    The calculator provides some functions which allow the program to
    read or write text files.  These functions use stdio internally,
    and the functions appear similar to some of the stdio functions.
    Some differences do occur, as will be explained here.

    Names of files are subject to ~ expansion just like the C or
    Korn shell.  For example, the file name:

            ~/.rc.cal

    refers to the file '.rc.cal' under your home directory.  The
    file name:

            ~chongo/.rc.cal

    refers to the a file 'rc.cal' under the home directory of 'chongo'.

    A file can be opened for either reading, writing, or appending.
    To do this, the 'fopen' function is used, which accepts a filename
    and an open mode, both as strings.  You use 'r' for reading, 'w'
    for writing, and 'a' for appending.  For example, to open the file
    'foo' for reading, the following could be used:

            fd = fopen('foo', 'r');

    If the open is unsuccessful, the numeric value of errno is returned.
    If the open is successful, a value of type 'file' will be returned.
    You can use the 'isfile' function to test the return value to see
    if the open succeeded.  You should assign the return value of fopen
    to a variable for later use.  File values can be copied to more than
    one variable, and using any of the variables with the same file value
    will produce the same results.

    If you overwrite a variable containing a file value or don't save the
    result of an 'fopen', the opened file still remains open.  Such 'lost'
    files can be recovered by using the 'files' function.  This function
    either takes no arguments or else takes one integer argument.  If no
    arguments are given, then 'files' returns the maximum number of opened
    files.  If an argument is given, then the 'files' function uses it as
    an index into an internal table of open files, and returns a value
    referring to one the open files.  If that entry in the table is not
    in use, then the null value is returned instead.  Index 0 always
    refers to standard input, index 1 always refers to standard output,
    and index 2 always refers to standard error.  These three files are
    already open by the calculator and cannot be closed.  As an example
    of using 'files', if you wanted to assign a file value which is
    equivalent to stdout, you could use:

            stdout = files(1);

     Or for example, if you wanted to assign a file value which is
     equivalent to stdin, you could use:

            stdout = files(0);

    And for stderr:

            stderr = files(2);

    The 'fclose' function is used to close a file which had been opened.
    When this is done, the file value associated with the file remains
    a file value, but appears 'closed', and cannot be used in further
    file-related calls (except fclose) without causing errors.  This same
    action occurs to all copies of the file value.  You do not need to
    explicitly close all the copies of a file value.  The 'fclose'
    function returns the numeric value of errno if there had been an
    error using the file, or the null value if there was no error.

    The builtin 'strerror' can be use to convert an errno number into
    a slightly more meaningful error message:

            badfile = fopen("not_a_file", "r");
            if (!isfile(badfile)) {
                print "error #" : badfile : ":", strerror(badfile);
            }

    File values can be printed.  When this is done, the filename of the
    opened file is printed inside of quote marks.  If the file value had
    been closed, then the null string is printed.  If a file value is the
    result of a top-level expression, then in addition to the filename,
    the open mode, file position, and possible EOF, error, and closed
    status is also displayed.

    File values can be used inside of 'if' tests.  When this is done,
    an opened file is TRUE, and a closed file is FALSE.  As an example
    of this, the following loop will print the names of all the currently
    opened non-standard files with their indexes, and then close them:

            for (i = 3; i < files(); i++) {
                    if (files(i)) {
                            print i, files(i);
                            fclose(files(i));
                    }
            }

    The functions to read from files are 'fgetline' and 'fgetc'.
    The 'fgetline' function accepts a file value, and returns the next
    input line from a file.  The line is returned as a string value, and
    does not contain the end of line character.  Empty lines return the
    null string.  When the end of file is reached, fgetline returns the
    null value.  (Note the distinction between a null string and a null
    value.)  If the line contained a numeric value, then the 'eval'
    function can then be used to convert the string to a numeric value.
    Care should be used when doing this, however, since eval will
    generate an error if the string doesn't represent a valid expression.
    The 'fgetc' function returns the next character from a file as a
    single character string.  It returns the null value when end of file
    is reached.

    Reading from standard input when calc is part of a pipe works
    as long as the -p flag is given to calc.  For example, this
    will print "chongo was here":

            echo chongo was here | calc -p 'print fgetline(files(0));'

    while this does not:

            echo chongo was here | calc 'print fgetline(files(0));'

    nor will this print "chongo was here":

            echo chongo was here | calc -i 'print fgetline(files(0));'

    This is because without -p, the interactive parser, in an effort
    to parse interactive commands, flushes data on standard input.

    On the other hand, once interactive mode is entered, reading
    from standard input works as expected.  For example, this works:

            $ calc
            C-style arbitrary precision calculator (version 2.12.6.0)
            Calc is open software. For license details type:  help copyright
            [Type "exit" to exit, or "help" for help.]

            ; str = fgetline(files(0))
            this text was typed into stdin
            ; print str
            this text was typed into stdin

    The 'printf' and 'fprintf' functions are used to print results to a
    file (which could be stdout or stderr).  The 'fprintf' function
    accepts a file variable, whereas the 'printf' function assumes the
    use of 'files(1)' (stdout).  They both require a format string, which
    is used in almost the same way as in normal C.  The differences come
    in the interpretation of values to be printed for various formats.
    Unlike in C, where an unmatched format type and value will cause
    problems, in the calculator nothing bad will happen.  This is because
    the calculator knows the types of all values, and will handle them
    all reasonably.  What this means is that you can (for example), always
    use %s or %d in your format strings, even if you are printing a non-
    string or non-numeric value.  For example, the following is valid:

            printf("Two values are %d and %s\n", "fred", 4567);

    and will print "Two values are fred and 4567".

    Using particular format characters, however, is still useful if
    you wish to use width or precision arguments in the format, or if
    you wish to print numbers in a particular format.  The following
    is a list of the possible numeric formats:

            %d          print in currently defined numeric format
            %f          print as floating point
            %e          print as exponential
            %r          print as decimal fractions
            %x          print as hex fractions
            %o          print as octal fractions
            %b          print as binary fractions

    Note then, that using %d in the format makes the output configurable
    by using the 'config' function to change the output mode, whereas
    the other formats override the mode and force the output to be in
    the specified format.

    Using the precision argument will override the 'config' function
    to set the number of decimal places printed.  For example:

            printf("The number is %.100f\n", 1/3);

    will print 100 decimal places no matter what the display configuration
    value is set to.

    The %s and %c formats are identical, and will print out the string
    representation of the value.  In these cases, the precision argument
    will truncate the output the same way as in standard C.

    If a matrix or list is printed, then the output mode and precision
    affects the printing of each individual element.  However, field
    widths are ignored since these values print using multiple lines.
    Field widths are also ignored if an object value prints on multiple
    lines.

    The functions 'fputc' and 'fputs' write a character and string to
    a file respectively.

    The final file-related functions are 'fflush', 'ferror', and 'feof'.
    The 'fflush' function forces buffered output to a file.  The 'ferror'
    function returns nonzero if an error had occurred to a file.  The
    'feof' function returns nonzero if end of file has been reached
    while reading a file.

    The 'strprintf' function formats output similarly to 'printf',
    but the output is returned as a string value instead of being
    printed.

## 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.
##
## Under source code control:   1991/07/21 04:37:19
## 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/

*************
* history
*************

Command history

    There is a command line editor and history mechanism built
    into calc, which is active when stdin is a terminal.  When
    stdin is not a terminal, then the command line editor is
    disabled.

    Lines of input to calc are always terminated by the return
    (or enter) key.  When the return key is typed, then the current
    line is executed and is also saved into a command history list
    for future recall.

    Before the return key is typed, the current line can be edited
    using emacs-like editing commands.  As examples, ^A moves to
    the beginning of the line, ^F moves forwards through the line,
    backspace removes characters from the line, and ^K kills the
    rest of the line.

    Previously entered commands can be recalled by using the history
    list.  The history list functions in a LRU manner, with no
    duplicated lines.  This means that the most recently entered
    lines are always at the end of the history list where they are
    easiest to recall.

    Typing <esc>h lists all of the commands in the command history
    and numbers the lines.  The most recently executed line is always
    number 1, the next most recent number 2, and so on.  The numbering
    for a particular command therefore changes as lines are entered.

    Typing a number at the beginning of a line followed by <esc>g
    will recall that numbered line.  So that for example, 2<esc>g
    will recall the second most recent line that was entered.

    The ^P and ^N keys move up and down the lines in the history list.
    If they attempt to go off the top or bottom of the list, then a
    blank line is shown to indicate this, and then they wrap around
    to the other end of the list.

    Typing a string followed by a ^R will search backwards through
    the history and recall the most recent command which begins
    with that string.

    Typing ^O inserts the current line at the end of the history list
    without executing it, and starts a new line.  This is useful to
    rearrange old history lines to become recent, or to save a partially
    completed command so that another command can be typed ahead of it.

    If your terminal has arrow keys which generate escape sequences
    of a particular kind (<esc>[A and so on), then you can use
    those arrow keys in place of the ^B, ^F, ^P, and ^N keys.

    The actual keys used for editing are defined in a bindings file,
    usually called /usr/local/lib/calc/bindings.  Changing the entries
    in this file will change the key bindings used for editing.  If the
    file is not readable, then a message will be output and command
    line editing is disabled.  In this case you can only edit each
    line as provided by the terminal driver in the operating system.

    A shell command can be executed by typing '!cmd', where cmd
    is the command to execute.  If cmd is not given, then a shell
    command level is started.

## 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.
##
## Under source code control:   1991/07/21 04:37:20
## 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/

*************
* interrupt
*************

Interrupts

    While a calculation is in progress, you can generate the SIGINT
    signal, and the calculator will catch it.  At appropriate points
    within a calculation, the calculator will check that the signal
    has been given, and will abort the calculation cleanly.  If the
    calculator is in the middle of a large calculation, it might be
    a while before the interrupt has an effect.

    You can generate the SIGINT signal multiple times if necessary,
    and each time the calculator will abort the calculation at a more
    risky place within the calculation.  Each new interrupt prints a
    message of the form:

            [Abort level n]

    where n ranges from 1 to 3.  For n equal to 1, the calculator will
    abort calculations at the next statement boundary specified by an
    ABORT opcode as described below.  For n equal to 2, the calculator
    will abort calculations at the next opcode boundary.  For n equal to 3,
    the calculator will abort calculations at the next attempt to allocate
    memory for the result of an integer arithmetic operation; this
    level may be appropriate for stopping a builtin operation like
    inversion of a large matrix.

    If a final interrupt is given when n is 3, the calculator will
    immediately abort the current calculation and longjmp back to the
    top level command level.  Doing this may result in corrupted data
    structures and unpredictable future behavior, and so should only
    be done as a last resort.  You are advised to quit the calculator
    after this has been done.

ABORT opcodes

    If config("trace") & 2 is zero, ABORT opcodes are introduced at
    various places in the opcodes for evaluation of command lines
    and functions defined by "define ... { ... }" commands.  In the
    following, config("trace") has been set equal to 8 so that opcodes
    are displayed when a function is defined.   The function f(x)
    evaluates x + (x - 1) + (x - 2) + ... until a zero term is
    encountered.  If f() is called with a negative or fractional x,
    the calculation is never completed and to stop it, an interruption
    (on many systems, by ctrl-C) will be necessary.

        ; config("trace", 8),
        ; define f(x) {local s; while (x) {s += x--} return s}
        0: DEBUG line 2
        2: PARAMADDR x
        4: JUMPZ 19
        6: DEBUG line 2
        8: LOCALADDR s
        10: DUPLICATE
        11: PARAMADDR x
        13: POSTDEC
        14: POP
        15: ADD
        16: ASSIGNPOP
        17: JUMP 2
        19: DEBUG line 2
        21: LOCALADDR s
        23: RETURN
        f(x) defined

    (The line number following DEBUG refers to the line in the file
    from which the definition is read.)   If an attempt is made to
    evaluate f(-1), the effect of the DEBUG at opcode 6 ensures that
    a single SIGINT will stop the calculation at a start of
    {s += x--} loop.  In interactive mode, with ^C indicating
    input of ctrl-C, the displayed output is as in:

        ; f(-1)
        ^C
        [Abort level 1]
        "f": line 2: Calculation aborted at statement boundary

    The DEBUG opcodes are disabled by nonzero config("trace") & 2.
    Changing config("trace") to achieve this, and defining g(x) with
    the same definition as for f(x) gives:

        ; define g(x) {local s; while (x) {s += x--} return s}
        0: PARAMADDR x
        2: JUMPZ 15
        4: LOCALADDR s
        6: DUPLICATE
        7: PARAMADDR x
        9: POSTDEC
        10: POP
        11: ADD
        12: ASSIGNPOP
        13: JUMP 0
        15: LOCALADDR s
        17: RETURN
        g(x) defined

    If g(-1) is called, two interrupts are necessary, as in:

        ; g(-1)
        ^C
        [Abort level 1]
        ^C
        [Abort level 2]
        "g": Calculation aborted in opcode

## Copyright (C) 1999-2006  David I. Bell, Landon Curt Noll and 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.
##
## Under source code control:   1991/07/21 04:37:21
## 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/

*************
* list
*************

NAME
    list - create list of specified values

SYNOPSIS
    list([x, [x, ... ]])

TYPES
    x           any, &any

    return      list

DESCRIPTION
    This function returns a list that is composed of the arguments x.
    If no args are given, an empty list is returned.

    Lists are a sequence of values which are doubly linked so that
    elements can be removed or inserted anywhere within the list.
    The function 'list' creates a list with possible initial elements.
    For example,

            x = list(4, 6, 7);

    creates a list in the variable x of three elements, in the order
    4, 6, and 7.

    The 'push' and 'pop' functions insert or remove an element from
    the beginning of the list.  The 'append' and 'remove' functions
    insert or remove an element from the end of the list.  The 'insert'
    and 'delete' functions insert or delete an element from the middle
    (or ends) of a list.  The functions which insert elements return
    the null value, but the functions which remove an element return
    the element as their value.  The 'size' function returns the number
    of elements in the list.

    Note that these functions manipulate the actual list argument,
    instead of returning a new list.  Thus in the example:

            push(x, 9);

    x becomes a list of four elements, in the order 9, 4, 6, and 7.
    Lists can be copied by assigning them to another variable.

    An arbitrary element of a linked list can be accessed by using the
    double-bracket operator.  The beginning of the list has index 0.
    Thus in the new list x above, the expression x[[0]] returns the
    value of the first element of the list, which is 9.  Note that this
    indexing does not remove elements from the list.

    Since lists are doubly linked in memory, random access to arbitrary
    elements can be slow if the list is large.  However, for each list
    a pointer is kept to the latest indexed element, thus relatively
    sequential accesses to the elements in a list will not be slow.

    Lists can be searched for particular values by using the 'search'
    and 'rsearch' functions.  They return the element number of the
    found value (zero based), or null if the value does not exist in
    the list.

EXAMPLE
    ; list(2,"three",4i)

    list (3 elements, 3 nonzero):
      [[0]] = 2
      [[1]] = "three"
      [[2]] = 4i

    ; list()
            list (0 elements, 0 nonzero)

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    append, delete, insert, islist, pop, push, remove, rsearch, search, size

## 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.
##
## Under source code control:   1994/03/19 03:13:19
## 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/

*************
* mat
*************

NAME
    mat - keyword to create a matrix value

SYNOPSIS
    mat [index-range-list] [ = {value_0. ...} ]
    mat [] [= {value_0, ...}]
    mat variable_1 ... [index-range-list] [ = {value_0, ...} ]
    mat variable_1 ... [] [ = {value_0, ...} ]

    mat [index-range-list_1[index-ranges-list_2] ... [ = { { ...} ...}  ]

    decl id_1 id_2 ... [index-range-list] ...

TYPES
    index-range-list    range_1 [, range_2, ...]  up to 4 ranges
    range_1, ...                integer, or integer_1 : integer_2
    value, value_1, ... any
    variable_1 ...      lvalue
    decl                        declarator = global, static or local
    id_1, ...           identifier

DESCRIPTION
    The expression  mat [index-range-list]  returns a matrix value.
    This may be assigned to one or more lvalues A, B, ... by either

        mat A B ... [index-range-list]

    or

        A = B = ... = mat[index-range-list]

    If a variable is specified by an expression that is not a symbol with
    possibly object element specifiers, the expression should be enclosed
    in parentheses.  For example, parentheses are required in
    mat (A[2]) [3]  and mat (*p) [3]  but  mat P.x [3] is acceptable.

    When an index-range is specified as integer_1 : integer_2, where
    integer_1 and integer_2 are expressions which evaluate to integers,
    the index-range consists of all integers from the minimum of the
    two integers to the maximum of the two integers.  For example,
    mat[2:5, 0:4] and mat[5:2, 4:0] return the same matrix value.

    If an index-range is an expression which evaluates to an integer,
    the range is as if specified by 0 : integer - 1.  For example,
    mat[4] and mat[0:3] return the same 4-element matrix; mat[-2] and
    mat[-3:0] return the same 4-element matrix.

    If the variable A has a matrix value, then for integer indices
    i_1, i_2, ..., equal in number to the number of ranges specified at
    its creation, and such that each index is in the corresponding range,
    the matrix element associated with those index list is given as an
    lvalue by the expressions A[i_1, i_2, ...].

    The elements of the matrix are stored internally as a linear array
    in which locations are arranged in order of increasing indices.
    For example, in order of location, the six element of A = mat [2,3]
    are:

        A[0,0], A[0,1], A[0,2], A[1,0], A[1,1], and A[1,2].

    These elements may also be specified using the double-bracket operator
    with a single integer index as in A[[0]], A[[1]], ..., A[[5]].
    If p is assigned the value &A[0,0], the address of A[[i]] for 0 <= i < 6
    is p + i as long as A exists and a new value is not assigned to A.

    When a matrix is created, each element is initially assigned the
    value zero. Other values may be assigned then or later using the
    "= {...}" assignment operation.  Thus

        A = {value_0, value_1, ...}

    assigns the values value_0, value_1, ... to the elements A[[0]],
    A[[1]], ... Any blank "value" is passed over.  For example,

        A = {1, , 2}

    will assign the value 1 to A[[0]], 2 to A[[2]] and leave all other
    elements unchanged. Values may also be assigned to elements by
    simple assignments, as in A[0,0] = 1, A[0,2] = 2;

    If the index-range is left blank but an initializer list is specified
    as in:

        ; mat A[] = {1, 2 }
        ; B = mat[] = {1, , 3, }

    the matrix created is one-dimensional.  If the list contains a
    positive number n of values or blanks, the result is as if the
    range were specified by [n], i.e. the range of indices is from
    0 to n - 1. In the above examples, A is of size 2 with A[0] = 1
    and A[1] = 2;  B is of size 4 with B[0] = 1, B[1] = B[3] = 0,
    B[2] = 3.  The specification mat[] = { } creates the same as mat[1].

    If the index-range is left blank and no initializer list is specified,
    as in  mat C[]  or  C = mat[], the matrix assigned to C has zero
    dimension; this has one element C[].

    To assign a value using "= { ...}" at the same time as creating C,
    parentheses are required as in (mat[]) = {value}  or  (mat C[]) =
    {value}. Later a value may be assigned to C[] by  C[] = value  or
    C = {value}.

    The value assigned at any time to any element of a matrix can be of
    any type - number, string, list, matrix, object of previously specified
    type, etc.  For some matrix operations there are of course conditions
    that elements may have to satisfy: for example, addition of matrices
    requires that addition of corresponding elements be possible.
    If an element of a matrix is a structure for which indices or an
    object element specifier is required, an element of that structure is
    referred to by appropriate uses of [ ] or ., and so on if an element
    of that element is required.

    For example, one may have an expressions like:

        ; A[1,2][3].alpha[2];

    if A[1,2][3].alpha is a list with at least three elements, A[1,2][3] is
    an object of a type like  obj {alpha, beta}, A[1,2] is a matrix of
    type mat[4] and A is a mat[2,3] matrix.  When an element of a matrix
    is a matrix and the total number of indices does not exceed 4, the
    indices can be combined into one list, e.g. the A[1,2][3] in the
    above example can be shortened to A[1,2,3]. (Unlike C, A[1,2] cannot
    be expressed as A[1][2].)

    The function ismat(V) returns 1 if V is a matrix, 0 otherwise.

    isident(V) returns 1 if V is a square matrix with diagonal elements 1,
    off-diagonal elements zero, or a zero- or one-dimensional matrix with
    every element 1; otherwise zero is returned.         Thus  isident(V) = 1
    indicates that for  V * A  and  A * V  where A is any matrix of
    for which either product is defined and the elements of A are real
    or complex numbers, that product will equal A.

    If V is matrix-valued, test(V) returns 0 if every element of V tests
    as zero; otherwise 1 is returned.

    The dimension of a matrix A, i.e. the number of index-ranges in the
    initial creation of the matrix, is returned by the function matdim(A).
    For 1 <= i <= matdim(A), the minimum and maximum values for the i-th
    index range are returned by matmin(A, i) and matmax(A,i), respectively.
    The total number of elements in the matrix is returned by size(A).
    The sum of the elements in the matrix is returned by matsum(A).

    The default method of printing matrices is to give a line of information
    about the matrix, and to list on separate lines up to 15 elements,
    the indices and either the value (for numbers, strings, objects) or
    some descriptive information for lists or matrices, etc.
    Numbers are displayed in the current number-printing mode.
    The maximum number of elements to be printed can be assigned
    any nonnegative integer value m by config("maxprint", m).

    Users may define another method of printing matrices by defining a
    function mat_print(M); for example, for a not too big 2-dimensional
    matrix A it is a common practice to use a loop like:

        define mat_print(A) {
                local i,j;

                for (i = matmin(A,1); i <= matmax(A,1); i++) {
                        if (i != matmin(A,1))
                                printf("\t");
                        for (j = matmin(A,2); j <= matmax(A,2); j++)
                                printf(" [%d,%d]: %e", i, j, A[i,j]);
                        if (i != matmax(A,1))
                                printf("\n");
                }
        }

    So that when one defines a 2D matrix such as:

        ; mat X[2,3] = {1,2,3,4,5,6}

    then printing X results in:

        [0,0]: 1 [0,1]: 2 [0,2]: 3
        [1,0]: 4 [1,1]: 5 [1,2]: 6

    The default printing may be restored by

        ; undefine mat_print;

    The keyword "mat" followed by two or more index-range-lists returns a
    matrix with indices specified by the first list, whose elements are
    matrices as determined by the later index-range-lists.  For
    example  mat[2][3]  is a 2-element matrix, each of whose elements has
    as its value a 3-element matrix.  Values may be assigned to the
    elements of the innermost matrices by nested = {...} operations as in

        ; mat [2][3] = {{1,2,3},{4,5,6}}

    An example of the use of mat with a declarator is

        ; global mat A B [2,3], C [4]

    This creates, if they do not already exist, three global variables with
    names A, B, C, and assigns to A and B the value mat[2,3] and to C mat[4].

    Some operations are defined for matrices.

    A == B
        Returns 1 if A and B are of the same "shape" and "corresponding"
        elements are equal; otherwise 0 is returned.  Being of the same
        shape means they have the same dimension d, and for each i <= d,

            matmax(A,i) - matmin(A,i) == matmax(B,i) - matmin(B,i),

        One consequence of being the same shape is that the matrices will
        have the same size.   Elements "correspond" if they have the same
        double-bracket indices; thus A == B implies that A[[i]] == B[[i]]
        for 0 <= i < size(A) == size(B).

    A + B
    A - B
        These are defined A and B have the same shape, the element
        with double-bracket index j being evaluated by A[[j]] + B[[j]] and
        A[[j]] - B[[j]], respectively.  The index-ranges for the results
        are those for the matrix A.

    A[i,j]
        If A is two-dimensional, it is customary to speak of the indices
        i, j in A[i,j] as referring to rows and columns;  the number of
        rows is matmax(A,1) - matmin(A,1) + 1; the number of columns if
        matmax(A,2) - matmin(A,2) + 1.  A matrix is said to be square
        if it is two-dimensional and the number of rows is equal to the
        number of columns.

    A * B
        Multiplication is defined provided certain conditions by the
        dimensions and shapes of A and B are satisfied.  If both have
        dimension 2 and the column-index-list for A is the same as
        the row-index-list for B, C = A * B is defined in the usual
        way so that for i in the row-index-list of A and j in the
        column-index-list for B,

                C[i,j] =  Sum A[i,k] * B[k,j]

        the sum being over k in the column-index-list of A.  The same
        formula is used so long as the number of columns in A is the same
        as the number of rows in B and k is taken to refer to the offset
        from matmin(A,2) and matmin(B,1), respectively, for A and B.
        If the multiplications and additions required cannot be performed,
        an execution error may occur or the result for C may contain
        one or more error-values as elements.

        If A or B has dimension zero, the result for A * B is simply
        that of multiplying the elements of the other matrix on the
        left by A[] or on the right by B[].

        If both A and B have dimension 1, A * B is defined if A and B
        have the same size; the result has the same index-list as A
        and each element is the product of corresponding elements of
        A and B.  If A and B have the same index-list, this multiplication
        is consistent with multiplication of 2D matrices if A and B are
        taken to represent 2D matrices for which the off-diagonal elements
        are zero and the diagonal elements are those of A and B.
        the real and complex numbers.

        If A is of dimension 1 and B is of dimension 2, A * B is defined
        if the number of rows in B is the same as the size of A.  The
        result has the same index-lists as B; each row of B is multiplied
        on the left by the corresponding element of A.

        If A is of dimension 2 and B is of dimension 1, A * B is defined
        if number of columns in A is the same as the size of A.  The
        result has the same index-lists as A; each column of A is
        multiplied on the right by the corresponding element of B.

        The algebra of additions and multiplications involving both one-
        and two-dimensional matrices is particularly simple when all the
        elements are real or complex numbers and all the index-lists are
        the same, as occurs, for example, if for some positive integer n,
        all the matrices start as  mat [n]  or  mat [n,n].

    det(A)
        If A is a square, det(A) is evaluated by an algorithm that returns
        the determinant of A if the elements of A are real or complex
        numbers, and if such an A is non-singular, inverse(A) returns
        the inverse of A indexed in the same way as A.  For matrix A of
        dimension 0 or 1, det(A) is defined as the product of the elements
        of A in the order in which they occur in A, inverse(A) returns
        a matrix indexed in the same way as A with each element inverted.


    The following functions are defined to return matrices with the same
        index-ranges as A and the specified operations performed on all
        elements of A.  Here num is an arbitrary complex number (nonzero
        when it is a divisor), int an integer, rnd a rounding-type
        specifier integer, real a real number.

            num * A
            A * num
            A / num
            - A
            conj(A)
            A << int, A >> int
            scale(A, int)
            round(A, int, rnd)
            bround(A, int, rnd)
            appr(A, real, rnd)
            int(A)
            frac(A)
            A // real
            A % real
            A ^ int

    If A and B are one-dimensional of the same size dp(A, B) returns
        their dot-product, i.e. the sum of the products of corresponding
        elements.

    If A and B are one-dimension and of size 3, cp(A, B) returns their
        cross-product.

    randperm(A) returns a matrix indexed the same as A in which the elements
        of A have been randomly permuted.

    sort(A) returns a matrix indexed the same as A in which the elements
        of A have been sorted.

    If A is an lvalue whose current value is a matrix, matfill(A, v)
        assigns the value v to every element of A, and if also, A is
        square, matfill(A, v1, v2) assigns v1 to the off-diagonal elements,
        v2 to the diagonal elements.  To create and assign to A the unit
        n * n matrix, one may use matfill(mat A[n,n], 0, 1).

    For a square matrix A, mattrace(A) returns the trace of A, i.e. the
        sum of the diagonal elements.  For zero- or one-dimensional A,
        mattrace(A) returns the sum of the elements of A.

    For a two-dimensional matrix A, mattrans(A) returns the transpose
        of A, i.e. if A is mat[m,n], it returns a mat[n,m] matrix with
        [i,j] element equal to A[j,i].  For zero- or one-dimensional A,
        mattrace(A) returns a matrix with the same value as A.

    The functions search(A, value, start, end]) and
    rsearch(A, value, start, end]) return the first or last index i
    for which A[[i]] == value and start <= i < end, or if there is
    no such index, the null value.   For further information on default
    values and the use of an "accept" function, see the help files for
    search and rsearch.

    reverse(A) returns a matrix with the same index-lists as A but the
    elements in reversed order.

    The copy and blkcpy functions may be used to copy data to a matrix from
    a matrix or list, or from a matrix to a list.  In copying from a
    matrix to a matrix the matrices need not have the same dimension;
    in effect they are treated as linear arrays.

EXAMPLE
    ; obj point {x,y}
    ; mat A[5] = {1, 2+3i, "ab", mat[2] = {4,5}, obj point = {6,7}}
    ; A
    mat [5] (5 elements, 5 nonzero):
      [0] = 1
      [1] = 2+3i
      [2] = "ab"
      [3] = mat [2] (2 elements, 2 nonzero)
      [4] = obj point {6, 7}

    ; print A[0], A[1], A[2], A[3][0], A[4].x
    1 2+3i ab 4 6

    ; define point_add(a,b) = obj point = {a.x + b.x, a.y + b.y}
    point_add(a,b) defined

    ; mat [B] = {8, , "cd", mat[2] = {9,10}, obj point = {11,12}}
    ; A + B

    mat [5] (5 elements, 5 nonzero):
      [0] = 9
      [1] = 2+3i
      [2] = "abcd"
      [3] = mat [2] (2 elements, 2 nonzero)
      [4] = obj point {17, 19}

    ; mat C[2,2] = {1,2,3,4}
    ; C^10

    mat [2,2] (4 elements, 4 nonzero):
      [0,0] = 4783807
      [0,1] = 6972050
      [1,0] = 10458075
      [1,1] = 15241882

    ; C^-10

    mat [2,2] (4 elements, 4 nonzero):
      [0,0] = 14884.650390625
      [0,1] = -6808.642578125
      [1,0] = -10212.9638671875
      [1,1] = 4671.6865234375

    ; mat A[4] = {1,2,3,4}, A * reverse(A);

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

LIMITS
    The theoretical upper bound for the absolute values of indices is
    2^31 - 1, but the size of matrices that can be handled in practice will
    be limited by the availability of memory and what is an acceptable
    runtime.  For example, although it may take only a fraction of a
    second to invert a 10 * 10 matrix, it will probably take about 1000
    times as long to invert a 100 * 100 matrix.

LINK LIBRARY
    none

SEE ALSO
    ismat, matdim, matmax, matmin, mattrans, mattrace, matsum, matfill,
    det, inverse, isident, test, config, search, rsearch, reverse, copy,
    blkcpy, dp, cp, randperm, sort

## Copyright (C) 1999-2006,2018,2021  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.
##
## Under source code control:   1991/07/21 04:37:22
## 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/

*************
* obj
*************

Using objects

    Objects are user-defined types which are associated with user-
    defined functions to manipulate them.  Object types are defined
    similarly to structures in C, and consist of one or more elements.
    The advantage of an object is that the user-defined routines are
    automatically called by the calculator for various operations,
    such as addition, multiplication, and printing.  Thus they can be
    manipulated by the user as if they were just another kind of number.

    An example object type is "surd", which represents numbers of the form

            a + b*sqrt(D),

    where D is a fixed integer, and 'a' and 'b' are arbitrary rational
    numbers.  Addition, subtraction, multiplication, and division can be
    performed on such numbers, and the result can be put unambiguously
    into the same form.  (Complex numbers are an example of surds, where
    D is -1.)

    The "obj" statement defines either an object type or an actual
    variable of that type.  When defining the object type, the names of
    its elements are specified inside of a pair of braces.  To define
    the surd object type, the following could be used:

            obj surd {a, b};

    Here a and b are the element names for the two components of the
    surd object.  An object type can be defined more than once as long
    as the number of elements and their names are the same.

    When an object is created, the elements are all defined with zero
    values.  A user-defined routine should be provided which will place
    useful values in the elements.  For example, for an object of type
    'surd', a function called 'surd' can be defined to set the two
    components as follows:

            define surd(a, b)
            {
                    local x;

                    obj surd x;
                    x.a = a;
                    x.b = b;
                    return x;
            }

    When an operation is attempted for an object, user functions with
    particular names are automatically called to perform the operation.
    These names are created by concatenating the object type name and
    the operation name together with an underscore.  For example, when
    multiplying two objects of type surd, the function "surd_mul" is
    called.

    The user function is called with the necessary arguments for that
    operation.  For example, for "surd_mul", there are two arguments,
    which are the two numbers.  The order of the arguments is always
    the order of the binary operands.  If only one of the operands to
    a binary operator is an object, then the user function for that
    object type is still called.  If the two operands are of different
    object types, then the user function that is called is the one for
    the first operand.

    The above rules mean that for full generality, user functions
    should detect that one of their arguments is not of its own object
    type by using the 'istype' function, and then handle these cases
    specially.  In this way, users can mix normal numbers with object
    types.  (Functions which only have one operand don't have to worry
    about this.)  The following example of "surd_mul" demonstrates how
    to handle regular numbers when used together with surds:

            define surd_mul(a, b)
            {
                    local x;

                    obj surd x;
                    if (!istype(a, x)) {
                            /* a not of type surd */
                            x.a = b.a * a;
                            x.b = b.b * a;
                    } else if (!istype(b, x)) {
                            /* b not of type surd */
                            x.a = a.a * b;
                            x.b = a.b * b;
                    } else {
                            /* both are surds */
                            x.a = a.a * b.a + D * a.b * b.b;
                            x.b = a.a * b.b + a.b * b.a;
                    }
                    if (x.b == 0)
                            return x.a; /* normal number */
                    return x;           /* return surd */
            }

    In order to print the value of an object nicely, a user defined
    routine can be provided.  For small amounts of output, the print
    routine should not print a newline.  Also, it is most convenient
    if the printed object looks like the call to the creation routine.
    For output to be correctly collected within nested output calls,
    output should only go to stdout.  This means use the 'print'
    statement, the 'printf' function, or the 'fprintf' function with
    'files(1)' as the output file.  For example, for the "surd" object:

            define surd_print(a)
            {
                    print "surd(" : a.a : "," : a.b : ")" : ;
            }

    It is not necessary to provide routines for all possible operations
    for an object, if those operations can be defaulted or do not make
    sense for the object.  The calculator will attempt meaningful
    defaults for many operations if they are not defined.  For example,
    if 'surd_square' is not defined to square a number, then 'surd_mul'
    will be called to perform the squaring.  When a default is not
    possible, then an error will be generated.

    Please note: Arguments to object functions are always passed by
    reference (as if an '&' was specified for each variable in the call).
    Therefore, the function should not modify the parameters, but should
    copy them into local variables before modifying them.  This is done
    in order to make object calls quicker in general.

    The double-bracket operator can be used to reference the elements
    of any object in a generic manner.  When this is done, index 0
    corresponds to the first element name, index 1 to the second name,
    and so on.  The 'size' function will return the number of elements
    in an object.

    The following is a list of the operations possible for objects.
    The 'xx' in each function name is replaced with the actual object
    type name.  This table is displayed by the 'show objfunctions' command.

            Name        Args    Comments

            xx_print    1       print value, default prints elements
            xx_one      1       multiplicative identity, default is 1
            xx_test     1       logical test (false,true => 0,1),
                                  default tests elements
            xx_add      2
            xx_sub      2
            xx_neg      1       negative
            xx_mul      2
            xx_div      2       non-integral division
            xx_inv      1       multiplicative inverse
            xx_abs      2       absolute value within given error
            xx_norm     1       square of absolute value
            xx_conj     1       conjugate
            xx_pow      2       integer power, default does multiply,
                                  square, inverse
            xx_sgn      1       sign of value (-1, 0, 1)
            xx_cmp      2       equality (equal,nonequal => 0,1),
                                   default tests elements
            xx_rel      2       relative order, positive for >, etc.
            xx_quo      3       integer quotient
            xx_mod      3       remainder of division
            xx_int      1       integer part
            xx_frac     1       fractional part
            xx_inc      1       increment, default adds 1
            xx_dec      1       decrement, default subtracts 1
            xx_square   1       default multiplies by itself
            xx_scale    2       multiply by power of 2
            xx_shift    2       shift left by n bits (right if negative)
            xx_round    3       round to given number of decimal places
            xx_bround   3       round to given number of binary places
            xx_root     3       root of value within given error
            xx_sqrt     3       square root within given error
            xx_or       2       bitwise or
            xx_and      2       bitwise and
            xx_not      1       logical not
            xx_fact     1       factorial or postfix !
            xx_min      1       value for min(...)
            xx_max      1       value for max(...)
            xx_sum      1       value for sum(...)
            xx_assign   2       assign, defaults to a = b
            xx_xor      2       value for binary ~
            xx_comp     1       value for unary ~
            xx_content  1       unary hash op
            xx_hashop   2       binary hash op
            xx_backslash 1      unary backslash op
            xx_setminus 2       binary backslash op
            xx_plus     1       unary + op

    Also see the standard resource files:

            deg.cal
            dms.cal
            ellip.cal
            hms.cal
            mod.cal
            natnumset.cal
            poly.cal
            quat.cal
            regress.cal
            set8700.cal
            surd.cal
            test2300.cal
            test3100.cal

## Copyright (C) 1999,2010,2021  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.
##
## Under source code control:   1991/07/21 04:37:22
## 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/

*************
* operator
*************

operators

    The operators are similar to C, but there are some differences in
    the associativity and precedence rules for some operators.  In
    addition, there are several operators not in C, and some C
    operators are missing.  A more detailed discussion of situations
    that may be unexpected for the C programmer may be found in
    the 'unexpected' help file.

    Below is a list giving the operators arranged in order of
    precedence, from the least tightly binding to the most tightly
    binding.  Except where otherwise indicated, operators at the same
    level of precedence associate from left to right.

    Unlike C, calc has a definite order for evaluation of terms (adds
    in a sum, factors in a product, arguments for a function or a
    matrix, etc.).  This order is always from left to right. but
    skipping of terms may occur for ||, && and ? : .  For example,
    an expression of the form:

            A * B + C * D

    is evaluated in the following order:

            A
            B
            A * B
            C
            D
            C * D
            A * B + C * D

    This order of evaluation is significant if evaluation of a
    term changes a variable on which a later term depends.  For example:

            x++ * x++ + x++ * x++

    returns the value of:

            x * (x + 1) + (x + 2) * (x + 3)

    and increments x as if by x += 4.  Similarly, for functions f, g,
    the expression:

            f(x++, x++) + g(x++)

    evaluates to:

            f(x, x + 1) + g(x + 2)

    and increments x three times.

    In A || B, B is read only if A tests as false;  in A && B, B is
    read only if A tests as true.  Thus if x is nonzero,
    x++ || x++ returns x and increments x once; if x is zero,
    it returns x + 1 and increments x twice.


    ,   Comma operator.
            a, b returns the value of b.
            For situations in which a comma is used for another purpose
            (function arguments, array indexing, and the print statement),
            parenthesis must be used around the comma operator expression.
            E.g., if A is a matrix, A[(a, b), c] evaluates a, b, and c, and
            returns the value of A[b, c].

    +=  -=  *=  /=  %=  //=  &=  |=  <<=  >>=  ^=  **=
         Operator-with-assignments.
            These associate from left to right, e.g. a += b *= c has the
            effect of a = (a + b) * c, where only a is required to be an
            lvalue.  For the effect of b *= c; a += b; when both a and b
            are lvalues, use a += (b *= c).

    =   Assignment.
            As in C, this, when repeated, this associates from right to left,
            e.g. a = b = c has the effect of a = (b = c).  Here both a and b
            are to be lvalues.

    ? : Conditional value.
            a ? b : c  returns b if a tests as true (i.e. nonzero if
            a is a number), c otherwise.  Thus it is equivalent to:
            if (a) return b; else return c;.
            All that is required of the arguments in this function
            is that the "is-it-true?" test is meaningful for a.
            As in C, this operator associates from right to left,
            i.e. a ? b : c ? d : e is evaluated as a ? b : (c ? d : e).

    ||  Logical OR.
            Unlike C, the result for a || b is one of the operands
            a, b rather than one of the numbers 0 and 1.
            a || b is equivalent to a ? a : b, i.e. if a tests as
            true, a is returned, otherwise b.  The effect in a
            test like "if (a || b) ... " is the same as in C.

    &&  Logical AND.
            Unlike C, the result for a && b is one of the operands
            a, b rather than one of the numbers 0 and 1.
            a && b is equivalent to a ? b : a, i.e. if a tests as
            true, b is returned, otherwise a.  The effect in a
            test like "if (a && b) ... " is the same as in C.

    ==  !=  <=  >=  <  >
            Relations.

    +  -
            Binary plus and minus and unary plus and minus when applied to
            a first or only term.

    *  /  //  %
            Multiply, divide, and modulo.
            Please Note: The '/' operator is a fractional divide,
            whereas the '//' is an integral divide.  Thus think of '/'
            as division of real numbers, and think of '//' as division
            of integers (e.g., 8 / 3 is 8/3 whereas 8 // 3 is 2).
            The '%' is integral or fractional modulus (e.g., 11%4 is 3,
            and 10%pi() is ~0.575222).

    |   Bitwise OR.
            In a | b, both a and b are to be real integers;
            the signs of a and b are ignored, i.e.
            a | b = abs(a) | abs(b) and the result will
            be a non-negative integer.

    &   Bitwise AND.
            In a & b, both a and b are to be real integers;
            the signs of a and b are ignored as for a | b.

    ^  **  <<  >>
            Powers and shifts.
            The '^' and '**' are both exponentiation, e.g. 2^3
            returns 8, 2^-3 returns 0.125.  Note that in a^b, if
            'a' == 0 and 'b' is real, then is must be >= 0 as well.
            Also 0^0 and 0**0 return the value 1.

            For the shift operators both arguments are to be
            integers, or if the first is complex, it is to have
            integral real and imaginary parts.  Changing the
            sign of the second argument reverses the shift, e.g.
            a >> -b = a << b.  The result has the same sign as
            the first argument except that a nonzero value is
            reduced to zero by a sufficiently long shift to the
            right.  These operators associate right to left,
            e.g.  a << b ^ c = a << (b ^ c).

    +  -  !
            Plus (+) and minus (-) have their usual meanings as unary
            prefix operators at this level of precedence when applied to
            other than a first or only term.

            As a prefix operator, '!' is the logical NOT: !a returns 0 if
            a tests as nonzero, and 1 if a tests as zero, i.e. it is
            equivalent to a ? 0 : 1.  Be careful about
            using this as the first character of a top level command,
            since it is also used for executing shell commands.

            As a postfix operator ! gives the factorial function, i.e.
            a! = fact(a).

    ++  --
            Pre or post incrementing or decrementing.
            These are applicable only to variables.

    [ ]  [[ ]]  .  ( )
            Indexing, double-bracket indexing, element references,
            and function calls.  Indexing can only be applied to matrices,
            element references can only be applied to objects, but
            double-bracket indexing can be applied to matrices, objects,
            or lists.

    variables  constants  .  ( )
            These are variable names and constants, the special '.' symbol,
            or a parenthesized expression.  Variable names begin with a
            letter, but then can contain letters, digits, or underscores.
            Constants are numbers in various formats, or strings inside
            either single or double quote marks.


    The most significant difference from the order of precedence in
    C is that | and & have higher precedence than ==, +, -, *, / and %.
    For example, in C a == b | c * d is interpreted as:

            (a == b) | (c * d)

    and calc it is:

            a == ((b | c) * d)


    Most of the operators will accept any real or complex numbers
    as arguments.  The exceptions are:

    /  //  %
            Second argument must be nonzero.

    ^
            The exponent must be an integer.  When raising zero
            to a power, the exponent must be non-negative.

    |  &
            Both both arguments must be integers.

    <<  >>
            The shift amount must be an integer.  The value being
            shifted must be an integer or a complex number with
            integral real and imaginary parts.


    See the 'unexpected' help file for a list of unexpected
    surprises in calc syntax/usage.  Persons familiar with C should
    read the 'unexpected' help file to avoid confusion.

## Copyright (C) 1999,2021  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.
##
## 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/

*************
* resource
*************

Calc standard resource files
----------------------------

To load a resource file, try:

    read filename

You do not need to add the .cal extension to the filename.  Calc
will search along the $CALCPATH (see ``help environment'').

Normally a resource file will simply define some functions.  By default,
most resource files will print out a short message when they are read.
For example:

    ; read lucas
    lucas(h,n) defined
    gen_u2(h,n,v1) defined
    gen_u0(h,n,v1) defined
    rodseth_xhn(x,h,n) defined
    gen_v1(h,n) defined
    ldebug(funct,str) defined
    legacy_gen_v1(h,n) defined

will cause calc to load and execute the 'lucas.cal' resource file.
Executing the resource file will cause several functions to be defined.
Executing the lucas function:

    ; lucas(149,60)
            1
    ; lucas(146,61)
            0

shows that 149*2^60-1 is prime whereas 146*2^61-1 is not.

=-=

Calc resource file files are provided because they serve as examples of
how use the calc language, and/or because the authors thought them to
be useful!

=-=

By convention, a resource file only defines and/or initializes functions,
objects and variables.  (The regress.cal and testxxx.cal regression test
suite is an exception.)  Also by convention, an additional usage message
regarding important object and functions is printed.

If a resource file needs to load another resource file, it should use
the -once version of read:

    /* pull in needed resource files */
    read -once "surd"
    read -once "lucas"

This will cause the needed resource files to be read once.  If these
files have already been read, the read -once will act as a noop.

The "resource_debug" parameter is intended for controlling the possible
display of special information relating to functions, objects, and
other structures created by instructions in calc resource files.
Zero value of config("resource_debug") means that no such information
is displayed.  For other values, the non-zero bits which currently
have meanings are as follows:

    n           Meaning of bit n of config("resource_debug")

    0   When a function is defined, redefined or undefined at
        interactive level, a message saying what has been done
        is displayed.

    1   When a function is defined, redefined or undefined during
        the reading of a file, a message saying what has been done
        is displayed.

    2   Show func will display more information about a functions
        arguments as well as more argument summary information.

    3   During execution, allow calc standard resource files
        to output additional debugging information.

The value for config("resource_debug") in both oldstd and newstd is 3,
but if calc is invoked with the -d flag, its initial value is zero.
Thus, if calc is started without the -d flag, until config("resource_debug")
is changed, a message will be output when a function is defined
either interactively or during the reading of a file.

Sometimes the information printed is not enough.  In addition to the
standard information, one might want to print:

        * useful obj definitions
        * functions with optional args
        * functions with optional args where the param() interface is used

For these cases we suggest that you place at the bottom of your code
something that prints extra information if config("resource_debug") has
either of the bottom 2 bits set:

        if (config("resource_debug") & 3) {
                print "obj xyz defined";
                print "funcA([val1 [, val2]]) defined";
                print "funcB(size, mass, ...) defined";
        }

If your the resource file needs to output special debugging information,
we recommend that you check for bit 3 of the config("resource_debug")
before printing the debug statement:

        if (config("resource_debug") & 8) {
                print "DEBUG: This a sample debug statement";
        }

=-=

The following is a brief description of some of the calc resource files
that are shipped with calc.  See above for example of how to read in
and execute these files.

alg_config.cal

    global test_time
    mul_loop(repeat,x) defined
    mul_ratio(len) defined
    best_mul2() defined
    sq_loop(repeat,x) defined
    sq_ratio(len) defined
    best_sq2() defined
    pow_loop(repeat,x,ex) defined
    pow_ratio(len) defined
    best_pow2() defined

    These functions search for an optimal value of config("mul2"),
    config("sq2"), and config("pow2").  The calc default values of these
    configuration values were set by running this resource file on a
    1.8GHz AMD 32-bit CPU of ~3406 BogoMIPS.

    The best_mul2() function returns the optimal value of config("mul2").
    The best_sq2() function returns the optimal value of config("sq2").
    The best_pow2() function returns the optimal value of config("pow2").
    The other functions are just support functions.

    By design, best_mul2(), best_sq2(), and best_pow2() take a few
    minutes to run.  These functions increase the number of times a
    given computational loop is executed until a minimum amount of CPU
    time is consumed.  To watch these functions progress, one can set
    the config("user_debug") value.

    Here is a suggested way to use this resource file:

        ; read alg_config
        ; config("user_debug",2),;
        ; best_mul2(); best_sq2(); best_pow2();
        ; best_mul2(); best_sq2(); best_pow2();
        ; best_mul2(); best_sq2(); best_pow2();

    NOTE: It is perfectly normal for the optimal value returned to differ
    slightly from run to run.  Slight variations due to inaccuracy in
    CPU timings will cause the best value returned to differ slightly
    from run to run.

    One can use a calc startup file to change the initial values of
    config("mul2"), config("sq2"), and config("pow2").  For example one
    can place into ~/.calcrc these lines:

        config("mul2", 1780),;
        config("sq2", 3388),;
        config("pow2", 176),;

    to automatically and silently change these config values.
    See help/config and CALCRC in help/environment for more information.


beer.cal

    This calc resource is calc's contribution to the 99 Bottles of Beer
    web page:

        http://www.ionet.net/~timtroyr/funhouse/beer.html#calc

     NOTE: This resource produces a lot of output.  :-)


bernoulli.cal

    B(n)

    Calculate the nth Bernoulli number.

    NOTE: There is now a bernoulli() builtin function.  This file is
          left here for backward compatibility and now simply returns
          the builtin function.


bernpoly.cal

    bernpoly(n,z)

    Computes the nth Bernoulli polynomial at z for arbitrary n,z.  See:

        http://en.wikipedia.org/wiki/Bernoulli_polynomials
        http://mathworld.wolfram.com/BernoulliPolynomial.html

    for further information


bigprime.cal

    bigprime(a, m, p)

    A prime test, base a, on p*2^x+1 for even x>m.


brentsolve.cal

    brentsolve(low, high,eps)

    A root-finder implemented with the Brent-Dekker trick.

    brentsolve2(low, high,which,eps)

    The second function, brentsolve2(low, high,which,eps) has some lines
    added to make it easier to hard-code the name of the helper function
    different from the obligatory "f".

    See:

        http://en.wikipedia.org/wiki/Brent%27s_method
        http://mathworld.wolfram.com/BrentsMethod.html

    to find out more about the Brent-Dekker method.


constants.cal

    e()
    G()

    An implementation of different constants to arbitrary precision.


chi.cal

    Z(x[, eps])
    P(x[, eps])
    chi_prob(chi_sq, v[, eps])

    Computes the Probability, given the Null Hypothesis, that a given
    Chi squared values >= chi_sq with v degrees of freedom.

    The chi_prob() function does not work well with odd degrees of freedom.
    It is reasonable with even degrees of freedom, although one must give
    a sufficiently small error term as the degrees gets large (>100).

    The Z(x) and P(x) are internal statistical functions.

    eps is an optional epsilon() like error term.


chrem.cal

    chrem(r1,m1 [,r2,m2, ...])
    chrem(rlist, mlist)

    Chinese remainder theorem/problem solver.


comma.cal

    Convert numbers into strings with 3-digit group and integer-fraction
    separators.

    If the value is an integer, the integer-fraction separator is not used.

    str_comma(x, [group, [decimal]])

        Convert x into a string.

        If group is given and is a string, group will be used as
        the 3-digit group separator, otherwise the default 3-digit
        group separator will be used.

        If decimal is given and is a string, group will be used as
        the integer-fraction separator, otherwise the default
        integer-fraction separator will be used.

        The decimal and group arguments are optional.

    set_default_group_separator(group)

        Change the default 3-digit group separator if group is a string,
        otherwise the default 3-digit group separator will not be
        changed.  Return the old 3-digit group separator.

    set_default_decimal_separator(decimal)

        Change the default 3-digit group separator if decimal is a
        string, otherwise the default integer-fraction separator
        will not be changed.  Return the old integer-fraction separator.

    print_comma(x, [group, [decimal]])

        Print the value produced by str_comma(x, [group, [decimal]])
        followed by a newline.

        If the str_comma() does not return a string, nothing is printed.

        The decimal and group arguments are optional.

        The value produced by str_comma() is returned.

    fprint_comma(fd, x, [group, [decimal]])

        Print the value produced by str_comma(x, [group, [decimal]]),
        without a trailing newline, on file fd.

        If the str_comma() does not return a string, nothing is printed.

        If fd is not an open file, nothing is printed.

        The decimal and group arguments are optional.

        The value produced by str_comma() is returned.


deg.cal

    deg(deg, min, sec)
    deg_add(a, b)
    deg_neg(a)
    deg_sub(a, b)
    deg_mul(a, b)
    deg_print(a)

    Calculate in degrees, minutes, and seconds.  For a more functional
    version see dms.cal.


dms.cal

    dms(deg, min, sec)
    dms_add(a, b)
    dms_neg(a)
    dms_sub(a, b)
    dms_mul(a, b)
    dms_print(a)
    dms_abs(a)
    dms_norm(a)
    dms_test(a)
    dms_int(a)
    dms_frac(a)
    dms_rel(a,b)
    dms_cmp(a,b)
    dms_inc(a)
    dms_dec(a)

    Calculate in degrees, minutes, and seconds.  Unlike deg.cal, increments
    are on the arc second level.  See also hms.cal.


dotest.cal

    dotest(dotest_file [,dotest_code [,dotest_maxcond]])

    dotest_file

        Search along CALCPATH for dotest_file, which contains lines that
        should evaluate to 1.  Comment lines and empty lines are ignored.
        Comment lines should use ## instead of the multi like /* ... */
        because lines are evaluated one line at a time.

    dotest_code

        Assign the code number that is to be printed at the start of
        each non-error line and after **** in each error line.
        The default code number is 999.

    dotest_maxcond

        The maximum number of error conditions that may be detected.
        An error condition is not a sign of a problem, in some cases
        a line deliberately forces an error condition.  A value of -1,
        the default, implies a maximum of 2147483647.

    Global variables and functions must be declared ahead of time because
    the dotest scope of evaluation is a line at a time.  For example:

        read dotest.cal
        read set8700.cal
        dotest("set8700.line");


ellip.cal

    efactor(iN, ia, B, force)

    Attempt to factor using the elliptic functions: y^2 = x^3 + a*x + b.


factorial.cal

    factorial(n)

    Calculates the product of the positive integers up to and including n.

    See:

        http://en.wikipedia.org/wiki/Factorial

    for information on the factorial. This function depends on the script
    toomcook.cal.


    primorial(a,b)

    Calculates the product of the primes between a and b. If a is not prime
    the next higher prime is taken as the starting point. If b is not prime
    the next lower prime is taking as the end point b. The end point b must
    not exceed 4294967291.  See:

        http://en.wikipedia.org/wiki/Primorial

    for information on the primorial.


factorial2.cal

    This file contents a small variety of integer functions that can, with
    more or less pressure, be related to the factorial.

    doublefactorial(n)

    Calculates the double factorial n!! with different algorithms for
        - n odd
        - n even and positive
        - n (real|complex) sans the negative half integers

    See:

        http://en.wikipedia.org/wiki/Double_factorial
        http://mathworld.wolfram.com/DoubleFactorial.html

    for information on the double factorial. This function depends on
    the script toomcook.cal, factorial.cal and specialfunctions.cal.


    binomial(n,k)

    Calculates the binomial coefficients for n large and k = k \pm
    n/2. Defaults to the built-in function for smaller and/or different
    values. Meant as a complete replacement for comb(n,k) with only a
    very small overhead.  See:

        http://en.wikipedia.org/wiki/Binomial_coefficient

    for information on the binomial. This function depends on the script
    toomcook.cal factorial.cal and specialfunctions.cal.


    bigcatalan(n)

    Calculates the n-th Catalan number for n large. It is useful
    above n~50,000 but defaults to the builtin function for smaller
    values.Meant as a complete replacement for catalan(n) with only a
    very small overhead.  See:

        http://en.wikipedia.org/wiki/Catalan_number
        http://mathworld.wolfram.com/CatalanNumber.html

    for information on Catalan numbers. This function depends on the scripts
    toomcook.cal, factorial.cal and specialfunctions.cal.


    stirling1(n,m)

    Calculates the Stirling number of the first kind. It does so with
    building a list of all of the smaller results. It might be a good
    idea, though, to run it once for the highest n,m first if many
    Stirling  numbers are needed at once, for example in a series.  See:

        http://en.wikipedia.org/wiki/Stirling_numbers_of_the_first_kind
        http://mathworld.wolfram.com/StirlingNumberoftheFirstKind.html
        Algorithm 3.17,  Donald Kreher and Douglas Simpson, "Combinatorial
          Algorithms", CRC Press, 1998, page 89.

    for information on Stirling numbers of the first kind.


    stirling2(n,m)
    stirling2caching(n,m)

    Calculate the Stirling number of the second kind.
    The first function stirling2(n,m) does it with the sum
                       m
                      ====
                 1    \      n      m - k
                 --    >    k  (- 1)      binomial(m, k)
                 m!   /
                      ====
                      k = 0

    The other function stirling2caching(n,m) does it by way of the
    re-occurrence relation and keeps all earlier results. This function
    is much slower for computing a single value than stirling2(n,m) but
    is very useful if many Stirling numbers are needed, for example in
    a series.  See:

        http://en.wikipedia.org/wiki/Stirling_numbers_of_the_second_kind
        http://mathworld.wolfram.com/StirlingNumberoftheSecondKind.html

        Algorithm 3.17,  Donald Kreher and Douglas Simpson, "Combinatorial
          Algorithms", CRC Press, 1998, page 89.

    for information on Stirling numbers of the second kind.


    bell(n)

    Calculate the n-th Bell number. This may take some time for large n.
    See:

        http://oeis.org/A000110
        http://en.wikipedia.org/wiki/Bell_number
        http://mathworld.wolfram.com/BellNumber.html

    for information on Bell numbers.


    subfactorial(n)

    Calculate the n-th subfactorial or derangement. This may take some
    time for large n.  See:

        http://mathworld.wolfram.com/Derangement.html
        http://en.wikipedia.org/wiki/Derangement

    for information on subfactorials.


    risingfactorial(x,n)

    Calculates the rising factorial or Pochammer symbol of almost arbitrary
    x,n.  See:

        http://en.wikipedia.org/wiki/Pochhammer_symbol
        http://mathworld.wolfram.com/PochhammerSymbol.html

    for information on rising factorials.

    fallingfactorial(x,n)

    Calculates the rising factorial of almost arbitrary x,n.  See:

        http://en.wikipedia.org/wiki/Pochhammer_symbol
        http://mathworld.wolfram.com/PochhammerSymbol.html

    for information on falling factorials.


fnv_util.cal

    Utility tools for FNV hash and "FNV-style" hash operations.

    These functions, if given non-standard values, will produce bogus results.
    In some cases, such as specifying the number of bits in the hash,
    using a non-power of 2 bit will produce a result that may work,
    but the hash will be only an "FNV-style" hash and not a true FNV hash.

    find_fnv_prime(bits)

        If bits == null(), this function will attempt to prompt stdin
        for a value and provide commends on the value of bits.

        given:
            bits        number of bits in the hash, null() ==> prompt for value

        returns:
            0 ==> no FNV prime found
            >0 ==> FNV prime

    deprecated_fnv0(bits, fnv_prime, string)

        If fnv_prime == null(), this function will try to compute the FNV prime
        for a hash of size bits.

        given:
            bits        number of bits in FNV hash
            fnv_prime   FNV prime, null() ==> generate suitable FNV prime if possible
            string      string to hash

        returns:
            FNV-0 hash, for size bytes, of string

        NOTE: This function does NOT attempt to determine that fnv_prime is prime.

    fnv_offset_basis(bits, fnv_prime)

        given:
            bits        number of bits in FNV hash
            fnv_prime   FNV prime, null() ==> generate suitable FNV prime if possible

        returns:
            FNV offset basis for a hash size of bits and an FNV prime of fnv_prime

        NOTE: This function does NOT attempt to determine that fnv_prime is prime.

    fnv1a_style_hash(bits, fnv_prime, prev_hash, string)

        given:
            bits        number of bits in FNV hash
            fnv_prime   FNV prime, null() ==> generate suitable FNV prime if possible
            prev_hash   previous hash value, null() ==> generate FNV offset basis
            string      string to hash

        returns:
            "FNV-style" hash of bits

        NOTE: This function does NOT attempt to determine that fnv_prime is prime.

gvec.cal

    gvec(function, vector)

    Vectorize any single-input function or trailing operator.


hello.cal

    Calc's contribution to the Hello World! page:

        http://www.latech.edu/~acm/HelloWorld.shtml
        http://www.latech.edu/~acm/helloworld/calc.html

     NOTE: This resource produces a lot of output.  :-)


hms.cal

    hms(hour, min, sec)
    hms_add(a, b)
    hms_neg(a)
    hms_sub(a, b)
    hms_mul(a, b)
    hms_print(a)
    hms_abs(a)
    hms_norm(a)
    hms_test(a)
    hms_int(a)
    hms_frac(a)
    hms_rel(a,b)
    hms_cmp(a,b)
    hms_inc(a)
    hms_dec(a)

    Calculate in hours, minutes, and seconds.  See also dmscal.


infinities.cal

    isinfinite(x)
    iscinf(x)
    ispinf(x)
    isninf(x)
    cinf()
    ninf()
    pinf()

    The symbolic handling of infinities. Needed for intnum.cal but might be
    useful elsewhere, too.


intfile.cal

    file2be(filename)

        Read filename and return an integer that is built from the
        octets in that file in Big Endian order.  The first octets
        of the file become the most significant bits of the integer.

    file2le(filename)

        Read filename and return an integer that is built from the
        octets in that file in Little Endian order.  The first octets
        of the file become the most significant bits of the integer.

    be2file(v, filename)

        Write the absolute value of v into filename in Big Endian order.
        The v argument must be on integer.  The most significant bits
        of the integer become the first octets of the file.

    le2file(v, filename)

        Write the absolute value of v into filename in Little Endian order.
        The v argument must be on integer.  The least significant bits
        of the integer become the last octets of the file.


intnum.cal

    quadtsdeletenodes()
    quadtscomputenodes(order, expo, eps)
    quadtscore(a, b, n)
    quadts(a, b, points)
    quadglcomputenodes(N)
    quadgldeletenodes()
    quadglcore(a, b, n)
    quadgl(a, b, points)
    quad(a, b, points = -1, method = "tanhsinh")
    makerange(start, end, steps)
    makecircle(radius, center, points)
    makeellipse(angle, a, b, center, points)
    makepoints()

    This file offers some methods for numerical integration. Implemented are
    the Gauss-Legendre and the tanh-sinh quadrature.

    All functions are useful to some extend but the main function for
    quadrature is quad(), which is not much more than an abstraction layer.

    The main workers are quadgl() for Gauss-Legendre and quadts() for the
    tanh-sinh quadrature. The limits of the integral can be anything in the
    complex plane and the extended real line. The latter means that infinite
    limits are supported by way of the symbolic infinities implemented in the
    file infinities.cal (automatically linked in by intnum.cal).

    Integration in parts and contour is supported by the "points" argument
    which takes either a number or a list. the functions starting with "make"
    allow for a less error prone use.

    The function to evaluate must have the name "f".

    Examples (shamelessly stolen from mpmath):

        ; define f(x){return sin(x);}
        f(x) defined
        ; quadts(0,pi())  -  2
            0.00000000000000000000
        ; quadgl(0,pi())  -  2
            0.00000000000000000000

    Sometimes rounding errors accumulate, it might be a good idea to crank up
    the working precision a notch or two.

        ; define f(x){ return exp(-x^2);}
        f(x) redefined
        ; quadts(0,pinf())  - pi()
            0.00000000000000000000
        ; quadgl(0,pinf())  - pi()
            0.00000000000000000001

        ; define f(x){ return exp(-x^2);}
        f(x) redefined
        ; quadgl(ninf(),pinf()) - sqrt(pi())
            0.00000000000000000000
        ; quadts(ninf(),pinf()) - sqrt(pi())
           -0.00000000000000000000

    Using the "points" parameter is a bit tricky

        ; define f(x){ return 1/x;  }
        f(x) redefined
        ; quadts(1,1,mat[3]={1i,-1,-1i})  -  2i*pi()
            0.00000000000000000001i
        ; quadgl(1,1,mat[3]={1i,-1,-1i})  -  2i*pi()
            0.00000000000000000001i

    The make* functions make it a bit simpler

        ; quadts(1,1,makepoints(1i,-1,-1i))  -  2i*pi()
            0.00000000000000000001i
        ; quadgl(1,1,makepoints(1i,-1,-1i))  -  2i*pi()
            0.00000000000000000001i

        ; define f(x){ return abs(sin(x));}
        f(x) redefined
        ; quadts(0,2*pi(),makepoints(pi()))  - 4
            0.00000000000000000000
        ; quadgl(0,2*pi(),makepoints(pi()))  - 4
            0.00000000000000000000

    The quad*core functions do not offer anything fancy but the third parameter
    controls the so called "order" which is just the number of nodes computed.
    This can be quite useful in some circumstances.

        ; quadgldeletenodes()
        ; define f(x){ return exp(x);}
        f(x) redefined
        ; s=usertime();quadglcore(-3,3)- (exp(3)-exp(-3));e=usertime();e-s
            0.00000000000000000001
            2.632164
        ; s=usertime();quadglcore(-3,3)- (exp(3)-exp(-3));e=usertime();e-s
            0.00000000000000000001
            0.016001
        ; quadgldeletenodes()
        ; s=usertime();quadglcore(-3,3,14)- (exp(3)-exp(-3));e=usertime();e-s
           -0.00000000000000000000
            0.024001
        ; s=usertime();quadglcore(-3,3,14)- (exp(3)-exp(-3));e=usertime();e-s
           -0.00000000000000000000
            0

    It is not much but can sum up. The tanh-sinh algorithm is not optimizable
    as much as the Gauss-Legendre algorithm but is per se much faster.

        ; s=usertime();quadtscore(-3,3)- (exp(3)-exp(-3));e=usertime();e-s
            -0.00000000000000000001
             0.128008
        ; s=usertime();quadtscore(-3,3)- (exp(3)-exp(-3));e=usertime();e-s
            -0.00000000000000000001
             0.036002
        ; s=usertime();quadtscore(-3,3,49)- (exp(3)-exp(-3));e=usertime();e-s
            -0.00000000000000000000
             0.036002
        ; s=usertime();quadtscore(-3,3,49)- (exp(3)-exp(-3));e=usertime();e-s
            -0.00000000000000000000
             0.01200


lambertw.cal

     lambertw(z,branch)

     Computes Lambert's W-function at "z" at branch "branch". See

         http://en.wikipedia.org/wiki/Lambert_W_function
         http://mathworld.wolfram.com/LambertW-Function.html
         https://cs.uwaterloo.ca/research/tr/1993/03/W.pdf
         http://arxiv.org/abs/1003.1628

     to get more information.

     This file includes also an implementation for the series described in
     Corless et al. (1996) eq. 4.22 (W-pdf) and Verebic (2010) (arxive link)
     eqs.35-37.

     The series has been implemented to get a different algorithm
     for checking the results. This was necessary because the results
     of the implementation in Maxima, the only program with a general
     lambert-w implementation at hand at that time, differed slightly. The
     Maxima versions tested were: Maxima 5.21.1 and 5.29.1. The current
     version of this code concurs with the results of Mathematica`s(tm)
     ProductLog[branch,z] with the tested values.

     The series is only valid for the branches 0,-1, real z, converges
     for values of z _very_ near the branch-point -exp(-1) only, and must
     be given the branches explicitly.  See the code in lambertw.cal
     for further information.


linear.cal

    linear(x0, y0, x1, y1, x)

    Returns the value y such that (x,y) in on the line (x0,y0), (x1,y1).
    Requires x0 != y0.


lnseries.cal

    lnseries(limit)
    lnfromseries(n)
    deletelnseries()

    Calculates a series of n natural logarithms at 1,2,3,4...n. It
    does so by computing the prime factorization of all of the number
    sequence 1,2,3...n, calculates the natural logarithms of the primes
    in 1,2,3...n and uses the above factorization to build the natural
    logarithms of the rest of the sequence by adding the logarithms of
    the primes in the factorization.  This is faster for high precision
    of the logarithms and/or long sequences.

    The sequence need to be initiated by running either lnseries(n) or
    lnfromseries(n) once with n the upper limit of the sequence.


lucas.cal

    lucas(h, n)

    Perform a primality test of h*2^n-1.

    gen_u2(h, n, v1)

    Generate u(2) for h*2^n-1.  This function is used by lucas(h, n),
    as the first term in the lucas sequence that is needed to
    prove that h*2^n-1 is prime or not prime.

    NOTE: Some call this term u(0).  The function gen_u0(h, n, v1)
          simply calls gen_u2(h, n, v1) for such people.  :-)

    gen_v1(h, v)

    Generate v(1) for h*2^n-1.  This function is used by lucas(h, n),
    via the gen_u2(h, n, v1), to supply the 3rd argument to gen_u2.

    legacy_gen_v1(h, n)

    Generate v(1) for h*2^n-1 using the legacy Amdahl 6 method.
    This function sometimes returns -1 for a few cases when
    h is a multiple of 3.  This function is NOT used by lucas(h, n).


lucas_chk.cal

    lucas_chk(high_n)

    Test all primes of the form h*2^n-1, with 1<=h<200 and n <= high_n.
    Requires lucas.cal to be loaded.  The highest useful high_n is 1000.

    Used by regress.cal during the 2100 test set.


mersenne.cal

    mersenne(p)

    Perform a primality test of 2^p-1, for prime p>1.


mfactor.cal

    mfactor(n [, start_k=1 [, rept_loop=10000 [, p_elim=17]]])

    Return the lowest factor of 2^n-1, for n > 0.  Starts looking for factors
    at 2*start_k*n+1.  Skips values that are multiples of primes <= p_elim.
    By default, start_k == 1, rept_loop = 10000 and p_elim = 17.

    The p_elim == 17 overhead takes ~3 minutes on an 200 MHz r4k CPU and
    requires about ~13 Megs of memory.  The p_elim == 13 overhead
    takes about 3 seconds and requires ~1.5 Megs of memory.

    The value p_elim == 17 is best for long factorizations.  It is the
    fastest even thought the initial startup overhead is larger than
    for p_elim == 13.


mod.cal

    lmod(a)
    mod_print(a)
    mod_one()
    mod_cmp(a, b)
    mod_rel(a, b)
    mod_add(a, b)
    mod_sub(a, b)
    mod_neg(a)
    mod_mul(a, b)
    mod_square(a)
    mod_inc(a)
    mod_dec(a)
    mod_inv(a)
    mod_div(a, b)
    mod_pow(a, b)

    Routines to handle numbers modulo a specified number.


natnumset.cal

    isset(a)
    setbound(n)
    empty()
    full()
    isin(a, b)
    addmember(a, n)
    rmmember(a, n)
    set()
    mkset(s)
    primes(a, b)
    set_max(a)
    set_min(a)
    set_not(a)
    set_cmp(a, b)
    set_rel(a, b)
    set_or(a, b)
    set_and(a, b)
    set_comp(a)
    set_setminus(a, b)
    set_diff(a,b)
    set_content(a)
    set_add(a, b)
    set_sub(a, b)
    set_mul(a, b)
    set_square(a)
    set_pow(a, n)
    set_sum(a)
    set_plus(a)
    interval(a, b)
    isinterval(a)
    set_mod(a, b)
    randset(n, a, b)
    polyvals(L, A)
    polyvals2(L, A, B)
    set_print(a)

    Demonstration of how the string operators and functions may be used
    for defining and working with sets of natural numbers not exceeding a
    user-specified bound.


palindrome.cal

    digitof(val,place)
    copalplace(d,place)
    upperhalf(val)
    mkpal(val)
    mkpalmiddigit(val,digit)
    ispal(val)
    nextpal(val)
    prevpal(val)
    nextprimepal(val)
    prevprimepal(val)

    Functions to form and manipulate palindromes in base 10.

    Important functions are:

        Find the next / previous palindrome:

            nextpal(val)
            prevpal(val)

        Test if a value is a palindrome:

            ispal(val)

        Find the next / previous palindrome that is a (highly probable) prime:

            nextprimepal(val)
            prevprimepal(val)


pell.cal

    pellx(D)
    pell(D)

    Solve Pell's equation; Returns the solution X to: X^2 - D * Y^2 = 1.
    Type the solution to Pell's equation for a particular D.


pi.cal

    qpi(epsilon)
    piforever()

    The qpi() calculate pi within the specified epsilon using the quartic
    convergence iteration.

    The piforever() prints digits of pi, nicely formatted, for as long
    as your free memory space and system up time allows.

    The piforever() function (written by Klaus Alexander Seistrup
    <klaus at seistrup dot dk>) was inspired by an algorithm conceived by
    Lambert Meertens.  See also the ABC Programmer's Handbook, by Geurts,
    Meertens & Pemberton, published by Prentice-Hall (UK) Ltd., 1990.


pix.cal

    pi_of_x(x)

    Calculate the number of primes < x using A(n+1)=A(n-1)+A(n-2).  This
    is a SLOW painful method ... the builtin pix(x) is much faster.
    Still, this method is interesting.


pollard.cal

    pfactor(N, N, ai, af)

    Factor using Pollard's p-1 method.


poly.cal

    Calculate with polynomials of one variable.  There are many functions.
    Read the documentation in the resource file.


prompt.cal

    adder()
    showvalues(str)

    Demonstration of some uses of prompt() and eval().


psqrt.cal

    psqrt(u, p)

    Calculate square roots modulo a prime


qtime.cal

    qtime(utc_hr_offset)

    Print the time as English sentence given the hours offset from UTC.


quat.cal

    quat(a, b, c, d)
    quat_print(a)
    quat_norm(a)
    quat_abs(a, e)
    quat_conj(a)
    quat_add(a, b)
    quat_sub(a, b)
    quat_inc(a)
    quat_dec(a)
    quat_neg(a)
    quat_mul(a, b)
    quat_div(a, b)
    quat_inv(a)
    quat_scale(a, b)
    quat_shift(a, b)

    Calculate using quaternions of the form: a + bi + cj + dk.  In these
    functions, quaternions are manipulated in the form: s + v, where
    s is a scalar and v is a vector of size 3.


randbitrun.cal

    randbitrun([run_cnt])

    Using randbit(1) to generate a sequence of random bits, determine if
    the number and length of identical bits runs match what is expected.
    By default, run_cnt is to test the next 65536 random values.

    This tests the subtractive 100 shuffle pseudo-random number generator.


randmprime.cal

    randmprime(bits, seed [,dbg])

    Find a prime of the form h*2^n-1 >= 2^bits for some given x.  The
    initial search points for 'h' and 'n' are selected by a cryptographic
    pseudo-random number generator.  The optional argument, dbg, if set
    to 1, 2 or 3 turn on various debugging print statements.


randombitrun.cal

    randombitrun([run_cnt])

    Using randombit(1) to generate a sequence of random bits, determine if
    the number and length of identical bits runs match what is expected.
    By default, run_cnt is to test the next 65536 random values.

    This tests the Blum-Blum-Shub generator.


randomrun.cal

    randomrun([run_cnt])

    Perform the "G. Run test" (pp. 65-68) as found in Knuth's "Art of
    Computer Programming - 2nd edition", Volume 2, Section 3.3.2 on
    the builtin rand() function.  This function will generate run_cnt
    64 bit values.  By default, run_cnt is to test the next 65536
    random values.

    This tests the Blum-Blum-Shub generator.


randrun.cal

    randrun([run_cnt])

    Perform the "G. Run test" (pp. 65-68) as found in Knuth's "Art of
    Computer Programming - 2nd edition", Volume 2, Section 3.3.2 on
    the builtin rand() function.  This function will generate run_cnt
    64 bit values.  By default, run_cnt is to test the next 65536
    random values.

    This tests the subtractive 100 shuffle pseudo-random number generator.

repeat.cal

    repeat(digit_set, repeat_count)

    Return the value of the digit_set repeated repeat_count times.
    Both digit_set and repeat_count must be integers > 0.

    For example repeat(423,5) returns the value 423423423423423,
    which is the digit_set 423 repeated 5 times.


regress.cal

    Test the correct execution of the calculator by reading this resource
    file.  Errors are reported with '****' messages, or worse. :-)


screen.cal

    up
    CUU /* same as up */
    down = CUD
    CUD /* same as down */
    forward
    CUF /* same as forward */
    back = CUB
    CUB /* same as back */
    save
    SCP /* same as save */
    restore
    RCP /* same as restore */
    cls
    home
    eraseline
    off
    bold
    faint
    italic
    blink
    rapidblink
    reverse
    concealed
    /* Lowercase indicates foreground, uppercase background */
    black
    red
    green
    yellow
    blue
    magenta
    cyan
    white
    Black
    Red
    Green
    Yellow
    Blue
    Magenta
    Cyan
    White

    Define ANSI control sequences providing (i.e., cursor movement,
    changing foreground or background color, etc.) for VT100 terminals
    and terminal window emulators (i.e., xterm, Apple OS/X Terminal,
    etc.) that support them.

    For example:

        read screen
        print green:"This is green. ":red:"This is red.":black


seedrandom.cal

    seedrandom(seed1, seed2, bitsize [,trials])

    Given:
        seed1 - a large random value (at least 10^20 and perhaps < 10^93)
        seed2 - a large random value (at least 10^20 and perhaps < 10^93)
        size - min Blum modulus as a power of 2 (at least 100, perhaps > 1024)
        trials - number of ptest() trials (default 25) (optional arg)

    Returns:
        the previous random state

    Seed the cryptographically strong Blum generator.  This functions allows
    one to use the raw srandom() without the burden of finding appropriate
    Blum primes for the modulus.


set8700.line

    A line-by-line evaluation file for dotest() (see dotest.cal).
    The set8700.cal file (and dotest.cal) should be read first.


smallfactors.cal

    smallfactors(x0)
    printsmallfactors(flist)

    Lists the prime factors of numbers smaller than 2^32. Try for example:
    printsmallfactors(smallfactors(10!)).


solve.cal

    solve(low, high, epsilon)

    Solve the equation f(x) = 0 to within the desired error value for x.
    The function 'f' must be defined outside of this routine, and the
    low and high values are guesses which must produce values with
    opposite signs.


specialfunctions.cal

    beta(a,b)

    Calculates the value of the beta function.  See:

        https://en.wikipedia.org/wiki/Beta_function
        http://mathworld.wolfram.com/BetaFunction.html
        http://dlmf.nist.gov/5.12

    for information on the beta function.


    betainc(a,b,z)

    Calculates the value of the regularized incomplete beta function.  See:

        https://en.wikipedia.org/wiki/Beta_function
        http://mathworld.wolfram.com/RegularizedBetaFunction.html
        http://dlmf.nist.gov/8.17

    for information on the regularized incomplete beta function.


    expoint(z)

    Calculates the value of the exponential integral Ei(z) function at z.
    See:

        http://en.wikipedia.org/wiki/Exponential_integral
        http://www.cs.utah.edu/~vpegorar/research/2011_JGT/

    for information on the exponential integral Ei(z) function.


    erf(z)

    Calculates the value of the error function at z.  See:

        http://en.wikipedia.org/wiki/Error_function

    for information on the error function function.


    erfc(z)

    Calculates the value of the complementary error function at z.  See:

        http://en.wikipedia.org/wiki/Error_function

    for information on the complementary error function function.


    erfi(z)

    Calculates the value of the imaginary error function at z.  See:

        http://en.wikipedia.org/wiki/Error_function

    for information on the imaginary error function function.


    erfinv(x)

    Calculates the inverse of the error function at x.  See:

        http://en.wikipedia.org/wiki/Error_function

    for information on the inverse of the error function function.


    faddeeva(z)

    Calculates the value of the complex error function at z.  See:

        http://en.wikipedia.org/wiki/Faddeeva_function

    for information on the complex error function function.


    gamma(z)

    Calculates the value of the Euler gamma function at z.  See:

        http://en.wikipedia.org/wiki/Gamma_function
        http://dlmf.nist.gov/5

    for information on the Euler gamma function.


    gammainc(a,z)

    Calculates the value of the lower incomplete gamma function for
    arbitrary a, z.  See:

        http://en.wikipedia.org/wiki/Incomplete_gamma_function

    for information on the lower incomplete gamma function.

    gammap(a,z)

    Calculates the value of the regularized lower incomplete gamma
    function for a, z with a not in -N.  See:

        http://en.wikipedia.org/wiki/Incomplete_gamma_function

    for information on the regularized lower incomplete gamma function.

    gammaq(a,z)

    Calculates the value of the regularized upper incomplete gamma
    function for a, z with a not in -N.  See:

        http://en.wikipedia.org/wiki/Incomplete_gamma_function

    for information on the regularized upper incomplete gamma function.


    heavisidestep(x)

    Computes the Heaviside stepp function (1+sign(x))/2


    harmonic(limit)

    Calculates partial values of the harmonic series up to limit.  See:

        http://en.wikipedia.org/wiki/Harmonic_series_(mathematics)
        http://mathworld.wolfram.com/HarmonicSeries.html

    for information on the harmonic series.


    lnbeta(a,b)

    Calculates the natural logarithm of the beta function.  See:

        https://en.wikipedia.org/wiki/Beta_function
        http://mathworld.wolfram.com/BetaFunction.html
        http://dlmf.nist.gov/5.12

    for information on the beta function.

    lngamma(z)

    Calculates the value of the logarithm of the Euler gamma function
    at z.  See:

        http://en.wikipedia.org/wiki/Gamma_function
        http://dlmf.nist.gov/5.15

    for information on the derivatives of the the Euler gamma function.


    polygamma(m,z)

    Calculates the value of the m-th derivative of the Euler gamma
    function at z.  See:

        http://en.wikipedia.org/wiki/Polygamma
        http://dlmf.nist.gov/5

    for information on the n-th derivative of the Euler gamma function. This
    function depends on the script zeta2.cal.


    psi(z)

    Calculates the value of the first derivative of the Euler gamma
    function at z.  See:

        http://en.wikipedia.org/wiki/Digamma_function
        http://dlmf.nist.gov/5

    for information on the first derivative of the Euler gamma function.


    zeta(s)

    Calculates the value of the Riemann Zeta function at s.  See:

        http://en.wikipedia.org/wiki/Riemann_zeta_function
        http://dlmf.nist.gov/25.2

    for information on the Riemann zeta function. This function depends
    on the script zeta2.cal.


splitbits.cal

    splitbits(x, b)

    Given an integer x, split the value into a list of integers,
    each of which is at most b bits long.

    The value b must be an integer > 0.

    The number of elements in the returned list is:

        ceil((highbit(x) + 1) / b)

    If x == 0, then a list of 1 element containing 0 is returned.

    If x < 0, then the two's compliment of abs(x) is returned.
    Even though calc represents negative integers as positive values
    with sign bit, the bits returned by this function are as if
    the integer converted as if the integer was a two's compliment
    value.  For example:

        ; L = splitbits(-1, 8);
        ; print L[[0]]
        255

        ; L = splitbits(-2, 8);
        ; print L[[0]]
        254

        ; L = splitbits(-3, 8);
        ; print L[[0]]
        253

    The first element of the list contains the lowest order bits
    of x.  The last element of the list contains the highest number
    bits of x.

    For example:

        ; x = 2^23209-1
        ; L = splitbits(x, 16);
        ; print size(L), L[[0]]

        ; print istype(2, 3i), istype(2, "2"), istype(2, null())
        0 0 0

        ; mat a[2]
        ; b = list(1,2,3)
        ; c = assoc()
        ; obj chongo {was, here} d;
        ; print istype(a,b), istype(b,c), istype(c,d)
        0 0 0


statistics.cal

    gammaincoctave(z,a)

    Computes the regularized incomplete gamma function in a way to
    correspond with the function in Octave.

    invbetainc(x,a,b)

    Computes the inverse of the regularized beta function. Does so the
    brute-force way which makes it a bit slower.

    betapdf(x,a,b)
    betacdf(x,a,b)
    betacdfinv(x,a,b)
    betamedian(a,b)
    betamode(a,b)
    betavariance(a,b)
    betalnvariance(a,b)
    betaskewness(a,b)
    betakurtosis(a,b)
    betaentropy(a,b)
    normalpdf(x,mu,sigma)
    normalcdf(x,mu,sigma)
    probit(p)
    normalcdfinv(p,mu,sigma)
    normalmean(mu,sigma)
    normalmedian(mu,sigma)
    normalmode(mu,sigma)
    normalvariance(mu,sigma)
    normalskewness(mu,sigma)
    normalkurtosis(mu,sigma)
    normalentropy(mu,sigma)
    normalmgf(mu,sigma,t)
    normalcf(mu,sigma,t)
    chisquaredpdf(x,k)
    chisquaredpcdf(x,k)
    chisquaredmean(x,k)
    chisquaredmedian(x,k)
    chisquaredmode(x,k)
    chisquaredvariance(x,k)
    chisquaredskewness(x,k)
    chisquaredkurtosis(x,k)
    chisquaredentropy(x,k)
    chisquaredmfg(k,t)
    chisquaredcf(k,t)

    Calculates a bunch of (hopefully) aptly named statistical functions.


strings.cal

    isascii(c)
    isblank(c)

    Implements some of the functions of libc's ctype.h and strings.h.

    NOTE: A number of the ctype.h and strings.h functions are now builtin
          functions in calc.

   WARNING: If the remaining functions in this calc resource file become
            calc builtin functions, then strings.cal may be removed in
            a future release.


sumsq.cal

    ss(p)

    Determine the unique two positive integers whose squares sum to the
    specified prime.  This is always possible for all primes of the form
    4N+1, and always impossible for primes of the form 4N-1.


sumtimes.cal

    timematsum(N)
    timelistsum(N)
    timematsort(N)
    timelistsort(N)
    timematreverse(N)
    timelistreverse(N)
    timematssq(N)
    timelistssq(N)
    timehmean(N,M)
    doalltimes(N)

    Give the user CPU time for various ways of evaluating sums, sums of
    squares, etc, for large lists and matrices.  N is the size of
    the list or matrix to use.  The doalltimes() function will run
    all of the sumtimes tests.  For example:

        doalltimes(1e6);


surd.cal

    surd(a, b)
    surd_print(a)
    surd_conj(a)
    surd_norm(a)
    surd_value(a, xepsilon)
    surd_add(a, b)
    surd_sub(a, b)
    surd_inc(a)
    surd_dec(a)
    surd_neg(a)
    surd_mul(a, b)
    surd_square(a)
    surd_scale(a, b)
    surd_shift(a, b)
    surd_div(a, b)
    surd_inv(a)
    surd_sgn(a)
    surd_cmp(a, b)
    surd_rel(a, b)

    Calculate using quadratic surds of the form: a + b * sqrt(D).


test2600.numfunc.cal

    global defaultverbose
    global err
    testismult(str, n, verbose)
    testsqrt(str, n, eps, verbose)
    testexp(str, n, eps, verbose)
    testln(str, n, eps, verbose)
    testpower(str, n, b, eps, verbose)
    testgcd(str, n, verbose)
    cpow(x, n, eps)
    cexp(x, eps)
    cln(x, eps)
    mkreal()
    mkcomplex()
    mkbigreal()
    mksmallreal()
    testappr(str, n, verbose)
    checkappr(x, y, z, verbose)
    checkresult(x, y, z, a)
    test2600(verbose, tnum)

    This resource files is used by regress.cal to test some of builtin
    functions in terms of accuracy and roundoff.


test2700.isqrt.cal

    global defaultverbose
    mknonnegreal()
    mkposreal()
    mkreal_2700()
    mknonzeroreal()
    mkposfrac()
    mkfrac()
    mksquarereal()
    mknonsquarereal()
    mkcomplex_2700()
    testcsqrt(str, n, verbose)
    checksqrt(x, y, z, v)
    checkavrem(A, B, X, eps)
    checkrounding(s, n, t, u, z)
    iscomsq(x)
    test2700(verbose, tnum)

    This resource files is used by regress.cal to test sqrt() for real and
    complex values.


test3100.matobj.cal

    obj res
    global md
    res_test(a)
    res_sub(a, b)
    res_mul(a, b)
    res_neg(a)
    res_inv(a)
    res(x)

    This resource file is used by regress.cal to test determinants of
    a matrix.


test3300.det.cal

    global defaultverbose
    global err
    testi(str, n, N, verbose)
    testr(str, n, N, verbose)
    test3300(verbose, tnum)

    This resource file is used by regress.cal to provide for more
    determinant tests.


test3400.trig.cal

    global defaultverbose
    global err
    test1(str, n, eps, verbose)
    test2(str, n, eps, verbose)
    test3(str, n, eps, verbose)
    test4(str, n, eps, verbose)
    test5(str, n, eps, verbose)
    test6(str, n, eps, verbose)
    test3400(verbose, tnum)

    This resource file is used by regress.cal to test trig functions.
    containing objects.


test4000.ptest.cal

    global defaultverbose
    global err
    global BASEB
    global BASE
    global COUNT
    global SKIP
    global RESIDUE
    global MODULUS
    global K1
    global H1
    global K2
    global H2
    global K3
    global H3
    plen(N) defined
    rlen(N) defined
    clen(N) defined
    ptimes(str, N, n, count, skip, verbose) defined
    ctimes(str, N, n, count, skip, verbose) defined
    crtimes(str, a, b, n, count, skip, verbose) defined
    ntimes(str, N, n, count, skip, residue, mod, verbose) defined
    testnextcand(str, N, n, cnt, skip, res, mod, verbose) defined
    testnext1(x, y, count, skip, residue, modulus) defined
    testprevcand(str, N, n, cnt, skip, res, mod, verbose) defined
    testprev1(x, y, count, skip, residue, modulus) defined
    test4000(verbose, tnum) defined

    This resource file is used by regress.cal to test ptest, nextcand and
    prevcand builtins.


test4100.redc.cal

    global defaultverbose
    global err
    global K1
    global K2
    global BASEB
    global BASE
    rlen_4100(N) defined
    olen(N) defined
    test1(x, y, m, k, z1, z2) defined
    testall(str, n, N, M, verbose) defined
    times(str, N, n, verbose) defined
    powtimes(str, N1, N2, n, verbose) defined
    inittimes(str, N, n, verbose) defined
    test4100(verbose, tnum) defined

    This resource file is used by regress.cal to test REDC operations.


test4600.fileop.cal

    stest(str [, verbose]) defined
    ttest([m, [n [,verbose]]]) defined
    sprint(x) defined
    findline(f,s) defined
    findlineold(f,s) defined
    test4600(verbose, tnum) defined

    This resource file is used by regress.cal to test searching in files.


test5100.newdecl.cal

    global a5100
    global b5100
    test5100(x) defined

    This resource file is used by regress.cal to test the new code generator
    declaration scope and order.


test5200.globstat.cal

    global a5200
    static a5200
    f5200(x) defined
    g5200(x) defined
    h5200(x) defined

    This resource file is used by regress.cal to test the fix of a
    global/static bug.


test8400.quit.cal

    test8400() defined

    This resource file is used by regress.cal to check for quit-based
    memory leaks.


test8500.divmod.cal

    global err_8500
    global L_8500
    global ver_8500
    global old_seed_8500
    global cfg_8500
    onetest_8500(a,b,rnd) defined
    divmod_8500(N, M1, M2, testnum) defined

    This resource file is used by regress.cal to the // and % operators.


test8600.maxargs.cal

    global min_8600
    global max_8600
    global hash_8600
    global hmean_8600

    This resource file is used by regress.cal to test a change of
    allowing up to 1024 args to be passed to a builtin function.


test8700.dotest.cal

    set8700_getA1() defined
    set8700_getA2() defined
    set8700_getvar() defined
    set8700_f(set8700_x) defined
    set8700_g(set8700_x) defined

    Declare globals and define functions needed by dotest() (see
    dotest.cal) to evaluate set8700.line a line at a time.


test8900.special.cal

    This function tests a number of calc resource functions contributed
    by Christoph Zurnieden.  These include:

        bernpoly.cal
        brentsolve.cal
        constants.cal
        factorial2.cal
        factorial.cal
        lambertw.cal
        lnseries.cal
        specialfunctions.cal
        statistics.cal
        toomcook.cal
        zeta2.cal


test9300.frem.cal

    global defaultverbose
    global err
    testfrem(x, y, verbose)
    testgcdrem(x, y, verbose)
    testf(str, n, verbose)
    testg(str, n, verbose)
    testh(str, n, N, verbose)
    test3500(verbose, n, N)

    This resource file is used by regress.cal to test the functions frem,
    fcnt, gcdrem.


toomcook.cal


    toomcook3(a,b)
    toomcook4(a,b)

    Toom-Cook multiplication algorithm.  Multiply two integers a,b by
    way of the Toom-Cook algorithm.  See:

        http://en.wikipedia.org/wiki/Toom%E2%80%93Cook_multiplication

    toomcook3square(a)
    toomcook4square(a)

    Square the integer a by way of the Toom-Cook algorithm.  See:

        http://en.wikipedia.org/wiki/Toom%E2%80%93Cook_multiplication

    The function toomCook4(a,b) calls the function toomCook3(a,b) which
    calls built-in multiplication at a specific cut-off point. The
    squaring functions act in the same way.


unitfrac.cal

    unitfrac(x)

    Represent a fraction as sum of distinct unit fractions.


varargs.cal

    sc(a, b, ...)

    Example program to use 'varargs'.  Program to sum the cubes of all
    the specified numbers.

write2file.cal

    w2f(filename,stream,fmt,value) defined
    wd2f(value) defined
    wx2f(value) defined

    write results to file

    This resource file serves as an example of how to perform file
    I/O. This write2file hows how to perform file I/O and is provided
    as an illustrative example.

xx_print.cal

    is_octet(a) defined
    list_print(a) defined
    mat_print (a) defined
    octet_print(a) defined
    blk_print(a) defined
    nblk_print (a) defined
    strchar(a) defined
    file_print(a) defined
    error_print(a) defined

    Demo for the xx_print object routines.


zeta2.cal

    hurwitzzeta(s,a)

    Calculate the value of the Hurwitz Zeta function.  See:

        http://en.wikipedia.org/wiki/Hurwitz_zeta_function
        http://dlmf.nist.gov/25.11

    for information on this special zeta function.


## Copyright (C) 2000,2014,2017,2021,2023  David I. Bell and Landon Curt Noll
##
## Primary author: 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.
##
## Under source code control:   1990/02/15 01:50:32
## File existed as early as:    before 1990
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/

*************
* script
*************

Calc shell scripts
------------------

    There are several ways calc may be used in shell scripts.  The
    syntax for these varies widely for different shells and systems,
    but common to most are commands like echo, if, for, goto, shift,
    and exit, as well as the accessing of environment parameters, shell
    variables, and command-line arguments.

    As a simple example, assuming a C or Bourne shell, let add be a
    file containing just one line:

            calc -q -- $1 + $2

    Then:

            ./add 1.23 4.56

    should respond with the display of:

            5.9

    The "-q" was included in the command to avoid reading of any
    start-up calc files which could contain commands not wanted
    here.  The "--" indicates that there are no more options;
    without it, if $1 began with '-', calc would interpret it as
    the first character of another option.  To execute the file,
    the strings "1.23" and "4.56" were assigned to $1 and $2, so
    calc was in effect asked to evaluate the string "1.23 + 4.56".

    By making add executable by a command like:

            chmod u+x add

    the command used here may be simplified to:

            ./add 1.23 4.56

    Here we shall assume that any script we refer to has been made
    executable in this way.

    Because $1 and $2, and instructions in the script, are to read
    by calc as expressions or commands, they may be much more
    complicated than in the above example, but if they involve
    characters with special interpretations by the shell (spaces
    for word separation, * or ? or [ ...] for file-name expansion,
    ! (without immediately following space) for history expansion,
    ( ... ) for shell-function arguments, { ... } for brace
    expansion, $ for parameter or variable expansion, <, <<, >, >>
    for redirection of input or output, etc.) it will usually be
    necessary to quote or escape th characters, or usually more
    conveniently, quote whole expressions with single or double
    quotes.

    For example, the add script should have no problem with
    commands like:

            ./add "sqrt(2)" "3 * 4"

            ./add "mat A[2,2] = {1,2,3,4}" "A^2"

            ./add "2 + 3i" "(3 + 4i)^2"

    If the shell arguments are to be integers, one could use
    scripts like the following with arithmetic expansion
    for the bash and ksh:

            declare -i a=$1
            declare -i b=$2
            calc -q -- $a + $b

    and for csh:

            @ a = $1
            @ b = $2
            calc -q -- $a + $b

    Specifying the shell for a script may be done by including
    in the script a first line with the "magic number" "#!" and
    the full file path for the shell as in:

            #!/bin/bash
            declare -i a=$1
            declare -i b=$2
            calc -q -- $a + $b

    For a script to multiply rather than add two expressions, one
    could have a file mul with the one line:

            calc -q -- $1 \* $2
    or:
            calc -q -- "$1 * $2"

    which will work so long as $1 and $2 are literal numbers, but
    will not work for:

            ./mul 2+3 4
    or:
            ./mul "2 + 3" 4

    both of which calc interprets as evaluating 2 + 3 * 4.  What should
    work for most shells is:

            calc -q -- "($1) * ($2)"

    For adding an arbitrary number of expressions that evaluate to
    rational numbers expressible with at most 20 decimal places,
    simple shell script could be used:

            s=0
            for i do
                    s=`calc -q -- $s + $i`
            done
            echo sum = $s

    This is not particularly efficient since it calls calc once for
    each argument.  Also, a more serious script would permit more
    general numbers.

    Another way of handling a sum of several expressions is with
    the script addall2 with a here document:

            calc "-q -s" $* << +
            global i, n, s;
            n = argv();
            for (i = 1; i < n; i++)
                    s += eval(argv(i));
            print "sum =", s;
            +

    In executing the command:

            ./addall2 2 3 4

    the $* in this script expands to  2 3 4, and because of the "-s"
    in the options, calc starts with argv(1) = "2", argv(2) = "3",
    argv(3)= "4".  As there is only one calc process involved and
    the eval() function accepts as argument any string that
    represents the body of a calc function, the strings argv(1),
    argv(2), ... could evaluate to any value types for which the
    additions to be performed are defined, and variables defined in
    one argv() can be used in later arguments.

    In case you are wondering, argv(0) returns the program
    or calc script name.  In the case of the above example,
    argv(0) = "./addall2".

    For systems that support interpreter files, essentially the
    same thing may be done more efficiently by using calc as an
    interpreter.  Assuming the full path for calc is
    /usr/local/bin/calc, one could use the file addall3 with contents

            #!/usr/bin/calc -q -f
            global i, n, s;
            n = argv();
            for (i = 1; i < n; i++)
                    s += eval(argv(i));
            print "sum =", s;

        IMPORTANT NOTE:

            The -f flag must be at the very end of the #! line.
            The #! line must be the first line of the executable file.
            The path after the #! must be the full path to the calc executable.

    After the command:

            ./addall3 2 3 4

    the arguments calc receives are argv(0) = "./addall3", argv(1) =
    "2", argv(3) = "3", argv(4) = "4".

    Another kind of script that can be useful is sqrts1:

            calc -q 'global s; while (scanf("%s", s) == 1) print sqrt(eval(s));'

    or what is essentially an interpreter equivalent sqrts2:

            #!/usr/local/bin/calc -q -f
            global s;
            while (scanf('%s', s) == 1)
                    print sqrt(eval(s));

    If sqrts is either of these scripts, the command:

            echo 27 2+3i | sqrts

    or, if datafile contains the one line:

            27 2+3i

    or the two lines:

            27
            2+3i

    either:

            cat datafile | ./sqrts
    or:
            ./sqrts < datafile

    should display the square-roots of 27 and 2+3i.  The output could
    be piped to another command by | or directed to a file by use of
    ; or >>.

    With no specified input, either sqrts1 or sqrts2 will wait
    without any prompt for input from the keyboard and as each line
    is completed display the square-roots of the expressions
    entered.  Exit can be achieved by entering exit or entering
    ctrl-D (interpreted as EOF) rather than a line of input.

    One advantage of an interpreter file like sqrts2 (which has only
    options, but neither "-s" nor "--" in its first line) is that it
    can be invoked with further options as in

            echo 2 3 4 | ./sqrts2 -i -D 32

    An advantage of non-interpreter files is that they can use shell
    features.  For example, for unquoted arguments or arguments in
    double quotes parameter expansion (indicated by unquoted '$') and
    command substitution (using backquotes) occur before lines are
    compiled by calc.  For example, if "doit" is an executable
    script with contents

            calc -q -- "$1($2)"

    it may be used as in:

            ./doit sqrt 7
    and:
            ./doit exp 7

    to display the values of sqrt(7) and exp(7).  The "--" prevents a
    leading '-' in the $1 argument as indicating one or more additional
    options. E.g., without the "--" in doit,

            ./doit -sqrt 7

    would be interpreted as:

            calc -q "-sqrt(7)"

    in which the dash in the quoted part would be taken as indicating a
    list of options -s, -q, -r, etc.; this would give an "illegal option"
    error as calc has no -r option.

    In invoking the doit script it is not necessary that $1 expand to a
    calc function name and $2 to an expression; all that is required is
    that:

            $1($2)

    expands to a string that calc will recognize as a command.  E.g.:

            ./doit "define f(x) = x^2; 2 + mod" "f(7), 6"

    does the same as:

            calc -q -- "define f(x) = x^2; 2 + mod(f(7), 6)"

    Essentially the same is achieved by the contents of doit is changed to:

            calc -q -p -- << +
            $1($2)
            +

    The "-p" stops calc going interactive; without it the effect would be
    be the same as that of a script with the one line:

            calc -q -i -- "$1($2)"

For more information use the following calc commands:

    help usage
    help argv
    help config
    help cscript

## Copyright (C) 2000,2014,2021  Landon Curt Noll and 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.
##
## Under source code control:   1999/11/30 05:29:48
## File existed as early as:    1999
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/


*************
* statement
*************

Statements

    Statements are very much like C statements.  Most statements act
    identically to those in C, but there are minor differences and
    some additions.  The following is a list of the statement types,
    with explanation of the non-C statements.

    Statements are generally terminated with semicolons or { ... }.

    C-like statements
    -----------------
    { statement }
    { statement; ... statement }


    C-like flow control
    -------------------
    if (expr) statement
    if (expr) statement else statement
    for (optionalexpr ; optionalexpr ; optionalexpr) statement
    while (expr) statement
    do statement while (expr)

            These all work like in normal C.

            IMPORTANT NOTE: When statement is of the form { ... },
            the leading { must be on the same line as the if, for,
            while or do keyword.

            This works as expected:

                if (expr) {
                    ...
                }

            However this WILL NOT WORK AS EXPECTED:

                if (expr)
                {
                    ...
                }

            because calc will parse the if being terminated by
            an empty statement followed by a

                if (expr) ;
                {
                    ...
                }

            In the same way, use these forms:

                for (optionalexpr ; optionalexpr ; optionalexpr) {
                        ...
                }

                while (expr) {
                        ...
                }

                do {
                        ...
                while (expr);

            where the initial { is on the SAME LINE as the if, while,
            for or do.

            See 'help expression' for details on expressions.
            See 'help builtin' for details on calc builtin functions.
            See 'help unexpanded' for things C programmers do not expect.
            See also 'help todo' and 'help bugs'.


    C-like flow breaks
    ------------------
    continue
    break
    goto label
            These all work like in normal C.

            See 'help expression' for details on expressions.
            See 'help builtin' for details on calc builtin functions.


    return
    ------
    return
    return expr
    return ( expr )
            This returns a value from a function.  Functions always
            have a return value, even if this statement is not used.
            If no return statement is executed, or if no expression
            is specified in the return statement, then the return
            value from the function is the null type.


    switch
    ------
    switch (expr) { caseclauses }
            Switch statements work similarly to C, except for the
            following.  A switch can be done on any type of value,
            and the case statements can be of any type of values.
            The case statements can also be expressions calculated
            at runtime.  The calculator compares the switch value
            with each case statement in the order specified, and
            selects the first case which matches.  The default case
            is the exception, and only matches once all other cases
            have been tested.


    matrix
    ------
    mat variable [dimension] [dimension] ...
    mat variable [dimension, dimension, ...]
    mat variable [] = { value, ... }
            This creates a matrix variable with the specified dimensions.
            Matrices can have from 1 to 4 dimensions.  When specifying
            multiple dimensions, you can use either the standard C syntax,
            or else you can use commas for separating the dimensions.
            For example, the following two statements are equivalent,
            and so will create the same two dimensional matrix:

                    mat foo[3][6];
                    mat foo[3,6];

            By default, each dimension is indexed starting at zero,
            as in normal C, and contains the specified number of
            elements.  However, this can be changed if a colon is
            used to separate two values.  If this is done, then the
            two values become the lower and upper bounds for indexing.
            This is convenient, for example, to create matrices whose
            first row and column begin at 1.  Examples of matrix
            definitions are:

                    mat x[3]    one dimension, bounds are 0-2
                    mat foo[4][5]       two dimensions, bounds are 0-3 and 0-4
                    mat a[-7:7] one dimension, bounds are (-7)-7
                    mat s[1:9,1:9]      two dimensions, bounds are 1-9 and 1-9

            Note that the MAT statement is not a declaration, but is
            executed at runtime.  Within a function, 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

    The man command is an alias for the help command.  For example:

            man jacobi

    Only calc help files may be displayed by the help and man commands.

## Copyright (C) 1999-2007,2017,2021  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.
##
## 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/

*************
* types
*************

Builtin types

    The calculator has the following built-in types:

    null value
            This is the undefined value type.  The function 'null'
            returns this value.  Functions which do not explicitly
            return a value return this type.  If a function is called
            with fewer parameters than it is defined for, then the
            missing parameters have the null type.  The null value is
            false if used in an IF test.

    rational numbers
            This is the basic data type of the calculator.
            These are fractions whose numerators and denominators
            can be arbitrarily large.  The fractions are always
            in lowest terms.  Integers have a denominator of 1.
            The numerator of the number contains the sign, so that
            the denominator is always positive.  When a number is
            entered in floating point or exponential notation, it is
            immediately converted to the appropriate fractional value.
            Printing a value as a floating point or exponential value
            involves a conversion from the fractional representation.

            Numbers are stored in binary format, so that in general,
            bit tests and shifts are quicker than multiplies and divides.
            Similarly, entering or displaying of numbers in binary,
            octal, or hex formats is quicker than in decimal.  The
            sign of a number does not affect the bit representation
            of a number.

    complex numbers
            Complex numbers are composed of real and imaginary parts,
            which are both fractions as defined above.  An integer which
            is followed by an 'i' character is a pure imaginary number.
            Complex numbers such as "2+3i" when typed in, are processed
            as the sum of a real and pure imaginary number, resulting
            in the desired complex number.  Therefore, parenthesis are
            sometimes necessary to avoid confusion, as in the two values:

                    1+2i ^2             (which is -3)
                    (1+2i) ^2   (which is -3+4i)

            Similar care is required when entering fractional complex
            numbers.  Note the differences below:

                    3/4i                (which is -(3/4)i)
                    3i/4                (which is (3/4)i)

            The imaginary unit itself is input using "1i".

    strings
            Strings are a sequence of zero or more characters.
            They are input using either of the single or double
            quote characters.  The quote mark which starts the
            string also ends it.  Various special characters can
            also be inserted using back-slash.  Example strings:

                    "hello\n"
                    "that's all"
                    'lots of """"'
                    'a'
                    ""

            There is no distinction between single character and
            multi-character strings.  The 'str' and 'ord' functions
            will convert between a single character string and its
            numeric value.  The 'str' and 'eval' functions will
            convert between longer strings and the corresponding
            numeric value (if legal).  The 'strcat', 'strlen', and
            'substr' functions are also useful.

    matrices
            These are one to four dimensional matrices, whose minimum
            and maximum bounds can be specified at runtime.  Unlike C,
            the minimum bounds of a matrix do not have to start at 0.
            The elements of a matrix can be of any type.  There are
            several built-in functions for matrices.  Matrices are
            created using the 'mat' statement.

    associations
            These are one to four dimensional matrices which can be
            indexed by arbitrary values, instead of just integers.
            These are also known as associative arrays.  The elements of
            an association can be of any type.  Very few operations are
            permitted on an association except for indexing.  Associations
            are created using the 'assoc' function.

    lists
            These are a sequence of values, which are linked together
            so that elements can be easily be inserted or removed
            anywhere in the list.  The values can be of any type.
            Lists are created using the 'list' function.

    files
            These are text files opened using stdio.  Files may be opened
            for sequential reading, writing, or appending.  Opening a
            file using the 'fopen' function returns a value which can
            then be used to perform I/O to that file.  File values can
            be copied by normal assignments between variables, or by
            using the result of the 'files' function.  Such copies are
            indistinguishable from each other.

    The calculator also has a number of special types that as used
    by some special builtin functions:

    rand
            A subtractive 100 shuffle pseudo-random number generator
            state.  This state is used by functions such as isrand()
            and srand().

    random
            A Blum-Blum-Shub pseudo-random number generator state.
            This state is used by functions such as israndom() and
            srandom().

## Copyright (C) 1999,2018  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.
##
## Under source code control:   1991/07/21 04:37:24
## 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/

*************
* unexpected
*************

Unexpected

    While calc is C-like, users of C will find some unexpected
    surprises in calc syntax and usage.  Persons familiar with C should
    review this file.

    Persons familiar with shell scripting may want to review this file
    as well, particularly notes dealing with command line evaluation
    and execution.


    The Comma
    =========

    The comma is also used for continuation of obj and mat creation
    expressions and for separation of expressions to be used for
    arguments or values in function calls or initialization lists.  The
    precedence order of these different uses is:  continuation,
    separator, comma operator.  For example, assuming the variables a,
    b, c, d, e, and object type xx have been defined, the arguments
    passed to f in:

            f(a, b, c, obj xx d, e)

    are a, b, c, and e, with e having the value of a newly created xx
    object.  In:

            f((a, b), c, (obj xx d), e)

    the arguments of f are b, c, d, e, with only d being a newly
    created xx object.

    In combination with other operators, the continuation use of the
    comma has the same precedence as [] and ., the separator use the
    same as the comma operator.  For example, assuming xx.mul() has
    been defined:

            f(a = b, obj xx c, d = {1,2} * obj xx e = {3,4})

    passes two arguments: a (with value b) and the product d * e of two
    initialized xx objects.


    ^ is not xor
    ** is exponentiation
    ====================

    In C, ^ is the xor operator. The expression:

            a ^ b

    yields "a to the b power", NOT "a xor b".

    Unlike in C, calc evaluates the expression:

            a ** b

    also yields "a to the b power".

    Here "a" and "b" can be a real value or a complex value:

        2^3                     3i^4
        2.5 ^ 3.5               0.5i ^ 0.25
        2.5 ^ 2.718i            3.13145i ^ 0.30103i

    In addition, "a" can be matrix.  In this case "b" must be an integer:

        mat a[2,2] = {1,2,3,4};
        a^3

    Note that 'a' == 0 and 'b' is real, then is must be >= 0 as well.
    Also 0^0 and 0**0 return the value 1.

    Be careful about the precedence of operators.  Note that:

        -1 ^ 0.5 == -1

    whereas:

        (-1) ^ 0.5 == 1i

    because the above expression in parsed as:

        -(1 ^ 0.5) == -1

    whereas:

        (-1) ^ 0.5 == 1i


    op= operators associate left to right
    =====================================

    Operator-with-assignments:

            +=  -=  *=  /=  %=  //=  &=  |=  <<=  >>=  ^=  **=

    associate from left to right instead of right to left as in C.
    For example:

            a += b *= c

    has the effect of:

            a = (a + b) * c

    where only 'a' is required to be an lvalue.  For the effect of:

            b *= c; a += b

    when both 'a' and 'b' are lvalues, use:

            a += (b *= c)


    || yields values other than 0 or 1
    ==================================

    In C:

            a || b

    will produce 0 or 1 depending on the logical evaluation
    of the expression.  In calc, this expression will produce
    either 'a' or 'b' and is equivalent to the expression:

            a ? a : b

    In other words, if 'a' is true, then 'a' is returned, otherwise
    'b' is returned.


    && yields values other than 0 or 1
    ==================================

    In C:

            a && b

    will produce 0 or 1 depending on the logical evaluation
    of the expression.  In calc, this expression will produce
    either 'a' or 'b' and is equivalent to the expression:

            a ? b : a

    In other words, if 'a' is true, then 'b' is returned, otherwise
    'a' is returned.


    / is fractional divide, // is integral divide
    =============================================

    In C:

            x/y

    performs integer division when 'x' and 'y' are integer types.
    In calc, this expression yields a rational number.

    Calc uses:

            x//y

    to perform division with integer truncation and is the equivalent to:

            int(x/y)


    | and & have higher precedence than ==, +, -, *, / and %
    ========================================================

    Is C:

            a == b | c * d

    is interpreted as:

            (a == b) | (c * d)

    and calc it is interpreted as:

            a == ((b | c) * d)


    calc always evaluates terms from left to right
    ==============================================

    Calc has a definite order for evaluation of terms (adds in a
    sum, factors in a product, arguments for a function or a matrix,
    etc.).  This order is always from left to right. but skipping of
    terms may occur for ||, && and ? : .

    Consider, for example:

            A * B + C * D

    In calc above expression is evaluated in the following order:

            A
            B
            A * B
            C
            D
            C * D
            A * B + C * D

    This order of evaluation is significant if evaluation of a
    term changes a variable on which a later term depends.  For example:

            x++ * x++ + x++ * x++

    in calc returns the value:

            x * (x + 1) + (x + 2) * (x + 3)

    and increments x as if by x += 4.  Similarly, for functions f, g,
    the expression:

            f(x++, x++) + g(x++)

    evaluates to:

            f(x, x + 1) + g(x + 2)

    and increments x three times.

    In an other example, this expression:

        1<<8/2

    evaluates to 128, not 16, because <<8 is performed before the /2.


    &A[0] and A are different things in calc
    ========================================

    In calc, value of &A[0] is the address of the first element, whereas
    A is the entire array.


    *X may be used to to return the value of X
    ==========================================

    If the current value of a variable X is an octet, number or string,
    *X may be used to to return the value of X; in effect X is an
    address and *X is the value at X.


    freeing a variable has the effect of assigning the null value to it
    ===================================================================

    The freeglobals(), freestatics(), freeredc() and free() free
    builtins to not "undefine" the variables, but have the effect of
    assigning the null value to them, and so frees the memory used for
    elements of a list, matrix or object.

    Along the same lines:

            undefine *

    undefines all current user-defined functions.  After executing
    all the above freeing functions (and if necessary free(.) to free
    the current "old value"), the only remaining numbers as displayed by

            show numbers

    should be those associated with epsilon(), and if it has been
    called, qpi().


    #! is also a comment
    ====================

    In addition to the C style /* comment lines */, lines that begin with
    #! are treated as comments.

    A single # is an calc operator, not a comment.  However two or more
    ##'s in a row is a comment.  See "help pound" for more information.

        #!/usr/local/src/bin/calc/calc -q -f

        /* a correct comment */
        ## another correct comment
        ### two or more together is also a comment
        /*
         * another correct comment
         */
        print "2+2 =", 2+2;     ## yet another comment

    This next example is WRONG:

        #!/usr/local/src/bin/calc/calc -q -f

        # This is not a calc calc comment because it has only a single #
        # You must to start comments with ## or /*
        print "This example has invalid comments"

    See "help cscript" and "help usage" for more information.


    The { must be on the same line as an if, for, while or do
    =========================================================

    When statement is of the form { ... }, the leading { MUST BE ON
    THE SAME LINE as the if, for, while or do keyword.

    This works as expected:

        if (expr) {
            ...
        }

    However this WILL NOT WORK AS EXPECTED:

        if (expr)
        {
            ...
        }

    because calc will parse the if being terminated by
    an empty statement followed by { ... }.  As in:

        if (expr) ;
        {
            ...
        }

    In the same way, use these forms:

        for (optionalexpr ; optionalexpr ; optionalexpr) {
                ...
        }

        while (expr) {
                ...
        }

        do {
                ...
        while (expr);

    where the initial { is on the SAME LINE as the if, while,
    for or do keyword.

    NOTE: See "help statement", "help todo", and "help bugs".


    Shell evaluation of command line arguments
    ==========================================

    In most interactive shells:

        calc 2 * 3

    will frequently produce a "Missing operator" error because the '*' is
    evaluated as a "shell glob".  To avoid this you must quote or escape
    argument with characters that your interactive shell interprets.

    For example, bash / ksh / sh shell users should use:

        calc '2 * 3'

    or:

        calc 2 \* 3

    or some other form of shell meta-character escaping.


    Calc reads standard input after processing command line args
    ============================================================

    The shell command:

        seq 5 | while read i; do calc "($i+3)^2"; done

        FYI: The command "seq 5" will write 1 through 5 on separate
             lines on standard output, while read i sets $i to
             the value of each line that is read from stdin.

    will produce:

        16
        2
        3
        4
        5

    The reason why the last 4 lines of output are 2 through 5 is
    that after calc evaluates the first line and prints (1+3)^2
    (i.e., 16), calc continues to read stdin and slurps up all
    of the remaining data on the pipe.

    To avoid this problem, use:

        seq 5 | while read i; do calc "($i+3)^2" </dev/null; done

    which produces the expected results:

        16
        25
        36
        49
        64


    display() will limit the number of digits printed after decimal point
    =====================================================================

    While calc is able to print many digits after the decimal point,
    the value of display() may limit the number of digits printed.

    For example, while the following will calculate e to 50 digits:

        ; e = exp(1,1e-50);

     the value of display() (defaults to 20) will limit the number of
     digits printed after the decimal point:

        ; e
                ~2.71828182845904523536

     To print many digits after the decimal point, one needs to change
     the value of display():

        ; display(100),;
        ; e
                2.71828182845904523536028747135266249775724709369996

     Printing a leading ~ (unless disabled by config("tilde", 0)) is
     your indication that the computed value has been rounded
     (rounding mode controlled by config("outround", bitflag)):

     For example, if display(49) is used for that value if e,
     the output will be rounded:

        ; display(49);
                50
        ; e
                ~2.7182818284590452353602874713526624977572470937000

    See also:

        ; help display
        ; help config
        ; help epsilon


    %d will format after the decimal point for non-integer numeric values
    =====================================================================

    In calc, %d formats in base 10 according to the current
    config("mode").  Therefore this will print the entire
    "1.2345" value:

        ; printf("%d\n", 1.2345);
        1.2345


    assuming printing of 4 or more digits is allowed by the current
    value of display().

    See also:

        ; help printf
        ; help display
        ; help mode


    %x will format as fractions for non-integer numeric values
    ==========================================================

    In calc, %x formats in base 16.  A non-integer numeric values such
    as 1/3 is represented as a fraction.  When fractions are printed
    in %x format, both the numerator and denominator are printed
    as is mode("fraction"):

        ; printf("%x\n", 1.2345);
        0x9a5/0x7d0

    See also:

        ; help printf
        ; help display
        ; help mode


    fprintf(fd, "%d\n", huge_value) may need fflush(fd) to finish
    =============================================================

    When printing a small value such as:

        ; fd = fopen("/tmp/test.txt", "w+");
        ; i = 20;
        ; fprintf(fd, "%d\n", i);

    The resulting string will almost always be printed in full.

    Because calc is capable of of printing very large values, some
    people may be surprised when this does not print the entire
    value of M(23209):

        fprintf(fd, "%d\n", 2^23209-1);
        /* the entire value may not be printed yet */

    Because I/O is usually buffered to files, the above fprintf()
    may print only the initial 4096 characters.  One needs to also
    flush (or close the stream) to be sure that the entire
    value as been printed to the file:

        ; fflush(fd);

    A similar problem an arise when printing many digits after
    the decimal point:

        ; display(10000),;
        ; fprintf(fd, "%d\n", pi(1e-10000));
        ; fflush(fd);

    The buffer will also be flushed during a call to fclose():

        ; fclose(fd);

    See also:

        ; help fprintf
        ; help fflush
        ; help fopen
        ; help fclose


    trig functions use only radians
    ===============================

    Some might be surprised to discover that all of the trigonometric in calc:

        sin, cos, tan, cot, sec, csc
        asin, acos, atan, acot, asec, acsc
        versin, coversin, vercos, covercos
        aversin, acoversin, avercos, acovercos
        haversin, hacoversin, havercos, hacovercos
        ahaversin, hacoversin, havercos, ahacovercos
        exsec, aexsec, excsc, aexcsc
        crd, acrd
        cas, cis

    work in only radians.

    Calc as builtin functions to convert between degrees, radians and gradians:

        d2r(deg)        - given degrees returns radians
        g2r(grad)       - given gradians returns radians

        r2d(rad)        - given radians returns degrees
        g2d(grad)       - given gradians returns degrees

        r2g(rad)        - given radians returns gradians
        d2g(deg)        - given degrees returns gradians

    For example, if you want to take the sin of 30 degrees, convert
    the 30 degrees into radians and pass the result to sin():

        ; print sin(d2r(30))
        0.5


    * operator has has a higher precedence than <<
    ==============================================

    The * operator has has a higher precedence than <<, which differs from the C language.
    So 3 << 2*5 evaluates to 3072 in C, whereas 3 << 2*5 evaluates to 60 in calc.


    prompt builtin returns null in calc shell scripts unless -p is used
    ===================================================================

    Be careful when using prompt(str) while calc is being used as a
    shell script.  Unless calc is run with the -p command line option,
    the prompt builtin will fail and return null.  This is because when
    calc is running as a shell script, calc will close stdin run in in
    a non-interactive mode.

    The following shell script will always print "got null" because
    stdin will be closed by calc during startup:

        #!/usr/bin/calc -q -f

        n = prompt("Test> ");
        if (isnull(n)) {
          print("got null");
        } else {
          print("got " + n);
        }

     However the following shell script (note the -p before the -f in
     the 1st line) will be interactive, prompt with "Test> " and print
     the "got" result as expected:

        #!/usr/bin/calc -q -p -f

        n = prompt("Test> ");
        if (isnull(n)) {
          print("got null");
        } else {
          print("got " + n);
        }

    Note in the example above, the -p flag must be given before the
    final -f command line flag.

    A similar problem will occur if the calc shell script attempts
    to read from standard input (stdin), unless the -p flag is used.

    See "SHELL SCRIPT MODE" in the calc man page for more information
    about -p and about the "shell script mode".

## Copyright (C) 1999-2007,2014,2017,2021,2023  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.
##
## Under source code control:   1997/03/21 13:15:18
## 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/

*************
* variable
*************

Variable declarations

    Variables can be declared as either being global, local, or static.
    Global variables are visible to all functions and on the command
    line, and are permanent.  Local variables are visible only within
    a single function or command sequence.  When the function or command
    sequence returns, the local variables are deleted.  Static variables
    are permanent like global variables, but are only visible within the
    same input file or function where they are defined.

    To declare one or more variables, the 'local', 'global', or 'static'
    keywords are used, followed by the desired list of variable names,
    separated by commas.  The definition is terminated with a semicolon.
    Examples of declarations are:

            local       x, y, z;
            global      fred;
            local       foo, bar;
            static      var1, var2, var3;

    Variables may have initializations applied to them.  This is done
    by following the variable name by an equals sign and an expression.
    Global and local variables are initialized each time that control
    reaches them (e.g., at the entry to a function which contains them).
    Static variables are initialized once only, at the time that control
    first reaches them (but in future releases the time of initialization
    may change).  Unlike in C, expressions for static variables may
    contain function calls and refer to variables.  Examples of such
    initializations are:

            local       a1 = 7, a2 = 3;
            static      b = a1 + sin(a2);

    Within function declarations, all variables must be defined.
    But on the top level command line, assignments automatically define
    global variables as needed.  For example, on the top level command
    line, the following defines the global variable x if it had not
    already been defined:

            x = 7

    The static keyword may be used at the top level command level to
    define a variable which is only accessible interactively, or within
    functions defined interactively.

    Variables have no fixed type, thus there is no need or way to
    specify the types of variables as they are defined.  Instead, the
    types of variables change as they are assigned to or are specified
    in special statements such as 'mat' and 'obj'.  When a variable is
    first defined using 'local', 'global', or 'static', it has the
    value of zero.

    If a procedure defines a local or static variable name which matches
    a global variable name, or has a parameter name which matches a
    global variable name, then the local variable or parameter takes
    precedence within that procedure, and the global variable is not
    directly accessible.

    The MAT and OBJ keywords may be used within a declaration statement
    in order to initially define variables as that type.  Initialization
    of these variables are also allowed.  Examples of such declarations
    are:

            static mat table[3] = {5, 6, 7};
            local obj point p1, p2;

    When working with user-defined functions, the syntax for passing an
    lvalue by reference rather than by value is to precede an expression
    for the lvalue by a backquote. For example, if the function invert is
    defined by:

            define invert(x) {x = inverse(x)}

    then invert(`A) achieves the effect of A = inverse(A).  In other
    words, passing and argument of `variable (with a back-quote)
    will cause and changes to the function argument to be applied to
    the calling variable.  Calling invert(A) (without the ` backquote)
    assigns inverse(A) to the temporary function parameter x and leaves
    A unchanged.

    In an argument, a backquote before other than an lvalue is ignored.
    Consider, for example:

            ; define logplus(x,y,z) {return log(++x + ++y + ++z);}

            ; eh = 55;
            ; mi = 25;
            ; answer = logplus(eh, `mi, `17);

            ; print eh, mi, answer;
            55 26 2

    The value of eh is was not changed because eh was used as
    an argument without a back-quote (`).  However, mi was incremented
    because it was passed as `mi (with a back-quote).  Passing 17
    (not an lvalue) as `17 has not effect on the value 17.

    The back-quote should only be used before arguments to a function.
    In all other contexts, a backquote causes a compile error.

    Another method is to pass the address of the lvalue explicitly and
    use the indirection operator * (star) to refer to the lvalue in the
    function body.  Consider the following function:

            ; define ten(a) { *a = 10; }

            ; n = 17;
            ; ten(n);
            ; print n;
            17

            ; ten(`n);
            ; print n;
            17

            ; ten(&n);
            ; print n;
            10

    Passing an argument with a & (ampersand) allows the tenmore()
    function to modify the calling variable:

            ; wa = tenmore(&vx);
            ; print vx, wa;
            65 65

    Great care should be taken when using a pointer to a local variable
    or element of a matrix, list or object, since the lvalue pointed to
    is deleted when evaluation of the function is completed or the lvalue
    whose value is the matrix, list or object is assigned another value.

    As both of the above methods (using & arguments (ampersand) *value
    (star) function values or by using ` arguments (back quote) alone)
    copy the address rather than the value of the argument to the function
    parameter, they allow for faster calls of functions when the memory
    required for the value is huge (such as for a large matrix).

    As the built-in functions and object functions always accept their
    arguments as addresses, there is no gain in using the backquote when
    calling these functions.

## 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.
##
## Under source code control:   1991/07/21 04:37:25
## 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/

*************
* bindings
*************

# bindings - default key bindings for calc line editing functions
#
# Copyright (C) 1999  David I. Bell
#
# 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.
#
# Under source code control:    1993/05/02 20:09:19
# File existed as early as:     1993
#
# Share and enjoy!  :-) http://www.isthe.com/chongo/tech/comp/calc/

# NOTE: This facility is ignored if calc was compiled with GNU-readline.
#       In that case, the standard readline mechanisms (see readline(3))
#       are used in place of those found below.


map     base-map
default insert-char
^@      set-mark
^A      start-of-line
^B      backward-char
^D      delete-char
^E      end-of-line
^F      forward-char
^H      backward-kill-char
^J      new-line
^K      kill-line
^L      refresh-line
^M      new-line
^N      forward-history
^O      save-line
^P      backward-history
^R      reverse-search
^T      swap-chars
^U      flush-input
^V      quote-char
^W      kill-region
^Y      yank
^?      backward-kill-char
^[      ignore-char     esc-map

map     esc-map
default ignore-char     base-map
G       start-of-line
H       backward-history
P       forward-history
K       backward-char
M       forward-char
O       end-of-line
S       delete-char
g       goto-line
s       backward-word
t       forward-word
d       forward-kill-word
u       uppercase-word
l       lowercase-word
h       list-history
^[      flush-input
[       arrow-key

*************
* custom_cal
*************

Custom calc resource files
--------------------------

The following custom calc resource files are provided because they serve
as examples of how use the custom interface.  The custom interface
allows for machine dependent and/or non-portable code to be added as
built-ins to the calc program.  A few example custom functions and
resource files are shipped with calc to provide you with examples.

By default, the custom builtin returns an error.  Calc have been
built with:

        ALLOW_CUSTOM= -DCUSTOM

in the top level Makefile (this is the shipped default) and calc
must be invoked with a -C argument:

        calc -C

when it is run.

To disable custom even if -C is given, calc must be built with:

        ALLOW_CUSTOM="-UCUSTOM"

See the ../cal/README or "help resource" for information about
calc resource standards and guidelines.

=-=

argv.cal

    argv(var, ...)

    print information about various args

halflen.cal

    halflen(num)

    Calculate the length of a numeric value in HALF's.

pzasusb8.cal

    Run custom("pzasusb8") on a standard set of data, print Endian
    related information and print value size information.

## Copyright (C) 1999,2021,2023  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.
##
## Under source code control:   1997/03/08 20:51:32
## 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/

*************
* libcalc
*************

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 /opt/local/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/opt/local/lib -lcalc

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

        -I${INCDIR} -L/opt/local/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/opt/local/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/opt/local/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/opt/local/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 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
and never try to free the array yourself using free().  The reason for this
is that sometimes the pointer points to a 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 str2z 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_;
        str2z("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)
        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.

To determine if z is an integer power of 2, use zispowerof2:

        ZVALUE z;               /* value to check if it is a power of */
        FULL log2;              /* set to log base 2 of z when is_power_of_2 is true */
        bool is_power_of_2;

        is_power_of_2 = zispowerof2(z, &log2)

Returns true if z an integer power of 2: set log2 to log base 2 of z.
Returns false if z is NOT integer power of 2 and leave log2 untouched.
The log2 arg must be a non-NULL pointer to a ZVALUE.

---------------
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 str2q 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 str2q converts a string representing
a number into the corresponding NUMBER.  The str2q function accepts input in
integral, fractional, real, or exponential formats.  Examples of allocating
numbers are:

        NUMBER *q1, *q2, *q3, *q4;

        q1 = itoq(66L);
        q2 = iitoq(2L, 3L);
        q3 = str2q("456.78");
        q4 = utoq((FULL) 1234567890L);

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, *q4;

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

        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 = str2q("0.5");
        epsilon = str2q("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)
        qisreciprocal(q)        (number is 1 / an integer and q != 0)

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_);

To determine if q is an integer power of 2, use qispowerof2:

        NUMBER *q;              /* value to check if it is a power of */
        NUMBER *qlog2;          /* set to log base 2 of q when is_power_of_2 is true */
        bool is_power_of_2;

        q = utoq((FULL) 1234567890L);
        qlog2 = qalloc();
        is_power_of_2 = qispowerof2(q, &qlog2);

Returns true if q an integer power of 2: set *qlog2 to log base 2 of q.
Returns false if q is NOT integer power of 2 and leave *qlog2 untouched.
Use qalloc() to setup the qlog2 arg before calling.

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

Sometimes to results of a COMPLEX based calculation is a real number.
That is, the imaginary part of the COMPLEX is 0.  You may convert the
COMPLEX into a new allocated NUMBER that is real part of the COMPLEX value.
For example:

        COMPLEX *c;
        NUMBER *q;
        bool ok_to_free;        /* true ==> free COMPLEX value, false ==> do not */

        if (cisreal(c)) {
                q = c_to_q(c, ok_to_free);
        }

The 2nd argument to c_to_q() determines if the complex argument should be freed
or not.  Pass a false value as the 2nd arg if you wish to continue to use the
COMPLEX value.

To convert a NUMBER into a COMPLEX value, use:

        COMPLEX *c;
        NUMBER *q;

        c = q_to_c(q);

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 done 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,2021,2023  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.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## 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/

*************
* new_custom
*************

Guidelines for adding custom functions
--------------------------------------

Step 0: Determine if is should it be done?

    The main focus for calc is to provide a portable platform for
    multi-precision calculations in a C-like environment.  You should
    consider implementing algorithms in the calc language as a first
    choice.  Sometimes an algorithm requires use of special hardware, a
    non-portable OS or pre-compiled C library.  In these cases a custom
    interface may be needed.

    The custom function interface is intended to make is easy for
    programmers to add functionality that would be otherwise
    un-suitable for general distribution.  Functions that are
    non-portable (machine, hardware or OS dependent) or highly
    specialized are possible candidates for custom functions.

    So before you go to step 1, ask yourself:

        + Can I implement this as a calc resource file or calc shell script?

            If Yes, write the shell script or resource file and be done with it.
            If No, continue to the next question ...

        + Does it require the use of non-portable features,
          OS specific support or special hardware?

            If No, write it as a regular builtin function.
            If Yes, continue to step 1 ...


Step 1: Do some background work

    First ... read this file ALL THE WAY THROUGH before implementing
    anything in Steps 2 and beyond!

    If you are not familiar with calc internals, we recommend that
    you look at some examples of custom functions.  Look at the
    the following source files:

        custom.c
        custom.h
        custom/custtbl.c
        custom/c_*.[ch]
        custom/*.cal
        help/custom             (or run:  calc help custom)

    You would be well advised to look at a more recent calc source
    such as one available in from the calc version archive.
    See the following for more details:

        help/archive            (or run:  calc help archive)


Step 2: Name your custom function

    We suggest that you pick a name that does not conflict with
    one of the builtin names.  It makes it easier to get help
    via the help interface and avoid confusion down the road.

    You should avoid picking a name that matches a file or
    directory name under ${HELPDIR} as well.  Not all help
    files are associated with builtin function names.

    For purposes of this file, we will use the name 'curds'
    as our example custom function name.


Step 3: Document your custom function

    No this step is NOT out of order.  We recommend that you write the
    help file associated with your new custom function EARLY.  By
    experience we have found that the small amount of effort made to
    write "how the custom function will be used" into a help file pays
    off in a big way when it comes to coding.  Often the effort of
    writing a help file will clarify fuzzy aspects of your design.
    Besides, unless you write the help file first, it will likely never
    be written later on.  :-(

    OK ... we will stop preaching now ...

    [[ From now on we will give filenames relative to the custom directory ]]

    Take a look at one of the example custom help files:

        custom/devnull
        custom/argv
        custom/help
        custom/sysinfo

    You can save time by using one of the custom help files
    as a template.  Copy one of these files to your own help file:

        cd custom
        cp sysinfo curds

    and edit it accordingly.


Step 4: Write your test code

    No this step is NOT out of order either.  We recommend that you
    write a simple calc script that will call your custom function and
    check the results.

    This script will be useful while you are debugging your code.  In
    addition, if you wish to submit your code for distribution, this
    test code will be an import part of your submission.  Your test
    code will also service as additional for your custom function.

    Oops ... we said we would stop preaching, sorry about that ...

    You can use one of the following as a template:

        custom/argv.cal
        custom/halflen.cal

    Copy one of these to your own file:

        cd custom
        cp halflen.cal curds.cal

    and exit it accordingly.  In particular you will want to:

        remove our header disclaimer (or put your own on)

        change the name from halflen() to curds()

        change the comment from 'halflen - determine the length ...' to
        'curds - brief description about ...'

        change other code as needed.


Step 5: Write your custom function

    By convention, the files we ship that contain custom function
    interface code in filenames of the form:

        c_*.c

    We suggest that you use filenames of the form:

        u_*.c

    to avoid filename conflicts.

    We recommend that you use one of the c_*.c files as a template.
    Copy an appropriate file to your file:

        cd custom
        cp c_argv.c u_curds.c

    Before you edit it, you should note that there are several important
    features of this file.

        a) All of the code in the file is found between #if ... #endif:

                /*
                 * only comments and blank lines at the top
                 */

                #if defined(CUSTOM)

                ... all code, #includes, #defines etc.

                #endif /* CUSTOM */

           This allows this code to 'go away' when the upper Makefile
           disables the custom code when CUSTOM is not defined.

        b) The function type must be:

                /*ARGSUSED*/
                VALUE
                u_curds(char *name, int count, VALUE **vals)

           The 3 args are passed in by the custom interface
           and have the following meaning:

                name    The name of the custom function that
                        was called.  In particular, this is the first
                        string arg that was given to the custom()
                        builtin.  This is the equivalent of argv[0] for
                        main() in C programming.

                        The same code can be used for multiple custom
                        functions by processing off of this value.

                count   This is the number of additional args that
                        was given to the custom() builtin.  Note
                        that count does NOT include the name arg.
                        This is similar to argc except that count
                        is one less than the main() argc interface.

                        For example, a call of:

                            custom("curds", a, b, c)

                        would cause count to be passed as 3.

                vals    This is a pointer to an array of VALUEs.
                        This is the equivalent of argv+1 for
                        main() in C programming.  The difference
                        here is that vals[0] refers to the 1st
                        parameter AFTER the same.

                        For example, a call of:

                            custom("curds", a, b, c)

                        would cause vals to point to the following array:

                            vals[0]  points to  a
                            vals[1]  points to  b
                            vals[2]  points to  c

           NOTE: If you do not use any of the 3 function parameters,
           then you should declare that function parameter to be UNUSED.
           For example, if the count and vals parameters were not used
           in your custom function, then your declaration should be:

                /*ARGSUSED*/
                VALUE
                u_curds(char *name, int UNUSED count, VALUE UNUSED **vals)

        c) The return value is the function must be a VALUE.

           The typical way to form a VALUE to return is by declaring
           the following local variable:

                VALUE result;   /* what we will return */

        d) You will need to include:

                #if defined(CUSTOM)

                /* any #include <foobar.h> here */

                #include "../have_const.h"
                #include "../value.h"
                #include "custom.h"

                #include "../have_unused.h"

            Typically these will be included just below any system
            includes and just below the #if defined(CUSTOM) line.

    To better understand the VALUE type, read:

        ../value.h

    The VALUE is a union of major value types found inside calc.
    The v_type VALUE element determines which union element is
    being used.   Assume that we have:

        VALUE *vp;

    Then the value is determined according to v_type:

        vp->v_type      the value is    which is a      type defined in
        ----------      ------------    ----------      ---------------
        V_NULL          (none)          n/a             n/a
        V_INT           vp->v_int       long            n/a
        V_NUM           vp->v_num       NUMBER *        ../qmath.h
        V_COM           vp->v_com       COMPLEX *       ../cmath.h
        V_ADDR          vp->v_addr      VALUE *         ../value.h
        V_STR           vp->v_str       char *          n/a
        V_MAT           vp->v_mat       MATRIX *        ../value.h
        V_LIST          vp->v_list      LIST *          ../value.h
        V_ASSOC         vp->v_assoc     ASSOC *         ../value.h
        V_OBJ           vp->v_obj       OBJECT *        ../value.h
        V_FILE          vp->v_file      FILEID          ../value.h
        V_RAND          vp->v_rand      RAND *          ../zrand.h
        V_RANDOM        vp->v_random    RANDOM *        ../zrandom.h
        V_CONFIG        vp->v_config    CONFIG *        ../config.h
        V_HASH          vp->v_hash      HASH *          ../hash.h
        V_BLOCK         vp->v_block     BLOCK *         ../block.h

    The V_OCTET is under review and should not be used at this time.

    There are a number of macros that may be used to determine
    information about the numerical values (ZVALUE, NUMBER and COMPLEX).
    you might also want to read the following to understand
    some of the numerical types of ZVALUE, NUMBER and COMPLEX:

        ../zmath.h
        ../qmath.h
        ../cmath.h

    While we cannot go into full detail here are some cookbook
    code for manipulating VALUEs.  For these examples assume
    that we will manipulate the return value:

        VALUE result;   /* what we will return */

    To return NULL:

        result.v_type = V_NULL;
        return result;

    To return a long you need to convert it to a NUMBER:

        long variable;

        result.v_type = V_NUM;
        result.v_num = itoq(variable);          /* see ../qmath.c */
        return result;

    To return a FULL you need to convert it to a NUMBER:

        FULL variable;

        result.v_type = V_NUM;
        result.v_num = utoq(variable);          /* see ../qmath.c */
        return result;

    To convert a ZVALUE to a NUMBER*:

        ZVALUE variable;

        result.v_type = V_NUM;
        result.v_num = qalloc();                /* see ../qmath.c */
        result.v_num->num = variable;
        return result;

    To convert a small NUMBER* into a long:

        NUMBER *num;
        long variable;

        variable = qtoi(num);

    To obtain a ZVALUE from a NUMBER*, extract the numerator:

        NUMBER *num;
        ZVALUE z_variable;

        if (qisint(num)) {
                z_variable = num->num;
        }

    To be sure that the value will fit, use the ZVALUE test macros:

        ZVALUE z_num;
        long variable;
        unsigned long u_variable;
        FULL f_variable;
        short very_tiny_variable;

        if (zgtmaxlong(z_num)) {                        /* see ../zmath.h */
                variable = ztolong(z_num);
        }
        if (zgtmaxulong(z_num)) {
                u_variable = ztoulong(z_num);
        }
        if (zgtmaxufull(z_num)) {
                f_variable = ztofull(z_num);
        }
        if (zistiny(z_num)) {
                very_tiny_variable = z1tol(z_num);
        }

    You can (and should) add debugging statements to your custom code
    by examining bit 8 of the calc_debug config flag:

        if (conf->calc_debug & CALCDBG_CUSTOM) {
            fprintf(stderr, "%ssome custom debug note: msg\n",
                (conf->tab_ok ? "\t" : ""),
                ((msg == NULL) ? "((NULL))" : msg));
        }

    One is able to set bit 8 by way of the calc command line:

        calc -D 128

    See the calc man page for details.  One may also set that bit
    while running calc by way of the config() builtin function:

        config("calc_debug", 128);

    See the help/config file for details on calc_debug.

Step 6: Register the function in the custom interface table

    To allow the custom() builtin to transfer control to your function,
    you need to add an entry into the CONST struct custom cust table
    found in custom/custtbl.c:

        /*
         * custom interface table
         *
         * The order of the elements in struct custom are:
         *
         *      { "xyz", "brief description of the xyz custom function",
         *         minimum_args, maximum_args, c_xyz },
         *
         * where:
         *
         *      minimum_args    an int >= 0
         *      maximum_args    an int >= minimum_args and <= MAX_CUSTOM_ARGS
         *
         * Use MAX_CUSTOM_ARGS for maximum_args is the maximum number of args
         * is potentially 'unlimited'.
         *
         * If the brief description cannot fit on the same line as the name
         * without wrapping on a 80 col window, the description is probably
         * too long and will not look nice in the show custom output.
         */
        CONST struct custom cust[] = {

        #if defined(CUSTOM)


                /*
                 * add your own custom functions here
                 *
                 * We suggest that you sort the entries below by name
                 * so that show custom will produce a nice sorted list.
                 */

                { "argv", "information about its args, returns arg count",
                 0, MAX_CUSTOM_ARGS, c_argv },

                { "devnull", "does nothing",
                 0, MAX_CUSTOM_ARGS, c_devnull },

                { "help", "help for custom functions",
                 1, 1, c_help },

                { "sysinfo", "return a calc #define value",
                 0, 1, c_sysinfo },


        #endif /* CUSTOM */

                /*
                 * This must be at the end of this table!!!
                 */
                {NULL, NULL,
                 0, 0, NULL}
        };

    The definition of struct custom may be found in custom.h.

    It is important that your entry be placed inside the:

        #if defined(CUSTOM) ... #endif /* CUSTOM */

    lines so that when the custom interface is disabled by the upper
    level Makefile, one does not have unsatisfied symbols.

    The brief description should be brief so that 'show custom' looks well
    formatted.  If the brief description cannot fit on the same line as
    the name without wrapping on a 80 col window, the description is
    probably too long and will not look nice in the show custom output.

    The minargs places a lower bound on the number of args that
    must be supplied to the interface.  This does NOT count
    the name argument given to custom().  So if minargs is 2:

        custom("curds")         /* call blocked at high level interface */
        custom("curds", a)      /* call blocked at high level interface */
        custom("curds", a, b)   /* call passed down to "curds" interface */

    The maxargs sets a limit on the number of args that may be passed.
    If minargs == maxargs, then the call requires a fixed number of
    argument.  There is a upper limit on the number of args.  If
    one wants an effectively unlimited upper bound, use MAX_CUSTOM_ARGS.

    Note that one must have:

                0 <= minargs <= maxargs <= MAX_CUSTOM_ARGS

    To allow the curds function to take at least 2 args and up
    to 5 args, one would add the following entry to cust[]:

                { "curds", "brief description about curds interface",
                 2, 5, u_curds },

    It is recommended that the cust[] remain in alphabetical order,
    so one would place it before the "devnull" and after "argv".

    Last, you must forward declare the u_curds near the top of the file:

        #if defined(CUSTOM)


        /*
         * add your forward custom function declarations here
         *
         * Declare custom functions as follows:
         *
         *      E_FUNC VALUE c_xyz(char*, int, VALUE**);
         *
         * We suggest that you sort the entries below by name.
         */
        E_FUNC VALUE c_argv(char*, int, VALUE**);
        E_FUNC VALUE c_devnull(char*, int, VALUE**);
        E_FUNC VALUE c_help(char*, int, VALUE**);
        E_FUNC VALUE c_sysinfo(char*, int, VALUE**);

    For u_curds we would add the line:

        E_FUNC VALUE u_curds(char*, int, VALUE**);


Step 7: Add the required information to the custom/Makefile.head

    The calc test script, curds.cal, should be added to the
    CUSTOM_CALC_FILES Makefile variable found in custom/Makefile.head:

        CUSTOM_CALC_FILES= argv.cal halflen.cal curds.cal

    The help file, curds, should be added to the CUSTOM_HELP
    custom/Makefile.head variable:

        CUSTOM_HELP= argv devnull help sysinfo curds

    If you needed to create any .h files to support u_curds.c, these
    files should be added to the CUSTOM_H_SRC custom/Makefile.head variable:

        CUSTOM_H_SRC= u_curds.h otherfile.h

    Your u_curds.c file MUST be added to the CUSTOM_SRC custom/Makefile.head
    variable:

        CUSTOM_SRC= c_argv.c c_devnull.c c_help.c c_sysinfo.c u_curds.c

    and so must the associated .o file:

        CUSTOM_OBJ= c_argv.o c_devnull.o c_help.o c_sysinfo.o u_curds.o


Step 8: Compile and link in your code

    If your calc was not previously setup to compile custom code,
    you should set it up now.  The upper level Makefile (and
    the custom Makefile) should have the following Makefile
    variable defined:

        ALLOW_CUSTOM= -DCUSTOM

    It is recommended that you build your code from the top level
    Makefile.  It saves having to sync the other Makefile values.
    To try and build the new libcustcalc.a that contains u_curds.c:

        (cd ..; make custom/libcustcalc.a)

    Fix any compile and syntax errors as needed.  :-)

    Once libcustcalc.a successfully builds, compile calc:

        cd ..
        make calc

    And check to be sure that the regression test suite still
    works without errors:

        make check


Step 9: Add the Make dependency tools

    You should probably add the dependency lines to the bottom of
    the Makefile.  Given the required include files, you will at least
    have the following entries placed at the bottom of the Makefile:

        u_curds.o: ../alloc.h
        u_curds.o: ../block.h
        u_curds.o: ../byteswap.h
        u_curds.o: ../cmath.h
        u_curds.o: ../config.h
        u_curds.o: ../endian_calc.h
        u_curds.o: ../errsym.h
        u_curds.o: ../hash.h
        u_curds.o: ../have_const.h
        u_curds.o: ../have_malloc.h
        u_curds.o: ../have_newstr.h
        u_curds.o: ../have_stdlib.h
        u_curds.o: ../have_string.h
        u_curds.o: ../longbits.h
        u_curds.o: ../nametype.h
        u_curds.o: ../qmath.h
        u_curds.o: ../shs.h
        u_curds.o: ../value.h
        u_curds.o: ../zmath.h
        u_curds.o: u_curds.c
        u_curds.o: ../custom.h

    If you have the makedepend tool from the X11 development environment
    (by Todd Brunhoff, Tektronix, Inc. and MIT Project Athena), you can
    use the following to update your dependencies:

        # cd to the top level calc directory if you are not there already

        rm -f Makefile.bak custom/Makefile.bak
        make depend

        diff -c Makefile.bak Makefile                   # look at the changes
        diff -c custom/Makefile.bak custom/Makefile     # look at the changes

        rm -f Makefile.bak custom/Makefile.bak          # cleanup

Step 10: Test

    Now that you have built calc with your new custom function, test it:

        ./calc -C               # run the new calc with the -C arg

    And then try out our test suite:

        C-style arbitrary precision calculator (version 2.10.3t5.1)
        [Type "exit" to exit, or "help" for help.]

        > read custom/curds.cal
        curds(a, b, [c, d, e]) defined

        > custom("curds", 2, 3, 4)


Step 11: Install

    Once you are satisfied that everything works, install the new code:

        # cd to the top level calc directory if you are not there already

        make install

    Although calc does not run setuid, you may need to be root to install
    the directories into which calc installs may be write protected.


Step 12: Contribute

    Your custom function may be of interest to some people and/or
    serve as an example of what one can do with custom functions.

    Read the file:

        help/contrib            (or run:  calc help contrib)

    and consider submitting your custom function for possible
    inclusion in later versions of calc.

## Copyright (C) 1999-2007,2021  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.
##
## Under source code control:   1997/03/10 03:03:21
## 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/

*************
* cscript
*************

calc shell script examples
--------------------------

These calc shell scripts are provided because they serve as examples of
how use the calc language, and/or because the authors thought them to
be useful!

Please note that calc shell scripts must start with the line:

    #!/opt/local/bin/calc -q -f

The above line MUST start in column 1 of the first line.   The first line
must also end in -f.  The -q is optional, but is recommended to disable
the processing of calc startup scripts.

Also please note that single # shell line comments are not supported in calc.
Comments must be /* c-like comment */ or start with a double ## symbol.

This is the correct way to form a calc shell script:

    #!/opt/local/bin/calc -q -f

    /* a correct comment */
    ## another correct comment
    ### two or more together is also a comment
    /*
     * another correct comment
     */
    print "2+2 =", 2+2; ## yet another comment

The first argument after the path to calc executable must be an -S.
The next arguments are optional.  The -q is often recommended because
it will disable the processing of the startup scripts.

For more informaton about calc command lines, see "help usage".

This next example WRONG:

    #!/opt/local/bin/calc -q

    # This is not a calc calc comment because it has only a single #
    # You must to start comments with ## or /*
    # is is also wrong because the first line does not end in -f
    print "This example has invalid comments"

=-=

For more info, see:

    help script
    help cscript

#####

4dsphere

    Determine if 6 points lie on the surface of a 4-dimensional sphere in R^4.

    4dsphere x0 y0 z0 w0   x1 y1 z1 w1   ...   x5 y5 z5 w5

        x0 y0 z0 w0     point 0 in R^4
        x1 y1 z1 w1     point 1 in R^4
        ...             ...
        x5 y5 z5 w5     point 5 in R^4


fproduct filename term ...

    Write the big Endian product of terms to a file.  Use - for stdout.


mersenne exp

    Print the value of 2^exp-1.


piforever

    Print the value of pi forever, or as long as you CPU / memory allows.


plus arg ...

    Print the sum of 1 or more arguments.


powerterm [base_limit] value

    Print the value as a sum (or difference) of powers of integers up
    to and including powers <= base_limit.  By default, base_limit is 10000.


simple

    A trivial example of a calc shell script.

## Copyright (C) 1999,2014,2021  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.
##
## Under source code control:   1999/12/17 10:23:40
## File existed as early as:    1999
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/

*************
* archive
*************

Where to get the latest versions of calc

    Official calc source is maintained on GitHub:

        https://github.com/lcn2/calc

    Calc releases may be found as GitHub tagged releases:

        https://github.com/lcn2/calc/releases?page=2

     At the bottom of a given release is a "> Assets" that may
     be opened to reveal down-loadable files such as source
     tarballs, source zip files and RPMs.

    Landon Noll also maintains a calc home page at:

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

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

chongo <was here> /\../\

## Copyright (C) 1999,2021  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.
##
## Under source code control:   1996/06/13 02:51:48
## 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/

*************
* bugs
*************

If you notice something wrong, strange or broken, try rereading:

    README.FIRST
    HOWTO.INSTALL
    BUGS (this file)

If that does not help, cd to the calc source directory and try:

    make check

Look at the end of the output, it should say something like:

    9998: passed all tests  /\../\
    9999: Ending regression tests

If it does not, then something is really broken!

To be sure that your version of calc is up to date.
Look for the latest release on GitHub:

    https://github.com/lcn2/calc/releases

Just below latest GitHub release sectiop is something called:

    > Assets

Click in the triangle to open up the Assets then click on
the approptiate package to download.

If you made and modifications to calc beyond the simple Makefile
configuration, try backing those changes out and see if things get
better.

If you have tried all of the above and things still are not right,
then it may be time to send in a bug report.

=-=

If you encounter a warning or error in compiling, or if you
find a calc bug and you wish to send is a fix, we recommend
that you submit your change using the GitHub pull request:

    https://github.com/lcn2/calc/pulls

=-=

If you just want to send us a bug report, we recommend
doing so via the GitHub issue process:

    https://github.com/lcn2/calc/issues

If you see an existing issue that matches your problem, look
over the notes and if needed, add your own observation,
even if you just add to an existing issue:

    I have this issue too

If you don't see your issue addressed, then on the above
GitHub web page, click on this button:

    ((New Issue))

Please include the following information in the new issue:

    * A description of the problem

    * Version of calc you are using

        If you cannot compile calc, then look at version.c
        and report the #define that start with:

            #define MAJOR_VER
            #define MINOR_VER
            #define MAJOR_PATCH
            #define MINOR_PATCH

    * If you modified calc from an official patch,
      send us the mods you made

    * Type and version of the operating system

    * Type and version of compiler

    * Send us all compiler warnings or errors you find

    * If calc dumped core, try to send us a core dump stack trace

    * cd to the calc source directory, and send the contents
      of debug.out.txt produced by this command:

        make debug

PLEASE attach the debug.out.txt file to your GitHub issue (bug report)!!

Please be patient as we cannot always respond to pull requests quickly.

=-=

Known bugs in calc:

    The output of the alg_config.cal resource file is bogus.
    We would welcome a replacement for this code.

    Calc may not compile natively under Windows 11, however with
    MSYS2 Software Distribution (a fork of Cygwin) people compile
    calc under Windiws just fine.  See README.WINDOWS.

    We are sure some more bugs exist.  When you find them, please let
    us know!  See the above for details on how to report and were to
    Email your bug reports and hopefully patches to fix them.

=-=

mis-features in calc:

    Some problems are not bugs but rather mis-features / things that could
    work better.  The following is a list of mis-features that should be
    addressed and improved someday.

    * When statement is of the form { ... }, the leading { MUST BE ON
      THE SAME LINE as the if, for, while or do keyword.

      This works as expected:

        if (expr) {
            ...
        }

      However this WILL NOT WORK AS EXPECTED:

        if (expr)
        {
            ...
        }

      This needs to be changed.  See also "help statement", "help unexpected",
      and "help todo".

    * The chi.cal resource file does not work well with odd degrees
      of freedom.  Can someone improve this algorithm?

    * The intfile.cal resource file reads and writes big or little Endian
      integers to/from files the hard way.  It does NOT use blkcpy.  The
      following code:

        i = (ord("\n") << 16) | (ord("i") << 8) | ord("H")
        b = blk()
        copy(i, b)
        fd = fopen("file", "w")
        copy(b, fd);
        fclose(fd)

      will write an extra NUL octet to the file.  Where as:

        read intfile
        i = (ord("\n") << 16) | (ord("i") << 8) | ord("H")
        be2file(i, "file2")

      will not.

    * The numerator is assumed

        The numerator value of 1 appears to be assumed.  In calc:

             / 2

        will produce a value of 0.5 as if the numerator 1 was given.


=-=

## Copyright (C) 1999-2014,2021,2023  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.
##
## Under source code control:   1994/03/18 14:06:13
## 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/

*************
* changes
*************

The following are the changes from calc version 2.15.0.7 to 2.15.1.0:

    Converted all ASCII tabs to ASCII spaces using a 8 character
    tab stop, for all files, except for all Makefiles (plus rpm.mk).
    The command `git diff -w` reports no changes.  There is no
    functionality change in calc: only ASCII tabs to ASCII spaces.

    Fixed trailblank.  It was pruning . in its find search.
    Added check for ASCII tabs is non-Makefiles.

    This version will form the basis for the calc v2 to calc v3 fork.


The following are the changes from calc version 2.15.0.6 to 2.15.0.7:

    Thanks to GitHub user @bambooleafz a critical bug (GitHub issue
    #148 - https://github.com/lcn2/calc/issues/148) they identified
    was fixed.


The following are the changes from calc version 2.15.0.5 to 2.15.0.6:

     Thanks to GitHub user @ashamedbit, a long standing memory leak in
     zrandom.c has been fixed.


The following are the changes from calc version 2.15.0.4 to 2.15.0.5:

     make clobber now removes the legacy files: have_fpos.h, help/man,
     and help/usage.  The latter 2 are now managed as help aliases
     in help.c.

     make install now removes the legacy files: ${HELPDIR}/man
     and ${HELPDIR}/usage.

     Fixed a problem where, when calc was linked with and uses GNU
     readline then for any multi-line copy-and-paste, only the first
     line is executed.  Thanks to GitHub user @malfisya for reporting
     this problem, and thanks to GitHub user @gromit1811 for doing
     the research needed to overcome deficiencies in the GNU readline
     documentation, and for supplying the work-a-round to allow
     multi-line copy-and-paste to work as expected!


The following are the changes from calc version 2.15.0.3 to 2.15.0.4:

    Fixed bug that caused calc to fail to compile filepos2z() in file.c
    on little endian machines for the Debian apcalc package.  Thanks to
    Martin Buck (m at rtin-buck dor de) for for fix.

    Removed unused macros from zmath.h:

        SWAP_B32_IN_HASH(dest, src)
        SWAP_B16_IN_HASH(dest, src)
        SWAP_B8_IN_HASH(dest, src)
        SWAP_B32_IN_FLAG(dest, src)
        SWAP_B16_IN_FLAG(dest, src)
        SWAP_B8_IN_FLAG(dest, src)

    When SWAP_HALF_IN_B32(dest, src), SWAP_B32_IN_FULL(dest, src),
    SWAP_B16_IN_HALF(dest, src), SWAP_B32_IN_bool(dest, src),
    or SWAP_B32_IN_LEN(dest, src), SWAP_HALF_IN_FILEPOS(dest, src)
    is an assignment such as:

        (*(dest) = *(src))

    We now case the dest and src pointers to the proper type before
    referencing and performing the assignment.

    Documented unexpected behavior when calc is running in
    "shell script mode" and the prompt builtin function is used
    without the -p flag.  Updated help/prompt, help/unexpected
    and the calc man page accordingly.

    Unless calc is given the -p command line option, calc will reopen
    stdin as /dev/null instead of just closing stdin.  This prevents
    subsequent opens grabbing the 1st file descriptor.

    Disable regress tests 4709, 4710, and 7763 because they print
    multi-byte sequences, which are just fine for calc, the awk
    used to evaluate the regression suite output in some legacy
    systems report a "multibyte conversion failure".

    Added a number of missing Makefile variables to the "make env" rule.

    The man command is used to format the calc.1 man page into calc.usage.

    The "help calc" command now prints the formatted calc man page (calc.usage).
    The "help man" command now prints the formatted calc man page (calc.usage).
    The "help usage" command now prints the formatted calc man page (calc.usage).

    The file, calc.cat1, is formed by gzipping the calc.usage
    formatted man page.  The calc.cat1 is installed as the calc
    cat section 1 man page.

    Updated the Copyright string in version.c to refer to
    the COPYING file and the "help copying" command.

    Added calc.cat1 to .gitignore.  Using "sort -d -u" to sort .gitignore content.

    Avoiding use of modern [[ and ]] in Makefile for those legacy systems
    whose shell do not support them.  Be sure to use ||'s between []'s
    to avoid problems with legacy shell such as the Bourne shell. *sigh*

    Fixed the order of "help full" to match the order of topics listed
    buy the "help help" command.

    Sorted the halias[] help topics table in help.c using sort -d -u.


The following are the changes from calc version 2.15.0.1 to 2.15.0.2:

    Updated BUGS about MSYS2 on Windows compiling of calc.

    Added more git related checks and sanity checks to chk_tree.

    Added ${FSANITIZE} make variable to Makefile.config to hold
    common Address Sanitizer (ASAN) optins to modern Linux and macOS.
    The Address Sanitizer is NOT enabled not compiled in by default.
    Improved comments in Makefile.local for RHEL9.2 (Linux) and for
    macOS 14.0 that, when uncommented and calc is recompiled (i.e.,
    make clobber all) will enable the Address Sanitizer (ASAN) for calc.

    Fixed memory leaks in the logn, aversin, acoversin, avercos,
    acovercos, ahaversin, ahavercos, ahacovercos, aexsec,
    aexcsc, and acrd.

    Fixed a compile error in zmath.h that impacted legacy 32-bit Big
    Endian machines.  Thanks goes to GitHub user @gromit1811 for their
    pull request.

    Fixed the check for <sys/mount.h> when forming have_sys_mount.h.
    Thanks goes to GitHub user @gromit1811 for their pull request.

    Added "STATIC bool blum_initialized = false" to zrandom.c to improve
    how the code detects if the Blum-Blum-Shub pseudo-random number
    generator is seeded or not, and how to free the state correctly.

    NOTE: There is a very minor memory leak in zrandom.c that will be
    fixed in a later release.


The following are the changes from calc version 2.14.3.5 to 2.15.0.1:

    The tarball for calc version 2.15.0.0 was missing version.h.
    The version.h is now listed as part of the calc distribution.

    Added the following new trigonometric functions:

        versin(x [,eps])        versed trigonometric sine
        coversin(x [,eps])      coversed trigonometric sine
        vercos(x [,eps])        versed trigonometric cosine
        covercos(x [,eps])      coversed trigonometric cosine
        aversin(x [,eps])       inverse versed trigonometric sine
        acoversin(x [,eps])     inverse coversed trigonometric sine
        avercos(x [,eps])       inverse versed trigonometric cosine
        acovercos(x [,eps])     inverse coversed trigonometric cosine
        haversin(x [,eps])      half versed trigonometric sine
        hacoversin(x [,eps])    half coversed trigonometric sine
        havercos(x [,eps])      half versed trigonometric cosine
        hacovercos(x [,eps])    half coversed trigonometric cosine
        ahaversin(x [,eps])     inverse half versed trigonometric sine
        ahacoversin(x [,eps])   inverse half coversed trigonometric sine
        ahavercos(x [,eps])     inverse half versed trigonometric cosine
        ahacovercos(x [,eps])   inverse half coversed trigonometric cosine
        exsec(x [,eps])         exterior trigonometric secant
        aexsec(x [,eps])        inverse exterior trigonometric secant
        excsc(x [,eps])         exterior trigonometric cosecant
        aexcsc(x [,eps])        inverse exterior trigonometric cosecant
        crd(x [,eps])           trigonometric chord of a unit circle
        acrd(x [,eps])          inverse trigonometric chord of a unit circle
        cas(x [,eps])           trigonometric cosine plus sine
        cis(x [,eps])           Euler's formula

    As Msys2 is a fork of Cygwin, if the OSNAME is Msys, the Cygwin
    target will be used.  Thanks to GitHub user @iahung2 for the
    pull request.

    Support for win32 and DJGPP has been dropped.  Calc version
    2.14.3.5 was the last to make references to win32 and make
    references to DJGPP.  Future versions of calc may work under
    those systems, we just elected to remove the somewhat out of
    date and awkward `win32.mkdef` and related win32 references.

    If you are a win32 user, please feel free to create a win32
    target in Makefile.target and submit as a pull request.
    If you are a DJGPP user, please feel free to create a DJGPP
    target in Makefile.target and submit as a pull request.
    Until someone can test such systems, we prefer to wait
    until someone is able to test and supply a pull request.

    Added PTR_LEN (length of a pointer) and PTR_BITS (bit length
    of a pointer) to longbits.h.

    Moved calc version definition from version.c to version.h.

    Sorted the order of symbols printed by "make env".

    Test if <stdbool.h> exists and set HAVE_STDBOOL_H accordingly
    in have_stdbool.h.  Added HAVE_STDBOOL_H to allow one to force
    this value.

    Added "bool.h" include file to support use of boolean symbols,
    true and false for pre-c99 C compilers.  The "bool.h" include
    file defines TRUE as true, FALSE as false, and BOOL as bool:
    for backward compatibility.

    Replaced in C source, TRUE with true, FALSE with false, and
    BOOL with bool.

    Fixed have_statfs optional executable file extension ${EXT{ in
    the ${UTIL_PROGS} make variable.

    Test if <stdint.h> exists and set HAVE_STDINT_H accordingly
    in have_stdint.h.  Added HAVE_STDINT_H to allow one to force
    this value.

    Test if <inttypes.h> exists and set HAVE_INTTYPES_H accordingly
    in have_inttypes.h.  Added HAVE_INTTYPES_H to allow one to force
    this value.

    Added c_chk.c to check the compiler and C include for calc
    requirements.  If you are unable to compile this program, or
    if this program when compiles does not exit 0, then your C
    compiler and/or C include fails to meet calc requirements.
    Compilers that are at least c99 MUST be able to compile this
    program such that when run will exit 0.

    The "make hsrc" file will attempt to compile and run c_chk and
    will warn if the C compiler and/or C include fails to meet
    calc requirements.  The "make debug" system will run c_chk -c
    to print information about the C compiler and C include.
    Currently failure to compile cc_chk.c or c_chk exiting non-0
    will just print "WARNING!!" strings to stderr.

    The make chk_c file also forms status.chk_c.h which either
    defines CHK_C when the C compiler and select include files
    appear to meet calc requirements, or undefines CHK_C
    when it does not.

    Added int.h as a central place for calc integer types and
    integer macros.

    Removed `-R release_file` and `-r release_file` command
    line options from `ver_calc`.  Add `-h` option.  Updated
    comments in "README.RELEASE", which serves as the contents
    of the calc command "help release".

    Added log2(x [,eps]) builtin function.  When x is an integer
    power of 2, log2(x) will return an integer, otherwise it will
    return the equivalent of ln(x)/ln(2).

    Removed CALC2_COMPAT in favor of ckecking if MAJOR_VER < 3.

    The sign element in a ZVALUE is now of type SIGN, which is either
    SB32 when MAJOR_VER < 3, or a bool otherwise.

    The len element in a ZVALUE is of type LEN.  LEN type is SB32 when
    MAJOR_VER < 3, or a uintptr_t otherwise.

    Setting an invalid epsilon via the epsilon(value) or confiv("epsilon",
    value) triggers an error.  The epsilon value must be: 0 < epsilon < 1.

    Added new logn(x, n [,eps]) builtin to compute logarithms to base n.

    Verify that eps arguments (error tolerance arguments that override
    the default epsilon value) to builtin functions have proper values.
    Previously the eps argument had little to no value checks for
    many builtin functions.

    Document in help files for builtin functions that take eps arguments,
    the LIMIT range for such eps values.

    Removed old Makefile testing rules for make dbx and make gdb.

    Improved "make run" to execute calccalc using shared libraries
    from the local directory, and with reading of the startup scripts
    disabled.

    Changed "make prep" to perform various tests that are used to
    help verify that calc is ready for a release.  Added the
    update_ver tool, (formerly verupdate) and the trailblank tool
    that existed outside of the calc source base but neverthless
    used in the calc release process.  Both of these tools are used
    by "make prep".

    Added Makefile testing rule "make testfuncsort" to check for
    the sort of the builtin function list.  Changed the order that
    builtin functions are listed by "show builtin" and the help/builtin
    to match the sorting of "LANG=C LC_ALL=C sort -d -u".

    Added c_to_q(COMPLEX *c, bool cfree) to make is easier to convert
    a COMPLEX value that is real (imag part is 0) into a NUMBER and
    optionally free the COMPLEX value.  The func.c code now uses c_to_q().

    Added q_to_c(NUMBER *q) to make it easier to convert a NUMBER
    into an allocated COMPLEX value.

    Added new vercos(x, [,eps]) for versed cosine and covercos(x, [,eps])
    for inverse versed cosine.

    Added new avercos(x, [,eps]) for inverse versed cosine and acovercos(x, [,eps])
    for inverse coversed cosine.

    Improved comments about use of the ${CALC_ENV} Makefile variable.
    Noted in Makefile.cal where and how the ${CALC_ENV} is used.
    Use ${CALC_ENV} Makefile variable were needed.

    Modified regression test cal/regress.cal: in some cases test numbers
    were adjusted.  Add comments indicate which test numbers apply to
    which code.  Indicated where there is room for new tests.
    Expanded the end of test numbers from 9999 to  99999.

    To make the meaning a bit more clear in cal/regress.cal, we have
    renamed the following test calc resource files that are related to
    the calc regression test suite:

        cal/test1700.cal -> cal/test8000.read.cal
        cal/test2300.cal -> cal/test2300.obj_incdec.cal
        cal/test2600.cal -> cal/test2600.numfunc.cal
        cal/test2700.cal -> cal/test2700.isqrt.cal
        cal/test3100.cal -> cal/test3100.matobj.cal
        cal/test3400.cal -> cal/test3400.trig.cal
        cal/test4000.cal -> cal/test4000.ptest.cal
        cal/test4100.cal -> cal/test4100.redc.cal
        cal/test4600.cal -> cal/test4600.fileop.cal
        cal/test5100.cal -> cal/test5100.newdecl.cal
        cal/test5200.cal -> cal/test5200.globstat.cal
        cal/test8400.cal -> cal/test8400.quit.cal
        cal/test8500.cal -> cal/test8500.divmod.cal
        cal/test8600.cal -> cal/test8600.maxargs.cal
        cal/set8700.cal -> cal/test8700.dotest.cal
        cal/test8900.cal -> cal/test8900.special.cal
        cal/test9300.cal -> cal/test9300.frem.cal

    Added to test 94dd, read of a number of new calc resource files
    that are not already read as a result of the calc regression test suite.

    Fixed more documentation and code comments that referred to the
    old additive 55 (a55) shuffle pseudo-random number generator.
    We have been using the subtractive 100 shuffle pseudo-random
    number generator in place of the additive 55 generator for a
    while now.

    Improved help files trigonometric functions.  They were corrected
    to indicate that complex arguments are allowed: an oversight
    from long ago when those trigonometric functions were expanded
    to include complex arguments.  The EXAMPLE sections were expanded
    and made consistent, where applicable, across the trigonometric
    help files.  Documented libcalc functions in the SEE ALSO sections.

    Improved "SEE ALSO" for the hyperbolic function help files.

    Expanded the calc regression test suite test 34dd to test various
    real and complex values for trigonometric functions.

    Added complex multiple approximation function to commath.c so
    that users of libcalc may directly round complex number to
    nearest multiple of a given real number:

        E_FUNC COMPLEX *cmappr(COMPLEX *c, NUMBER *e, long rnd, bool cfree);

    For example:

        COMPLEX *c;             /* complex number to round to nearest epsilon */
        NUMBER *eps;            /* epsilon rounding precision */
        COMPLEX *res;           /* c rounded to nearest epsilon */
        long rnd = 24L;         /* a common rounding mode */
        bool ok_to_free;        /* true ==> free c, false ==> do not free c */

        ...

        res = cmappr(c, eps, ok_to_free);

    The complex trigonometric functions tan, cot, sec, csc were
    implemented in func.c as calls to complex sin and complex cos.
    We added the following direct calls to comfunc.c so that users
    of libcalc may call them directly:

        E_FUNC COMPLEX *c_tan(COMPLEX *c, NUMBER *eps);
        E_FUNC COMPLEX *c_cot(COMPLEX *c, NUMBER *eps);
        E_FUNC COMPLEX *c_sec(COMPLEX *c, NUMBER *eps);
        E_FUNC COMPLEX *c_cot(COMPLEX *c, NUMBER *eps);

    Added help/errorcodes rule to the top level Makefile.

    Added E_USERMAX symbol (== 32767) to indicate the maximum value
    allowed for user error codes.

    Improved help/error.  Added text about error code ranges and
    range symbols.

    Changed calc_errno a global int variable so that is may be directly
    accessed by libcalc users.

    Further improve help files for help/errno, help/error, help/newerror,
    help/stoponerror and help/strerror by adding to documentation
    of the calc error code system as well as libcalc interface
    where applicable.

    Changed #define E_USERDEF to #define E__USERDEF.

    Removed use of E_USERDEF, E__BASE, E__COUNT, and E__HIGHEST
    from custom/c_sysinfo because the c_sysinfo is just a demo
    and this will simplify the custom/Makefile.

    The include file calcerr.h is now the errsym.h include file.
    The calcerr.tbl has been replaced by errtbl.c and errtbl.h.

    The calcerr_c.awk, calcerr_c.sed, calcerr_h.awk, and
    calcerr_h.sed files are now obsolete and have been removed.
    The calcerr.c and calcerr.h now obsolete and are no longer built.

    The calc computation error codes, symbols and messages are now in
    a error_table[] array of struct errtbl.

    An E_STRING is a string corresponds to an error code #define.
    For example, the E_STRING for the calc error E_STRCAT,
    is the string "E_STRING".  An E_STRING must now match
    the regular expression: "^E_[A-Z0-9_]+$".

    The old array error_table[] of error message strings has been
    replaced by a new error_table[] array of struct errtbl.  The struct
    errtbl array holds calc errnum error codes, the related E_STRING
    symbol as a string, and the original related error message.
    To add new computation error codes, add them near the bottom of the
    error_table[] array, just before the NULL entry.

    The ./errcode utility, when run, will verify the consistency of
    the error_table[] array.

    The Makefile uses ./errcode -e to generate the contents of
    help/errorcodes file.  The help errorcodes now prints
    information from the new cstruct errtbl error_table[] array.

    The help/errorcodes.hdr and help/errorcodes.sed files are
    now obsolete and have been removed.

    The Makefile uses ./errcode -d to generate the contents of the
    errsym.h include file.

    Code that used the old array error_table[] of error message strings
    such as:

        #include "calcerr.h"

        char *msg;      /* calc computation error message */

        msg = error_table[errnum - E__BASE];

    where errnum is the calc computation error code
    E__BASE <= errnum <= E__HIGHEST, may now use:

        #include "errtbl.h"
        #include "errsym.h"

        char *msg;      /* calc computation error message */

        msg = error_table[errnum - E__BASE].errmsg;

    Rename the #define E__COUNT to ECOUNT to avoid confusion
    with "E_STRING" error symbols.

    Renamed "E_1OVER0" to "E_DIVBYZERO".
    Renamed "E_0OVER0" to "E_ZERODIVZERO".

    The verify_error_table() function that does a verification
    the error_table[] array and setup private_error_alias[] array
    is now called by libcalc_call_me_first().

    Fix comment about wrong include file in have_sys_mount.h.

    Removed unused booltostr() and strtobool() macros from bool.h.

    Moved define of math_error(char *, ...) from zmath.h to errtbl.h.
    The errtbl.h include file, unless ERRCODE_SRC is defined
    also includes attribute.h and errsym.h.

    Added E_STRING to error([errnum | "E_STRING"]) builtin function.
    Added E_STRING to errno([errnum | "E_STRING"]) builtin function.
    Added E_STRING to strerror([errnum | "E_STRING"]) builtin function.
    Calling these functions with an E_STRING errsym is the same as calling
    them with the matching errnum code.

    Standardized on calc computation error related E_STRING strings
    where there are a set of related codes.  Changed "E_...digits" into
    "E_..._digits".  For example, E_FPUTC1 became E_FPUTC_1, E_FPUTC2
    became E_FPUTC_2, and E_FPUTC3 became E_FPUTC_3.  In a few cases
    such as E_APPR became E_APPR_1, because there was a E_APPR2 (which
    became E_APPR_2) and E_APPR3 (which became E_APPR_3).  To other
    special cases, E_ILOG10 became E_IBASE10_LOG and E_ILOG2 became
    E_IBASE2_LOG because E_ILOG10 and E_ILOG2 are both independent calc
    computation error related E_STRING strings.  Now related sets of
    E_STRING strings end in _ (underscore) followed by digits.

    Added errsym builtin function.  The errsym(errnum | "E_STRING")
    builtin, , when given a valid integer errnum that corresponds to a
    calc error condition, will return an E_STRING string, AND when given
    a valid E_STRING string that is associated with a calc error
    condition, will return errnum integer that corresponds to a calc
    error condition.

    Supplying a non-integer numeric errnum code to error(), errno(),
    strerror(), or errsym() will result in an error.

    Added tests to the calc regression test suite (cal/regress.cal) to
    verify that the errnum calc computation error codes and their
    E_STRING values have not changed.

    Improved the clarity of calc regression suite (regress.cal) to mostly
    use E_STRING errsym instead of numeric errnum values for error()
    and errno() related tests.

    Fixed SEE ALSO typo in help randperm.

    Fixed calc regression test 42dd to set the display value back to 20.

    Added to test 95dd and test9500.trigeq.cal to the calc regression test
    suite to perform extensive test of trigonometric functions.

    Added to test 34dd, some if the missing inverse trigonometric tests.

    Improved builtin function strings, as printed by help builtin,
    that use an optional accuracy (epsilon) arg by adding a comma.


The following are the changes from calc version 2.14.3.4 to 2.14.3.5:

    Under macOS, to reduce dependency chains, we remove functions
    and data that are unreachable by the entry point or exported
    symbols.  In particular, the macOS linker is used with both
    "-dead_strip" and "-dead_strip_dylibs".

    The libcalc shared library is now linked with libcustcalc.

    The config("triground") controls rounding for the following
    trigonometric and hyperbolic functions:

        sin, cos, tan, cot, sec, csc
        asin, acos, atan, acot, asec, acsc
        versin, coversin, vercos, covercos
        aversin, acoversin, avercos, acovercos
        haversin, hacoversin, havercos, hacovercos
        ahaversin, hacoversin, havercos, ahacovercos
        exsec, aexsec, excsc, aexcsc
        crd, acrd
        cas, cis
        sinh, cosh, tanh, coth, sech, csch
        asinh, acosh, atanh, acoth, asech, acsch

    In addition to taking a complex root (such as via the power
    function on a complex value), "triground" is used for:

        exp, polar

    For the above mentioned functions, the rounding mode used to
    round the result to the nearest epsilon value is controlled by,
    and defaults to:

        config("triground", 24)

    As with other config options, the call returns the previous mode,
    without a 2nd argument, returns the current mode without changing it:

        config("triground")

    When printing an error, calc used to print the errnum (error number):

        ; 1/0
                Error 10001

    Calc now prints the errsym (errsym):

        ; 1/0
                Error E_DIVBYZERO

    Added errsym E_LN_3 for ln(0).
    Added errsym E_LOG_5 for log(0).
    Added errsym E_LOG2_4 for log2(0).
    Added errsym E_LOGN_6 for logn(0,base).

    Added a chk_tree tool to help look for problems such as files that are
    result of building calc that are also part of the calc distribution,
    and files that are part of the calc source that are missing from the
    calc distribution, and files that are of unknown status that are either
    result of building calc nor missing from the calc distribution.

    Updated file lists in Makefile, sorting as needed.

    Updated Makefile PHONY rule to include Makefile rules that are NOT files.

    Reduced make chatter for rules that build lists.

    Added make verifydist to verify the existence of files that are part of
    the calc distribution.

    Added make verifydist to make prep.

    Added a chk_tree double check, one after make clobber, one before
    the final make chk, to make prep.  Added double pass of chk_tree to
    make full_debug (and thus to the make debug output).

    Improved notes for install locations in Makefile.config.

    Added printing of ${BUILD_ALL} to make env output.


The following are the changes from calc version 2.14.3.0 to 2.14.3.4:

    Fix typo in the `make debug` Makefile rule.

    Improved .gitignore to ignore .static, calc-static,
    sample_many-static and sample_rand-static.

    Improved error messages when trying to compile with
    with one calc type (when BLD_TYPE=calc-dynamic-only or
    BLD_TYPE=calc-static-only) and install with the other.

    When installing with BLD_TYPE=calc-static-only, the
    installed calc and calc-static are links to each other.
    Thanks to GitHub user @TurtleWilly for this suggestion.

    The dynamic shared libraries are not installed if they are not
    built.  So when installing with BLD_TYPE=calc-static-only, the
    install rule will not attempt to install dynamic shared libraries.
    Thanks to GitHub user @TurtleWilly for bringing to our attention,
    problems related to building a statically linked calc under macOS.

    Updated comments in Makefile.local for how to Diagnosing memory,
    thread, and crash issues under RHEL and macOS.

    We no longer support the Makefile variable ${ALLOW_CUSTOM} to be empty.
    Normally ${ALLOW_CUSTOM} is:

        ALLOW_CUSTOM= -DCUSTOM

    Now, to disable custom disable custom even if -C is given, use:

        ALLOW_CUSTOM="-UCUSTOM"

    Dropped support of Makefile.simple and custom/Makefile.simple.
    The calc version 2.14.3.0 is the last release that supported
    the Makefile.simple and custom/Makefile.simple files.
    Now, a make that supports makefile conditional syntax is required.
    The simple target, a target that only was used for Makefile.simple
    was removed.

    Moved makefile variables that configure calc and configure how to
    compile calc from Makefile into a new Makefile.config file.

    The Makeifle includes the Makefile.config file.
    The cal/Makeifle includes the Makefile.config file.
    The cscript/Makeifle includes the Makefile.config file.
    The custom/Makeifle includes the Makefile.config file.
    The help/Makeifle includes the Makefile.config file.

    Now, the Makefile.config file will consistently configure
    calc and how calc is compiled and built by all calc Makefiles.
    The custom/Makefile no longer includes Makefile.

    The platform target section from the old Makefile has been moved
    to a new file, Makefile.target.  Improved the format and comments
    in target information.

    The Makeifle includes the Makefile.target file.
    The cal/Makeifle includes the Makefile.target file.
    The cscript/Makeifle includes the Makefile.target file.
    The custom/Makeifle includes the Makefile.target file.
    The help/Makeifle includes the Makefile.target file.

    Now, the Makefile.target file will consistently set
    target information for all calc Makefiles.

    The cal/Makeifle includes the Makefile.local file.
    The cscript/Makeifle includes the Makefile.local file.
    The custom/Makeifle includes the Makefile.local file.
    The help/Makeifle includes the Makefile.local file.

    Thus, one may modify or append many Makefile variables
    in all calc Makefiles.

    Removed the ${CAL_PASSDOWN}, ${HELP_PASSDOWN}, ${HELP_PASSDOWN},
    ${CSCRIPT_PASSDOWN} Makefile variables as the new Makefile
    include files keep Makefile variables in sync.

    Fixed the ability of calc to compile when CUSTOM is undefined
    (i.e., -UCUSTOM).  The libcustcalc is always built, regardless
    of the $(ALLOW_CUSTOM} Makefile variable.  However when CUSTOM
    is undefined, the bulk of custom functions are not defined.

    Dropped the use of Makefile variable ${SET_INSTALL_NAME}.
    Under macOS it was always needed, elsewhere it was not.

    Added Makefile variable ${VER} to hold the calc major release version.
    The calc major release version is a 3 level version (x.y.z).

    Under macOS, the current version of both libcalc and libcustcalc
    shared libraries are set to the current calc major release version.

    Under macOS, to reduce dependency chains, we remove functions and
    data that are unreachable by the entry point or exported symbols.
    In particular, the macOS linker is used with "-dead_strip" by default.

    While calc on macOS will execute if linker used with "-dead_strip_dylibs"
    and CUSTOM is defined, other applications that use libcalc but not
    libcustcalc (such as sample_many and sample_rand) will fail to execute
    due to missile symbols.  Therefore "-dead_strip_dylibs" is not used
    by default when ALLOW_CUSTOM is "-DCUSTOM" under macOS.
    Thanks to GitHub user @TurtleWilly for bringing to our attention,
    problems related to use of  "-dead_strip_dylibs".

    When installing shared libraries, libcalc.x.y.z will be a link
    to the libcalc shared library and libcustcalc.x.y.z will be a link
    to the libcustcal shared library.


The following are the changes from calc version 2.14.2.1 to 2.14.3.0:

    Added cal/fnv_tool.cal, a calc resource file defining:

        find_fnv_prime(bits)
        deprecated_fnv0(bits,fnv_prime,string)
        fnv_offset_basis(bits,fnv_prime)
        fnv1a_style_hash(bits,fnv_prime,prev_hash,string)

    Fixed sorted order of cal/README.

    Removed references to obsolete Email addresses.

    macOS Darwin defaults LCC to "cc".

    Updated COPYING to include the actual text of "The Unlicense".
    Made minor formatting changes to the file.

    The Darwin specific ${DARWIN_ARCH}, thay by default was unset,
    is now the ${ARCH_CFLAGS} Makefile variable.  Comments about
    various "-arch name" have been moved to the ${ARCH_CFLAGS} area.

    For old Apple Power PC systems, the following is added:

        COMMON_CFLAGS+= -std=gnu99
        COMMON_LDFLAGS+= -std=gnu99
        ARCH_CFLAGS+= -arch ppc

    Old Apple Power PC systems should be detected by the
    "uname -p" command returning "powerpc".  One may force the
    Power PC mode by adding to the end of any make command:

        make ...make_args... target=Darwin arch=powerpc

    or by adding the following in the Makefile.local file:

        target= Darwin
        arch= powerpc

    Improved the output of the calcinfo rule by adding echos
    of various uname values as well as some top Makefile variables.

    Fixed the BUGS file with respect to using `make debug`.

    Added a final ls of `debug.out` for `make debug`.


The following are the changes from calc version 2.14.2.0 to 2.14.2.0:

    Ported calc to the s390x IBM Mainframe running RHEL9.1.

    Added cal/splitbits.cal:

        splitbits(x, b)

        Given an integer x, split the value into a list of integers,
        each of which is at most b bits long.

        The value b must be an integer > 0.

        The number of elements in the returned list is:

            ceil((highbit(x) + 1) / b)

        If x == 0, then a list of 1 element containing 0 is returned.

        If x < 0, then the two's compliment of abs(x) is returned.
        Even though calc represents negative integers as positive values
        with sign bit, the bits returned by this function are as if
        the integer converted as if the integer was a two's compliment value.

        See also the help command:

            ; help resource


The following are the changes from calc version 2.14.1.5 to 2.14.1.6:

    Fixed version numbers in two cases in CHANGES that referred
    to the 2.14.2.x instead of 2.14.1.x.

    Rename MINGW Makefile variable (a holdover from MINGW32_NT-5.0)
    to OSNAME.

    Fixed FUNCPTR typedef in hist.c to fix deprecated compiler warnings.

    Fixed when USE_READLINE, READLINE_LIB, READLINE_EXTRAS, and
    READLINE_INCLUDE are set to empty (disable use of the GNU-readline
    facility).

    Fix cases of spaces before tabs in Makefile and Makefile.simple.

    Fixed obsolete references to the atoz() in LIBRARY to use the
    correct internal function name of str2z().

    Fixed obsolete references to the atoq() in LIBRARY to use the
    correct internal function name of str2q().

    Document in help/unexpected that * operator has has a higher
    precedence than << in calc, which differs from C.  Thanks
    goes to GitHub user @inguin for pointing put this difference.


The following are the changes from calc version 2.14.1.3 to 2.14.1.4:

    Fixed missing <string.h include in have_fpos_pos.c.

    Change calc version from 2.14.1.2 to 2.14.2.3 as part of a test to
    build calc RPMs on a reference RHEL8.7 platform (formerly a RHEL7.9
    platform).

    Changes #! lines in Makefiles to "#!/usr/bin/env make".

    Set SHELL in Makefiles to the basename of the shell.

    Updated COPYING file to indicate that these files are now
    covered under "The Unlicense" (see https://unlicense.org):

            sha1.c
            sha1.h
            cal/dotest.cal
            cal/screen.cal

    Updated help/credit to match the above changes to COPYING.

    Updated CONTRIB-CODE and calc.man to refer to using GitHub pull requests
    for contributing to calc (instead of using Email).

    Updated BUGS and calc.man to refer to using GitHub issues
    for reporting calc bugs (instead of using Email).

    Updated QUESTIONS and calc.man to refer to using GitHub issues
    for asking calc questions (instead of using Email).

    Fixed Makefile.local command example to refer to overriding the
    Makefile variable DEBUG (instead of CDEBUG).

    Fixed all make chk ASAN warnings under macOS 13.2.1 when calc is compiled
    with the following uncommented lines in Makefile.local:

        DEBUG:= -O0 -g
        CFLAGS+= -fsanitize=address -fno-omit-frame-pointer -fsanitize=undefined
        LDFLAGS+= -fsanitize=address -fno-omit-frame-pointer -fsanitize=undefined
        CALC_ENV+= ASAN_OPTIONS=detect_stack_use_after_return=1

    Improved how pointers to functions are declared for the builtins
    array in func.c to avoid function declarations without a prototype
    that is now deprecated in C.

    Improved how pointers to functions are declared for the opcodes
    array in opcodes.c to avoid function declarations without a prototype

    Replaced use of egrep with grep -E in Makefiles.

    Fixed cases where variables were set but not used in symbol.c, calc.c,
    and the main function in func.c as used by funclist.c.

    Added rule name to "DO NOT EDIT -- generated by the Makefile" lines
    in constructed files.

    Test if <sys/vfs.h> exists and set HAVE_SYS_VFS_H accordingly
    in have_sys_vfs.h.  Added HAVE_SYS_VFS_H to allow one to force
    this value.

    Test if <sys/param.h> exists and set HAVE_SYS_PARAM_H accordingly
    in have_sys_param.h.  Added HAVE_SYS_PARAM_H to allow one to force
    this value.

    Test if <sys/mount.h> exists and set HAVE_SYS_MOUNT_H accordingly
    in have_sys_mount.h.  Added HAVE_SYS_MOUNT_H to allow one to force
    this value.

    Test if the system as the statfs() system call and set HAVE_STATFS
    accordingly in have_statfs.h.  Added HAVE_STATFS to allow one
    to force this value.

    The pseudo_seed() function will also try to call statfs() if
    possible and permitted by the HAVE_STATFS value.

    Test if makedepend command is available before trying to build
    the Makefile dependency list via "make depend".


The following are the changes from calc version 2.14.1.0 to 2.14.1.2:

    Attempted to address a paranoid compiler warning -Wmaybe-uninitialized
    in swap_HALF_in_ZVALUE() where the gcc compiler seems to ignore the
    fact that calling not_reached() above the call to zcopyval()
    should prevent dest from being NULL to the 1st zcopyval() call.
    Thanks to <GitHub user mattdm> for raising this potential concern.

    Fixed a -Wuse-after-free warning that identified a call to realloc()
    in find_tty_state() could move the fd_setup array.  Thanks goes to
    <GitHub user mattdm> for reporting this bug!

    In find_tty_state(), we changed how we expand fd_orig as an original
    pre-modified copy of fd_setup.  We realloc the fd_orig array and copy
    the fd_setup into it first, before touching the fd_setup array.

    In pseudo_seed(), we removed a call to setjmp() that was only
    there to add more information to mix into the seed.  For compilers
    such as gcc that used -Wclobbered, the call to setjmp() gave the
    impression that the hash_val might be clobbered by a longjmp().
    Where there is no longjmp() that would use the previous setjmp(),
    the gcc compiler has nil ways to notice that. So to avoid confusion
    we removed the setjmp() call.  Thanks to <GitHub user mattdm> for
    raising this potential concern.

    Added config("tilde_space", boolean).  The "tilde_space" controls
    whether or not a space (' ') is printed after leading tilde ('~').
    By default, config("tilde_space") is false.

    For example, with the default, config("tilde_space", 0):

        ; 1/3
                ~0.33333333333333333333
        ; sqrt(7 + 5i,1e-100)
                ~2.79305614578749801863+~0.89507688693280053094i

    With config("tilde_space", 1):

        ; 1/3
                ~ 0.33333333333333333333
        ; sqrt(7 + 5i,1e-100)
                ~ 2.79305614578749801863+~ 0.89507688693280053094i

    NOTE: Use of config("tilde_space", 1) can break printing and scanning
          of complex values via "%c".

    To enable "tilde_space", use config("tilde_space", 1) on the
    command line and/or use config("tilde_space", 1),; in your ~/.calcrc.
    Thanks goes to <GitHub use ljramalho> for this suggestion.

    Added config("tilde_space", boolean) to help/config, along with
    a few few minor text improvements.  Updated cal/regress to test
    config("tilde_space").

    For example, with the default, config("tilde_space", 0):

        ; pi(1e-50)
                ~3.14159265358979323846

    With config("tilde_space", 1):

        ; pi(1e-50)
                ~ 3.14159265358979323846

    Added config("fraction_space", boolean).  The "fraction_space" controls
    whether or not a space (' ') is printed before and after fractions.
    By default, config("fraction_space") is false.

    For example, with the default, config("fraction_space", 0):

        ; base(1/3),
        ; 1/7
                1/7

    With config("fraction_space", 1):

        ; base(1/3),
        ; 1/7
                1 / 7

    NOTE: Use of config("fraction_space", 1) can break printing and scanning
          of fractional values via "%r".

    NOTE: Use of config("fraction_space", 1) can break printing and scanning
          of complex values via "%c".

    Added config("fraction_space", boolean) to help/config, along with
    a few few minor text improvements.  Updated cal/regress to test
    config("tilde_space").

    Added config("complex_space", boolean).  The "complex_space" controls
    whether or not a space (' ') is printed before and after the + or -
    in complex values.

    By default, config("complex_space") is false.

    For example, with the default, config("complex_space", 0):

        ; asin(2)
                1.57079632679489661923-1.31695789692481670863i

    With config("complex_space", 1):

        ; asin(2)
                1.57079632679489661923 - 1.31695789692481670863i

    NOTE: Use of config("complex_space", 1) can break printing and scanning
          of fractional values via "%r".

    NOTE: Use of config("complex_space", 1) can break printing and scanning
          of complex values via "%c".

    Added config("complex_space", boolean) to help/config, along with
    a few few minor text improvements.  Updated cal/regress to test
    config("complex_space").

    Clarify in the calc man page, the relationship between -q and
    calc start scripts such as the ~/.calcrc file.

    Fixed in the calc man page, the issue of -f not implying -q.


The following are the changes from calc version 2.14.1.2 to date:

    Restored use of the #define FPOS_POS_LEN symbol.  This refers to
    the length of the __pos element (if the __pos element exists),
    the fpos_t type (if that type exists).

    Changed SWAP_HALF_IN_FILEPOS(dest, src) mato to use FILEPOS_LEN Little
    Endian when FILEPOS is a simple scalar type (i.e., HAVE_FILEPOS_SCALAR
    is defined).

    Changed #define HAVE_FPOS to HAVE_FGETSETPOS.

    Corrected comment in have_fpos_pos.h.  The HAVE_FPOS_POS symbol was
    NOT related to fgetpos & fsetpos but rather if we we have an __pos
    element in FILEPOS.

    Changed #define HAVE_NO_FPOS to HAVE_NO_FGETSETPOS.

    Improved comments in have_fpos_pos.h to show why and how
    HAVE_FPOS_POS, FPOS_POS_BITS, and FPOS_POS_LEN were defined or undefed.

    Changed showfiles builtin to print sizes cast to (long int) with
    the "%ld" printf format to avoid implementations that do not support
    the "%lld" printf format specifier.

    Renamed have_fpos.h to have_fgetsetpos.h.  Renamed CALC_HAVE_FPOS_H
    to CALC_HAVE_FGETSETPOS_H.  The make install and the olduninstall
    rules remove the any old have_fpos.h that was previously installed.

    Added swap_HALFs(dest, src, len) function to byteswap.c.

    Calc can now handle Big Engian file position sizes that are a
    multiple of BASEB bits in length.  Before handle Big Engian file
    positions could only be 32 and 64 bits in length.  This will allow,
    for example, a Big Engian file position size of 128 (assuming that
    128/BASEB is is an integer).

    Temporary workaround for musl libc systems such as gentoo Linux that
    allows them to compile calc and successfully run the regression test.


The following are the changes from calc version 2.14.1.1 to 2.14.1.1:

    Added a few remarks on calc version numbers to version.c.

    Fixed how fposval.h is built.  On a number of systems, the fposval.c
    file failed to compile incorrectly.  This caused problems for systems in
    which fposval.h.def was not correct.

    Fixed how have_memmv.h is built.  On a number of systems, the have_memmv.c
    file failed to compile incorrectly, producing a potentially incorrect
    have_memmv.h file for such systems.

    Fixed how align32.h is built.  On a number of systems, the align32.c
    file failed to compile incorrectly, producing a potentially incorrect
    align32.h file for such systems.

    Fixed how have_newstr.h is built.  On a number of systems, the have_newstr.c
    failed to compile incorrectly, producing a potentially incorrect
    have_newstr.h file for such systems.

    Fixed how have_strdup.h is built.  On a number of systems, the have_strdup.c
    file failed to compile incorrectly, producing a potentially incorrect
    have_strdup.h file for such systems.

    Fixed how have_strlcat.h is built.  On a number of systems, the have_strlcat.c
    file failed to compile incorrectly, producing a potentially incorrect
    have_strlcat.h file for such systems.

    Fixed how have_strlcpy.h is built.  On a number of systems, the have_strlcpy.c
    file failed to compile incorrectly, producing a potentially incorrect
    have_strlcpy.h file for such systems.

    Fixed how have_uid_t.h is built.  On a number of systems, the have_uid_t.c
    file failed to compile incorrectly, producing a potentially incorrect
    have_uid_t.h file for such systems.

    Fixed how have_uid_t.h is built.  On a number of systems, the have_uid_t.c
    file failed to compile incorrectly, producing a potentially incorrect
    have_uid_t.h file for such systems.

    Added full_debug rule to Makefile.  This does the work of the
    old debug rule in a more verbose mode by using Q= H=@ S= E= V=@.

    The debug rule in the Makefile now pre-removes debug.out and then
    runs make full_debug sending stdout and stderr to debug.out.  It then
    prints a few instructions about filing a GitHub issue bug report.

    The full_debug rule will no longer stop when one of the sub-tasks
    failed (exit non-zero).


The following are the changes from calc version 2.14.1.0 to 2.14.1.0:

    Fixed alignment of show item section of help command.

    Bug fix: While 0^0 == 1, now for y > 0, 0^y == 0.
    Adjusted cal/test8900.cal to reflect this bug fix.
    Added tests to cal/regress.cal to help verify bug fix is fixed.

    Fixed a \-escape bug in calc(1) man page.

    Added cal/comma.cal:

        Convert numbers into strings with 3-digit group and integer-fraction
        separators.

        If the value is an integer, the integer-fraction separator is not used.

        str_comma(x, [group, [decimal]])

            Convert x into a string.

            If group is given and is a string, group will be used as
            the 3-digit group separator, otherwise the default 3-digit
            group separator will be used.

            If decimal is given and is a string, group will be used as
            the integer-fraction separator, otherwise the default
            integer-fraction separator will be used.

            The decimal and group arguments are optional.

        set_default_group_separator(group)

            Change the default 3-digit group separator if group is a string,
            otherwise the default 3-digit group separator will not be
            changed.  Return the old 3-digit group separator.

        set_default_decimal_separator(decimal)

            Change the default 3-digit group separator if decimal is a
            string, otherwise the default integer-fraction separator
            will not be changed.  Return the old integer-fraction separator.

        print_comma(x, [group, [decimal]])

            Print the value produced by str_comma(x, [group, [decimal]])
            followed by a newline.

            If the str_comma() does not return a string, nothing is printed.

            The decimal and group arguments are optional.

            The value produced by str_comma() is returned.

        fprint_comma(fd, x, [group, [decimal]])

            Print the value produced by str_comma(x, [group, [decimal]]),
            without a trailing newline, on file fd.

            If the str_comma() does not return a string, nothing is printed.

            If fd is not an open file, nothing is printed.

            The decimal and group arguments are optional.

            The value produced by str_comma() is returned.


The following are the changes from calc version 2.14.0.15 to 2.14.0.15:

    Changed Makefile to set shell before setting the SHELL Makefile
    variable.

    Added text to HOWTO.INSTALL to help people with systems that
    lack the readline package.

    Trimmed long line in the CONTRIBUTING.md file.

    Expanded the globalsymbol string table size: from 1024 to 65536.

    Expanded the how often to reallocate string table is performed:
    from 100 to 1024.

    Expanded the number env_pool elements to allocate at a time:
    from 10 to 256.

    Improve comments on Makefile.local and add a few more examples
    of how it might be used.

    Changed /*NOTREACHED*/ to not_reached(); and use "attribute.h".

    Added .PHONY rule, just after all rule, to Makefiles.

    Made minor format update on help/commands.

    Added ${WINGM} Makefile variable for users under Windows 11 who
    use Cygwin and the MinGW64 packages.

    Updated README.WINDOWS for Windows 11 users based on advice
    form a Microsoft 11 developer.

    Fixed missing quotes in the PASSDOWN makefile variables.

    Disable use of gettime() under _WIN32 or _WIN64.


The following are the changes from calc version 2.14.0.14 to 2.14.0.14:

    Fixed typo in Makefile.local comment.

    Established a tagging procedure for a production release.
    Production git tags will be of the form:

        prod-2.x.y.z


The following are the changes from calc version 2.14.0.13 to 2.14.0.13:

    Made major changes to our release process in order to avoid
    missing critical files that happened in calc v2.4.0.12.

    Minor tweak to seed() builtin.  Updated help/srand and help/srandom.

    Moved Makefile.ship into Makefile.

    Removed custom/Makefile.head and custom/Makefile.tail.

    The custom/Makefile is now part of source and includes Makefile.
    In particular, custom/Makefile makes use of the 'middle' of
    the new top level Makefile where calc's top level Makefile
    variables are defined.

    Makefile.simple and custom/Makefile.simple are now part of the source
    and are constructed from Makefile and custom/Makefile respectively.
    The Makefile.simple and custom/Makefile.simple avoid using GNU
    conditionals. They may be used with older/classic make commands.

    Makefile.local will include comments about how to better use
    it. Between releases, Makefile.local at the top of the master branch
    will contain how we typically build calc and test calc (FYI: we
    normally enable things such as -Werror -Wextra -pedantic).  When we
    push out a release, Makefile.local will be stripped of non-comment
    lines.  Thus, releases of calc, and, released "calc*.src.rpm"
    files and the source tarballs, will have a Makefile.local with
    only comments.

    The "README.*" files and "HOWTO.INSTALL" file have been updated.

    By default, compiler warnings have been turned up.  The Makefile
    variable ${CCWARN} now defaults to:

        CCWARN= -Wall -Wextra -pedantic

    The previous level of compiler warnings can be easily restored by
    adding to Makefile.local:

        CCWARN:= -Wall

    The readline, history and ncurses libraries are now default.
    The Makefile variables ${USE_READLINE}, ${READLINE_LIB}, and
    ${READLINE_EXTRAS} now default to:

        USE_READLINE= -DUSE_READLINE
        READLINE_LIB= -lreadline
        READLINE_EXTRAS= -lhistory -lncurses

    The previous mode where readline, history and ncurses libraries
    were not compiled in by default can be easily restored by
    adding to Makefile.local:

        USE_READLINE:=
        READLINE_LIB:=
        READLINE_EXTRAS:=

    We have renamed "stable" as "production".
    We have renamed "unstable" as "tested".

    On the web site:

        http://www.isthe.com/chongo/src/calc/

    these files has been renamed:

        2.x.y.z_IS_LATEST_STABLE   ==> 2.x.y.z_IS_LATEST_PRODUCTION
        2.x.y.z_IS_LATEST_UNSTABLE ==> 2.x.y.z_IS_LATEST_TESTED

    The terms 'stable' and 'unstable' were both misleading and
    inaccurate.  For details see the new documention file:

        README.RELEASE

    See also the help command:

        ; help release

    Fixed bug impacting how have_ustat.h was formed.

    Updated help/archive, BUGS, HOWTO.INSTALL to reflect GitHub use.


The following are the changes from calc version 2.14.0.11 to 2.14.0.12:

    Fixed a number of typos.

    Drop support for SunOS, IRIX and MINGW32_NT-5.0 targets.
    Drop support for CLOCK_SGI_CYCLE.  Drop testing for __MSDOS__.

    Minor improvement of various help files.  Made format of help
    files more consistent.

    Corrected a few comments in zrandom.c, including a case where
    the comment referred to 1007 when it should have used 2^32.

    Improved seed() generation.  Improved some comments in seed.c.
    Added have_environ.c to build have_environ.h in order to
    determine if:

        extern char **environ;  /* user environment */

    is an valid external symbol.

    Fixed documentation that referred to the old additive 55
    generator.  We have been using the subtractive 100 in place
    of the additive 55 generator for a while now.

    Fixed depend rule for custom/Makefile.

    Fixed how Makefile variable SHELL is set on macOS vs. Linux.
    Using /bin/sh on macOS due to how zsh treats globs by default.

    Added charbit.h to define CALC_CHARBIT which is either CHAR_BIT
    from <limits.h> or 8 or a value set by the Makefile variable
    CALC_CHARBIT.  Added have_limits.h to determine if <limits.h>
    is a system include file.

    Compiling now tests for _WIN64 as well when testing for _WIN32.

    Now assuming that <stdio.h> is available under _WIN32 and _WIN64.

    Added some preliminary notes about attempts to compile calc
    under Windows 11.

        BTW: While we are unable to use Windows 11, we welcome
             Windows 11 developers to try compiling calc natively
             (instead of via a Linux virtual machine).  If you are
             able to compile Windows 11 natively, we would welcome
             GitHub pull requests showing any needed modifications:

                https://github.com/lcn2/calc/pulls

             Please also add notes to the 'Compiling calc under Windows 11'
             section in README.WINDOWS file.

    We added Makefile.simple as part of the master branch source
    to help those who may be using a make tool that does not support
    GNU Make-like features such as "ifeq" and ":=".

    Fixed incorrect ustat_dev member ref in seed() builtin that
    was part of the unreleased calc v2.12.0.11.


The following are the changes from calc version 2.14.0.9 to 2.14.0.10:

    Due to issues with clang and Apple Silicon, ARCH_CFLAGS is now,
    by default, empty:

        ARCH_CFLAGS=

    If you want to use, say, -march=native, then either change
    the Makefile or make with:

        make all ARCH_CFLAGS='-march=native'

    Added arch and hardware as GNU Makefile computed values.
    As with ${target}, ${arch} and ${hardware} is computed by uname:

        target: uname -a
        arch: uname -p
        hardware: uname -m

    Fixed compiling calc on Apple Silicon with HomeBrew.  On Apple
    Silicon, HomeBrew installs on into a different location.  The
    Makefile checks if ${hardware} is arm64 and adjusts the location
    of libraries such as readline and history accordingly.

    Plugged a number of memory leaks.

    Fixed a few cases where v_subtype was not properly initialized.

    Improved the way that internal pre-defined constants are managed.
    Removed unused internal pre-defined constants.  Added code to
    prevent an internal pre-defined constant (that was never allocated)
    from being freed.

    Remove unnecessary spaces in-between or next to tabs.

    Update copyright dates to account for 2021 modifications.


The following are the changes from calc version 2.14.0.7 to 2.14.0.8:

    Fizzbin is a better word. :-)

    The help and man builtin commands now return an error when a
    help file cannot be opened, such as when there is no help file.

    Added palindrome.cal resource file.  For example, to find the
    largest (highly probable) prime palindrome under 280 decimal
    digits (text tweet limit):

        prevprimepal(1e280)


The following are the changes from calc version 2.14.0.0 to 2.14.0.6:

    The :-separated default CALCRC value has been reversed.
    The default CALCRC was:

        ${CALC_SHAREDIR}/startup:~/.calcrc:./.calcinit

    The default CALCRC is now:

        ./.calcinit:~/.calcrc:${CALC_SHAREDIR}/startup

    See "help environment" for details.

    Added engineering mode as per a GitHub pull request from
    <GitHub user heitzmann>.  Thank you!  For example:

        ; config("mode","eng"),
        ; 10^41
                100e39

    or for example:

        ; base(1000),
        ; 2^23209-1
                ~402.87411577898877818187e6984

    For more information see:

        help base

    Added regression test code for engineering mode.  Improved and
    expanded regression test code related to the base() and base2()
    builtin functions.

    Fixed a critical bug in the above mentioned pull request where
    a call to base2(1000) would make calc unstable and likely to
    dump core.

    Added builtin functions to convert between degrees, radians
    and gradians:

        d2r(deg)        - given degrees returns radians
        g2r(grad)       - given gradians returns radians

        r2d(rad)        - given radians returns degrees
        g2d(grad)       - given gradians returns degrees

        r2g(rad)        - given radians returns gradians
        d2g(deg)        - given degrees returns gradians

    Add 6 functions take a 2nd optional epsilon argument.
    For d2r(deg, ep), r2d(rad, ep), the optional 2nd epsilon argument controls
    the precision of the internal constant pi/180.
    For g2r(grad, ep), r2g(rad, ep), the optional 2nd epsilon argument controls
    the precision of the internal constant pi/200.
    The optional 2nd argument is ignored by g2d(grad, ep) and d2g(deg, ep).

    The clean and clobber makefile rules no longer list custom/Makefile
    as a dependency.

    Unfortunately due to the complex dependency issues between
    Makefile, Makefile.ship and custom/Makefile, parallel GNU make
    is NOT recommended.  Sorry (tm Canada) :)

    The clean and clobber makefile rules no longer list custom/Makefile
    as a dependency.

    Unfortunately due to the complex dependency issues between
    Makefile, Makefile.ship and custom/Makefile, parallel GNU make
    is NOT recommended.  Sorry (tm Canada) :)

    Fixed a few typos in CHANGES.

    As a side note: We stayed v2.13.x was kept for only a short time.
    The move to 2.14.x was motivated by non-compatible changes due to
    the default order of CALCRC, plus some new builtin functions.

    More changes are likely, so we might see another v2.14.0.x release
    before things are declared "recommended stable".

    Not that we want to discourage people from trying v2.14.0, you should
    try it.  We just want things to become stable and well field tested
    before we reach the "recommended stable" release state.

    Added builtin functions to convert between degrees and
    degrees, minutes and seconds under the config("mod")
    round rules:

        d2dms(degs, d, m, s [,rnd]) - given degs, compute d, m, s
        d2dm(degs, d, m [,rnd]) - given degs, compute d, m

        See help/d2dms and help/d2dm.

    Example:

        ; print d2dms(360.321,deg=,min=,sec=), deg, min, sec;
        0.321 0 19 15.6

        ; print d2dm(360.321,deg=,min=), deg, min;
        0.321 0 19.26

    Added builtin functions to convert between gradians and
    gradians, minutes and seconds under the config("mod")
    round rules:

        g2gms(grads, g, m, s [,rnd]) - given grads, compute g, m, s
        g2gm(grads, g, m [,rnd]) - given grads, compute g, m

        See help/g2gms and help/g2gm.

    Example:

        ; print g2gms(400.321,grad=,min=,sec=), grad, min, sec;
        0.321 0 19 15.6

        ; print g2gm(400.321,grad=,min=), grad, min;
        0.321 0 19.26

    Added builtin functions to convert between hours and
    hours, minutes and seconds under the config("mod")
    round rules:

        h2hms(hours, h, m, s [,rnd]) - given hours, compute h, m, s
        h2hm(hours, h, m [,rnd]) - given hours, compute h, m

        See help/h2hms and help/h2hm.

    Example:

        ; print h2hms(24.321,hour=,min=,sec=), hour, min, sec;
        0.321 0 19 15.6

        ; print h2hm(24.321,hour=,min=), hour, min;
        0.321 0 19.26

    Renumbered regression tests 3408 thru 3437, to 9102 thru 9131.

    Updated Added hms.cal resource file to use h2hms() builtin.
    Updated Added dms.cal resource file to use d2dms() builtin.

    Fix minor typo in help/mod SYNOPSIS.
    Fix minor typo in help/quo SYNOPSIS.

    Added a few more examples to help/strcmp.

    Added builtin functions to convert between degrees, minutes and
    seconds and degrees under the config("mod") round rules:

        dms2d(d, m, s [,rnd]) - convert deg, min, and secs to deg
        dm2d(d, m [,rnd]) - convert deg, min to deg

        See help/dms2d and help/dm2d.

    Example:

        ; print dms2d(12, 20, 44.16);
        12.3456

        ; print dm2d(3601, -25.5594);
        0.57401

    Added builtin functions to convert between gradians, minutes and
    seconds and gradians under the config("mod") round rules:

        gms2g(g, m, s [,rnd]) - convert grad, min, and secs to grad
        gm2g(g, m [,rnd]) - convert grad and min to grad

        See help/g2gms and help/g2gm.

    Example:

        ; print gms2g(12, 20, 44.16);
        12.3456

        ; print gm2g(4001, -25.5594);
        0.57401

    Added builtin functions to convert between hours, minutes and
    seconds and hours under the config("mod") round rules:

        hms2h(h, m, s [,rnd]) - convert hours, min, and secs to hours
        hm2h(h, m [,rnd]) - convert hours, min to hours

        See help/hms2h and help/hm2h.

    Example:

        ; print hms2h(12, 20, 44.16);
        12.3456

        ; print hm2h(241, -25.5594);
        0.57401

    Fixed typo in cal/statistics.cal thanks to a report by <GitHub user
    dennisaldea>.

    Fixed an old Windows pun in README.WINDOWS as requested by <GitHub
    user marcodegio>.

    Fixed a really obscure bug in the internal initconstants()
    function of const.c that has been sitting for over 31 years!

        We are amazed that nobody has encountered this bug before
        now.  Nevertheless, our very extensive regression and
        multi-architecture testing found the bug.  Now, after all
        those years, it is fixed.

    Fixed issues identified by the default CodeUL GitHub security code scan:

        Wrong type of arguments to printf in have_fpos_pos.c
        Multiplication result converted to larger type in zfunc.c


The following are the changes from calc version 2.13.0.1 to 2.13.0.1:

    Replaced /usr/local with the use of ${PREFIX} in calc Makefiles.

    The ${PREFIX} is not the same as ${T}.  The ${T} specifies
    a top level directory under which calc installs things.
    While usually ${T} is empty, it can be specific path
    as if calc where "chrooted" during an install.
    The ${PREFIX} value, during install, is a path between
    the top level ${T} install directory and the object
    such as an include file.

    Corrected a few more typos in Makefile comments.

    Added Makefile.local, a file with a single comment.  The main
    Makefile includes Makefile.local just before the first all rule.
    One may override any Makefile setting by modifying Makefile.local.
    For example, Makefile.local could force BLD_TYPE:

        HAVE_STRING_H:= YES
        HAVE_TIMES_H:= YES
        SED:= /usr/local/bin/nsed

    Added ${LOC_MKF} to specify the make of the file that is
    included just before the all file.  So one could place
    the above override lines into a different file and call
    make changing the ${LOC_MKF} value.  For example:

        make LOC_MKF=Makefile.private clobber all chk

    Updated HOWTO.INSTALL to mention Makefile.local.


The following are the changes from calc version 2.13.0.0 to 2.13.0.0:

    Fixed typo (missing quotes) in the env rule.

    Fixed indentation problem in CHANGES.

    Combined 2.12.9.1 changes into the 2.12.8.2 to 2.12.9.0
    range, and thus renamed the range to 2.12.8.2 to 2.12.9.1.

    Fixed issues related to building Makefile.simple.

    Fixed how the Makefile variable MANPATH is set for macOS.

    Added a bunch of information to the near bottom of HOWTO.INSTALL
    on calc Makefiles.  This information discusses the various
    Makefiles found in the calc source.

    Added comments in various calc Makefiles about their origin.
    In particular, for Makefiles that are constructed such as
    Makefile.simple, custom/Makefile and custom/Makefile.simple
    there are comments about how they were made.

    For all calc Makefiles, including those in sub-directories,
    near the top there is now a line of the form:

        # SRC: ... some message about the origin ...

    Fixed how the calc(1) man page is installed under macOS.

    Fixed how calc man page in ${CATDIR} is formed.

    Fixed how Makefile.simple is formed.

    Fixed the #! calc script argument processing.  The initial #!
    line must end in a -f.  For example, if calc is in /usr/local/bin/calc,
    then the following would be the first line of a calc script:

        #!/usr/local/bin/calc -f
        ...

    It is common that -q be used with a calc script, so assuming the
    same /usr/local/bin/calc path:

        #!/usr/local/bin/calc -q -f
        ...

    Use of -s in the #! first line of a calc script is not needed
    since -f implies -f.

    The argv() will now return values more typical of C's main().
    Before it returned one less than the number of arguments.  Now,
    for example, when calc is given 2 args, argv() will return 3.

    The value of argv(0) will be the path to calc, or in the
    case of a #! calc cscript, it will return the name of the script.

    Updated the calc man page and help/argv to reflect the
    above changes.

    Improved the formatting of the calc man page.

    Fixed the formation of the win32 sub-directory via the win32_hsrc
    Makefile rule.

    Due to incompatible changes to the argv() function, and #! calc
    scripts, we are setting the version to the next minor number:

        2.13.0.x

    Updated BUGS file as per v2.13.0 fixes.


The following are the changes from calc version 2.12.8.2 to 2.12.9.1:

    Added notes to help/unexpected about:

        display() will limit the number of digits printed after decimal point

        %d will format after the decimal point for non-integer numeric values

        %x will format as fractions for non-integer numeric values

        fprintf(fd, "%d\n", huge_value) may need fflush(fd) to finish

    Fixed Makefile dependencies for the args.h rule.

    Fixed Makefile cases where echo with -n is used.  On some systems,
    /bin/sh does not use -n, so we must call /bin/echo -n instead
    via the ${ECHON} Makefile variable.

    Add missing standard tools to sub-Makefiles to make them
    easier to invoke directly.

    Sort lists of standard tool Makefile variables and remove duplicates.

    Declare the SHELL at the top of Makefiles.

    Fixed the depend rule in the custom Makefile.

    Improved the messages produced by the depend in the Makefiles.

    Changed the UNUSED define in have_unused.h to be a macro with
    a parameter.  Changed all use of UNUSED in *.c to be UNUSED(x).

    Removed the need for HAVE_UNUSED in building the have_unused.h file.

    CCBAN is given to ${CC} in order to control if banned.h is in effect.

    The banned.h attempts to ban the use of certain dangerous functions
    that, if improperly used, could compromise the computational integrity
    if calculations.

    In the case of calc, we are motivated in part by the desire for calc
    to correctly calculate: even during extremely long calculations.

    If UNBAN is NOT defined, then calling certain functions
    will result in a call to a non-existent function (link error).

    While we do NOT encourage defining UNBAN, there may be
    a system / compiler environment where re-defining a
    function may lead to a fatal compiler complication.
    If that happens, consider compiling as:

        make clobber all chk CCBAN=-DUNBAN

    as see if this is a work-a-round.

    If YOU discover a need for the -DUNBAN work-a-round, PLEASE tell us!
    Please send us a bug report.  See the file:

        BUGS

    or the URL:

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

    for how to send us such a bug report.

    Added the building of have_ban_pragma.h, which will determine
    if "#pragma GCC poison func_name" is supported.  If it is not,
    or of HAVE_PRAGMA_GCC_POSION=-DHAVE_NO_PRAGMA_GCC_POSION, then
    banned.h will have no effect.

    Fixed building of the have_getpgid.h file.
    Fixed building of the have_getprid.h file.
    Fixed building of the have_getsid.h file.
    Fixed building of the have_gettime.h file.
    Fixed building of the have_strdup.h file.
    Fixed building of the have_ustat.h file.
    Fixed building of the have_rusage.h file.

    Added HAVE_NO_STRLCPY to control if we want to test if
    the system has a strlcpy() function.  This in turn produces
    the have_strlcpy.h file wherein the symbol HAVE_STRLCPY will
    be defined, or not depending if the system comes with a
    strlcpy() function.

    If the system does not have a strlcpy() function, we
    compile our own strlcpy() function.  See strl.c for details.

     Added HAVE_NO_STRLCAT to control if we want to test if
     the system has a strlcat() function.  This in turn produces
     the have_strlcat.h file wherein the symbol HAVE_STRLCAT will
     be defined, or not depending if the system comes with a
     strlcat() function.

     If the system does not have a strlcat() function, we
     compile our own strlcat() function.  See strl.c for details.

     Fixed places were <string.h>, using #ifdef HAVE_STRING_H
     for legacy systems that do not have that include file.

     Added ${H} Makefile symbol to control the announcement
     of forming and having formed hsrc related files.  By default
     H=@ (announce hsrc file formation) vs. H=@: to silence hsrc
     related file formation.

     Explicitly turn off quiet mode (set Makefile variable ${Q} to
     be empty) when building rpms.

     Improved and fixed the hsrc build process.

     Forming rpms is performed in verbose mode to assist debugging
     to the rpm build process.

     Compile custom code, if needed, after main code is compiled.

    Fixed a typo typo in help/Makefile that caused the build of
    2.12.9.0 to fail in a number of cases.  Thanks to a report by
    <GitHub user balducci>.

    Pass form Makefile variables ${Q}, ${S}, ${E}, ${H} and ${V} down
    to all sub-directory Makefiles from the top level Makefile.


The following are the changes from calc version 2.12.8.1 to 2.12.8.2:

    Fixed how the *.tar.bz2 are formed.  The calc-2.12.8.0.tar.bz2 file
    that was formed for calc version 2.12.8.0 was missing most files.

    Expanded 'make chk' to also verify that 'make distchk' and 'make
    distlist' execute successfully.  This will help check a regression
    of the bug that produced the bogus calc-2.12.8.0.tar.bz2 file.

    Added additional regression tests related 0^(zero_expression)==1.

    Calc can now correctly compile without CUSTOM being defined,
    thanks to a report by <GitHub user barsnick>.



The following are the changes from calc version 2.12.7.5 to 2.12.8.0:

    Fixed a mistake in "help intro" where some inserted text changed
    the value of "." and thus made the next result incorrect.

    Clarified in "help factor" that 1 is returned if no
    factor below the limit was found.

    Removed Makefile variable ${MAKEFILE_REV}.

    The missing cscript/square.calc file has been restored.

    Fixed compiler errors and warnings related to GCC.  In particular,
    gcc/9.3.1 and gcc/10.2.1 now compile calc without any compiler
    errors or warnings, even with -Werror -Wextra -pedantic.

    To print out information about the calc compilation
    environment, we added the following make rule:

        make calcinfo

    Improved how 'make debug' operates.

    Moved help/contrib to CONTRIB-CODE.  The help/contrib file
    is now build from a copy of CONTRIB-CODE.

    Created a new calc bug report Email address.  Created a new
    calc question Email address.  Created a new calc contribution
    Email address.  See the BUGS file for details.

    Added "help questions" to print the QUESTIONS help file.

    If the environment variable $CALCHELP is defined and is non-empty,
    then calc help files will be in the directory by the $CALCHISTFILE
    environment variable.

    If the environment variable $CALCCUSTOMHELP is defined and is
    non-empty, then custom calc help files will be in the directory
    by the $CALCCUSTOMHELP environment variable.

    Fixed a number of typos in text and in source code comments.

    The calc-tester mailing list has been retired.  See:

        * How to submit a calc bug report:

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

        * How to contribute code to calc:

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

        * How to submit a question about calc:

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


The following are the changes from calc version 2.12.7.1 to 2.12.7.5:

    Corrected CHANGES notes that were mixed up for TAB, VT, CR &
    NL.  The code in 2.12.7.0 is correct.  The CHANGE notes should
    have read:

        The following is a partial list of escape sequences recognized
        in strings and in printf formats:

            \a  audible bell    byte 0x07 in ASCII encoding
            \b  backspace       byte 0x08 in ASCII encoding
            \f  form feed       byte 0x0c in ASCII encoding
            \n  newline         byte 0x0a in ASCII encoding
            \r  return          byte 0x0d in ASCII encoding
            \t  tab             byte 0x09 in ASCII encoding
            \v  vertical tab    byte 0x0b in ASCII encoding

    Fixed a segfault when getpwuid() returned NULL during initialization.
    Thanks goes to baratharon GitHub user for reporting this issue.

    Requiring calc shell scripts to use -s -f at the end of the
    initial #! line.

    Fixed /tmp/mersenne example in calc(1) man page.

    Added make variable ${ARCH_CFLAGS}.  The ${ARCH_CFLAGS} is
    added after ${CCMISC} and before ${EXTRA_CFLAGS} when building
    the ${CFLAGS} for compiling C code.  are ${CC} when compiling
    C files.  The default value is:

        ARCH_CFLAGS= -march=native

    which directs C compiler to compile for the native machine.
    To disable use of '-march=native', set ARCH_CFLAGS to the empty
    string as in:

        make all ARCH_CFLAGS=

    To make calc RPMs more portable, they are compiled with an
    empty ARCH_CFLAGS.

    Fixed issues relating to compiling on macOS.  Fixed issues
    where <unistd.h> is needed.

    Fixed typos in help/intro and README.md. <<GitHub guilhermgonzaga>>

    Copied missing description lines from help/intro to README.md
    "What is calc?" section.  <<GitHub guilhermgonzaga>>

    GCC 7 added a warning on fall through in case statements.  It's
    enabled by -Wextra and treated as an error due to -Wall so it
    breaks compilation.  See -Wimplicit-fallthrough in the GCC
    manual.  The default value is 3, which means a comment matching
    some specific regexes is enough to disable the warning.
    Fixed spaces vs tabs and use FALLTHRU as it's used elsewhere.
    Fixed one FALLTHRU comment that was inconsistent with others.
    <<GitHub jcul>>

    Fixed minor typo on help/power. <<GitHub thegithubr>>

    By default, the calc history file is located in ~/.calc_history.
    Now, if the environment variable $CALCHISTFILE is defined
    and is non-empty, then calc history file will be defined
    by the $CALCHISTFILE environment variable.

    Calc as defined 0^0 as 1.  However in the past, 0 raised to
    an expression that evaluated to zero returned 1.  The result
    was that 0^0 was different than 0^(6-6) or even 0^(0).
    Now, calc will return 1 for 0^(0) and 0^zero when zero == 0.

    The missing cscript/square.calc file has been restored.


The following are the changes from calc version 2.12.6.10: to 2.12.7.0:

    Added a patch to replaces the manual search for include files
    in $(INCDIR) in the have_*.h targets with compiler invocations.
    Thanks goes to Helmut Grohne (helmut at subdivi dot de) who
    implemented the patch and posted it to the Debian bug tracker
    and Martin Buck (m at rtin-buck dor de) for forwarding it to us.

    The check_include make rule was fixed to not assume /usr/include.

    The qprintnum() function now takes outdigits as a 3rd argument.
    Most of the time, this 3rd argument is just conf->outdigits.
    But when it comes to the experimental '%g', this value can
    change.  This avoids having to modify conf->outdigits.

    Fixed a problem where gcc complains about E_FUNC not being defined
    for Linux systems as reported by Martin Buck (m at rtin-buck dor de).

    Updated the help files help/config, help/display, help/epsilon,
    help/fprint, help/printf, and help/strprintf to give more
    examples of how display digits and epsilon precision interact
    with displaying values.

    Added more information about %g in the help file help/printf.

    The '\a' is now recognized in a printf format string as the
    single byte audible bell character (byte 0x07 in ASCII encoding).

    The following is a partial list of escape sequences recognized
    in strings and in printf formats:

        \a      audible bell    byte 0x07 in ASCII encoding
        \b      backspace       byte 0x08 in ASCII encoding
        \f      form feed       byte 0x0c in ASCII encoding
        \n      newline         byte 0x0a in ASCII encoding
        \r      return          byte 0x0d in ASCII encoding
        \t      tab             byte 0x09 in ASCII encoding
        \v      vertical tab    byte 0x0b in ASCII encoding


The following are the changes from calc version 2.12.6.9 to 2.12.6.9:

    Fixed a number of core dump bugs related to the calculation of
    tan(), cot(), sec(), csc(), tanh(), coth(), sech(), and csch(),
    asin(), acos(), asinh(), acosh(), where when a call to an
    underlying function produced an invalid value.  Thanks goes to
    github user wuxiuheng for reporting this problem.

    A number of trigonometric and hyperbolic functions that incorrectly
    returned E_LOGINF, now return a new error code that is more
    specific to the trigonometric or hyperbolic function.  The
    following is a list of these new error codes: E_TAN3 E_TAN4
    E_COT3 E_COT4 E_SEC3 E_CSC3 E_TANH3 E_TANH4 E_COTH3 E_COTH4
    E_SECH3 E_CSCH3 E_ASIN3 E_ACOS3 E_ASINH3 E_ACOSH3 E_ATAN3 E_ACOT3
    E_ASEC3 E_ACSC3 E_ATANH3 E_ACOTH3 E_ASECH3 E_ACSCH3.

    Added regression tests 3729 thru 3732 to test E_TAN3, E_COT3,
    E_SEC3 and E_CSC3 respectively.

    Added experimental %g printf (and strprintf) format implementation
    based on pull request from github user 10110111.

    Made experimental changes to macOS builds to not require use of
    /usr/include.  The INCDIR for macOS uses:

        INCDIR= $(shell xcrun --show-sdk-path --sdk macosx)/usr/include

    to determine the upper path of the /usr/include directory for macOS.
    In some rare cases, the Darwin target seems to not automatically detected.
    If you are running under macOS, and that happens, you can force
    the target to be Darwin:

        # for macOS users only, force the target to be darwin
        #
        make target=Darwin clobber
        make target=Darwin all
        make target=Darwin chk
        make target=Darwin install


The following are the changes from calc version 2.12.6.6 to 2.12.6.8:

    For historical purposes, in lucas.cal, gen_v1(1, n) always returns 4.

    Fixed some compiler warnings, thanks to a report by Mike
    <michael dot d dot ince at gmail dot com>.

    Added work around for a gcc warning bug, thanks to a report by Mike
    <michael dot d dot ince at gmail dot com>.

    Fixed errors in various help files such as:

        mat randbit seed srandom types

    Removed the MAXSTRING symbol because it was no longer used by calc.

    Increased HIST_SIZE (depth of the history stack) from 10k to 32k.

    Increased TTYSIZE (reallocation size for terminal buffers) from 100 to 8191.

    Increased MAXDEPTH (maximum depth of input stack) from 10 to 255.

    Increased interactive input buffer size from 1024 to 256k.  This has the
    effect of increasing the maximum length of an input line from a tty.
    This helps with an interactive bug that was reported by Ruslan Kabatsayev
    (b7 dot 10110111 at gmail dot com).

    The calc man page indicates that -d also disables the printing of the
    leading tilde.

    Added information to "help command" about how to silence messages
    while reading calc resource files.

    Fixed an error message buffer overflow thanks to a report by
    Frank Peters <nlp at northernlightsphoto dot biz>.

    Replaced all use of the C function sprintf() with snprintf().
    Replaced all use of the C funcion vsprintf() with vsnprintf().
    Replaced all DONT_HAVE_VSPRINTF with DONT_HAVE_VSNPRINTF.
    Replaced all Makefile var ${HAVE_VSPRINTF} with ${HAVE_VSNPRINTF}.


The following are the changes from calc version 2.12.6.4 to 2.12.6.5:

    Fixed warning about undefined operations involving the qlink(q)
    macro by replacing that macro with an inline-function.  Thanks goes
    to David Haller <dnh at opensuse dot org> for this fix.

    NOTE for Windows 10 users: Pavel Nemec <pane at seznam dot cz>
    reported that calc version 2.12.6.4 has been successfully
    compiled, installed and running on Windows 10.  See README.WINDOWS
    for more details.


The following are the changes from calc version 2.12.6.1 to 2.12.6.3:

    Improved gen_v1(h,n) in lucas.cal to use an even faster search method.

    Improved are checking in lucas.cal.  In particular both h and n must be
    integers >= 1.  In the case of both rodseth_xhn(x, h, n) and gen_v1(h, n)
    h must be odd.

    Fixed an C code indenting issue that was reported by Thomas Walter
    <th dot walter42 at gmx dot de> in zfunc.c.

    Fixed a man page warning about ./myfile where the leading dot
    was mistook for an nroff macro.  Thanks goes to David Haller
    <dnh at opensuse dot org> for providing the patch.

    Improved gen_v1(h,n) in lucas.cal for cases where h is not a
    multiple of 3. Optimized the search for v(1) when h is a
    multiple of 3.

    Fixed a Makefile problem, reported by Doug Hays <doughays6 at gmail
    dot com>, where if a macOS user set BINDIR, LIBDIR, CALC_SHAREDIR
    or INCDIR in the top section, their values will be overwritten by
    the Darwin specific section.


The following are the changes from calc version 2.12.6.0 to 2.12.6.0:

    Added the makefile variable ${COMMON_ADD} that will add flags
    to all compile and link commands. The ${COMMON_ADD} flags are
    appended to both ${COMMON_CFLAGS} and ${COMMON_LDFLAGS}.  This
    facility is available to nearly all platforms except those with
    very old make commands that do not understand the += operator.

    Example on macOS (Darwin), one may invoke clang's -fsanitize
    facility by:

        make clobber all \
          COMMON_ADD='-fsanitize=undefined -fsanitize=address'

    Another example.  To force C warnings to be treated as errors:

        make COMMON_ADD='-Werror'

    Created a GitHub repository for calc:

        https://github.com/lcn2/calc

    NOTE: The calc GitHub repository represents the an active
          development stream.  While an effort will be made to keep
          the master branch of the calc GitHub repository in working
          order, that tree may be unstable.  Those wishing for more
          reliable releases use releases found at calc mirror sites:

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

    IMPORTANT NOTE:

        On 2017 June 05, the calc GitHub history was re-written.
        Anyone who was tracking the calc "pre-release" on GitHub prior
        to version 2.12.6.0 should do a:

            git reset --hard origin/master
            git cleanup -f

        Or you may just want to start over:

            rm -rf calc
            git clone https://github.com/lcn2/calc.git

        Sorry about that.  The previous GitHub repository was an useful
        experiment.  Based on what we learned, we decided to rebuild it.

    Renamed README to README.FIRST.  Added README.md for the
    GitHub repository.

    Fixed reading from standard input (stdin) when -p is given on
    the command line.  This now prints hello:

        echo hello | calc -p 'stdin = files(0); print fgetline(stdin);'

    Added more debugging related to stdin when bit 4 of calc_debug
    is set (e.g., running calc with -D16).

    Updated the calc(1) man page and 'help file' to explain about
    reading from standard input (stdin).

    Added some clarifying remarks for 'help ptest' explaining that
    the ptest builtin can return 1 is some cases where the test
    value is a pseudoprime.

    Removed duplicate copyright comments from the help/builtin that
    is built.

    Fixed a number of typos in the CHANGES file.

The following are the changes from calc version 2.12.5.4 to 2.12.5.6:

    Recompile to match current RHEL7.2 libc and friends.

    Added fix by Alexandre Fedotov <fedotov at mail dot desy dot de>
    to prepend ${T} in front of the CALCPATH path components
    ${CALC_SHAREDIR} and ${CUSTOMDIR}.  Add ${T} in front of ${HELPDIR}
    and ${CUSTONHELPDIR} when making conf.h.

    Improved the jacobi help page.

    Rewrote gen_v1() in the lucas.cal resource file using the method
    based on a paper:

        "A note on primality tests for N = h*2^n-1", by Oystein J. Rodseth,
        Department of Mathematics, University of Bergen, BIT Numerical
        Mathematics. 34 (3): pp 451-454.

        http://folk.uib.no/nmaoy/papers/luc.pdf

    The improved gen_v1() function is capable of returning a value
    for all valid values of h and n.  As a result, the trial tables
    used by gen_v1() have been changed to a short list of values
    to try, in order ot likelihood of success, before doing an
    exhaustive search for a v1 value to return.

    Removed lucas_tbl.cal calc resource file.  This file was made
    obsolete by the above rewrite of the lucas.cal resource file.
    This file will be removed from the local cal directory and
    from CALC_SHAREDIR during a 'make install', 'make clobber',
    and 'make uninstall'.

    Renamed gen_u0() to gen_u2() in lucas.cal.  Provided a gen_u0()
    stub function that calls gen_u2() for backward compatibility.

    The old gen_v1() method used by the Amdahl 6 group has been
    renamed legacy_gen_v1() in lucas.cal.  This function is no
    longer used by the lucas(h, n) function to test the primality of
    h*2^n-1.  It is preserved in lucas.cal for historical purposes.

    The 'make clobber' rule will attempt to remove all files that
    start with libcalc and start with libcustcalc.

    The 'man' command is now an alias for the 'help' command.

    Fixed extra /'s that were put into CALCPATH because of ${T}.
    Fixed extra /'s that were compiled into HELPDIR and CUSTOMHELPDIR.

    The fix in 2.12.5.4 to to prepend ${T} in front of the CALCPATH
    path components ${CALC_SHAREDIR} and ${CUSTOMDIR} broke the
    calc rpm build process.  The check-buildroot tool discovered
    that the BUILDROOT directory had been improperly put into various
    paths and binaries.  This has been fixed in 2.12.5.5.

    Fixed a crash that showed up on macOS (Darwin) that was reported
    by Richard Outerbridge <outer at interlog dot com> and
    fixed by Stuart Henderson <stu at spacehopper dot org>.
    Thanks goes to both!


The following are the changes from calc version 2.12.5.3 to 2.12.5.3:

    Calc version 2.12.5.2 for macOS (Darwin) users, code to installed
    calc under /opt/calc.  Moreover the CHANGES file did not mention
    /opt/calc.  Sorry about that!.

    A much better tree for macOS (Darwin) users would have been
    to install cal under /opt/calc.  This release ONLY changes the
    macOS (Darwin) install tree to /usr/local.

    macOS (Darwin) users who installed calc version 2.12.5.2
    should, after installing version 2.12.5.3:

        rm -rf /opt/calc


The following are the changes from calc version 2.12.5.1 to 2.12.5.2:

    NOTE: calc version 2.12.5.2, for macOS (Darwin) users,
          installed under /opt/calc.  We neglected to mention this
          AND /usr/local would have been a better choice.  Sorry!
          Fixed in calc version 2.12.5.3.

    Removed rules and makefile variables associated with shortened
    calc version numbers of less than 4 levels.

    Under OS X (Darwin), if /usr/include is missing, warnings
    are issued to help the user use xcode-select --install
    so that one may properly compile C code.

    Lowered REDC levels:

        #define MAXREDC 256     /* number of entries in REDC cache */

        #define SQ_ALG2 28      /* size for alternative squaring */
            config("sq2") == 28         /* was 3388 */
        #define MUL_ALG2 28     /* size for alternative multiply */
            config("mul2") == 28        /* was 1780 */
        #define POW_ALG2 20     /* size for using REDC for powers */
            config("pow2") == 20        /* was 176 */
        #define REDC_ALG2 25    /* size for using alternative REDC */
            config("redc2") == 25       /* was 220 */

    The alg_config.cal script appears to be not correctly finding the
    best REDC values.  While it has been improved, alg_config.cal still
    seems to be suspect on how it attempts to find the best values.

    Fixed an intro help file mistake found by Roger Hardiman
    <roger at rjh dot org dot uk>.


The following are the changes from calc version 2.12.5.0 to 2.12.5.1:

    There is a new calc bug report Email address:

NOTE:       calc-bug-report Email address no longer in use

        This replaces the old calc-bugs Email address.

        To be sure we see your Email reporting a calc bug, please use the
        following phase in your Email Subject line:

            calc bug report

        That phrase in your subject line will help ensure your
        request will get past our anti-spam filters.  You may have
        additional words in your subject line.

        However, you may find it more helpful to simply subscribe
        to the calc-tester mailing list (see above) and then to
        send your report to that mailing list as a wider set calc
        testers may be able to help you.

    The following makefile rules that were related to printing the
    upper values of the calc version, rules that were made obsolete
    in calc version 2.12.4.14, have been removed:

        calc_vers calc_ver calc_ve
        vers ver ve

    Noted that the hash() builtin function, internally known as
    quickhash (used for internal objects such as the associative
    arrays as well as other internal processes) uses the deprecated
    32-bit FNV-0 hash.  The use of this deprecated hash is sufficient
    for calc internal purposes.  Use of FNV-1a is recommended for
    a general non-cryptographic quick hash.


The following are the changes from calc version 2.12.4.14 to 2.12.5.0:

    For Apple OS X / Darwin target:

        MACOSX_DEPLOYMENT_TARGET is no longer defined
        using clang compiler

        By default, -install-name is used when forming shared libs.
        To force -install-name to not be used, set SET_INSTALL_NAME=no.

    The have_stdvs.c test uses <stdlib.h> and fixed va_start() test call
    that didn't use last arg.

    Fixed math_fmt (printf) in value.c where a LEN (SB32) be printed as %d.

    Fixed a significant bug where that resulted in an incorrect
    complex number comparison.  Thanks goes to David Binderman
    <dcb314 at hotmail dot com> for identifying the subtle typo!

    Make minor fixes to the make depend rule.

    Fixed places were calc defined a reserved identifier that
    begin with either __ or _[A-Z].  For example, __FILE_H__ has
    been replaced with INCLUDE_FILE_H.

    Fixed the addall3 example in the script help file.  Thanks for this
    fix goes to Igor Furlan <igor dot furlan at gmail dot com>.

    We made important fixes to the calc command line history:

        Fixed a bug in the command line history where calc would sometimes
        crash.  There was code that used memcpy() instead of memmove()
        that could corrupt the command line history when entering a
        into into history that was similar to a previous entry.  Thanks
        goes to Einar Lielmanis <einars at spicausis dot lv> for first
        identifying this mistake.

        The calc command line history code, in general was not robust.
        We made use a patch from Mathias Buhr <napcode at users dot sf
        dot net>, that while it uses a bit more memory: is much more
        flexible, readable and robust.  This patch replaced the improper
        use of memcpy() (see above) with better code.  Thanks!

    The alg_config.cal calc resource file has been reworked to produce
    better diagnostics while attempting to determine the ideal values
    for mul2, sq2, and pow2.  However, it has been shown that this
    code is not correct.  Suggestions for a replacement are welcome!

        calc -u 'read alg_config; config("user_debug", 2),; best_mul2();'
        calc -u 'read alg_config; config("user_debug", 2),; best_sq2();'
        calc -u 'read alg_config; config("user_debug", 2),; best_pow2();'

    Fixed a number of pedantic compiler warnings.

    Removed -W and -Wno-comment from the the CCWARN makefile variable.

    Removed no_implicit.arg makefile rule.  Removed HAVE_NO_IMPLICIT
    makefile variable.  Removed no_implicit.c source file.

    Added WNO_IMPLICT makefile variable to hold the compiler flag
    -Wno-implicit for use on selective compile lines.

    Added WNO_ERROR_LONG_LONG makefile variable to hold the compiler flag
    -Wno-error=long-long for use on selective compile lines.

    Added WNO_LONG_LONG makefile variable to hold the compiler flag
    -Wno-long-long for use on selective compile lines.

    The makefile variable ${MKDIR_ARG} has been replaced with just -p.

    Minor fixes were made to the calc.spec.in file.

    The target rpm architecture changed from i686 to x86_64.  For those
    who do not run machine with x86_64, we continue to release a src
    rpm. For those without the ability to process an rpm, we will always
    to release src tarball.

    When building the libcalc and libcustcalc shared  libraries,
    ONLY the .so and .so.${VERSION} files are created.  The .so is
    a symlink to the .so.${VERSION} file.  Here ${VERSION} is the
    full "w.x.y.z" calc version.


The following are the changes from calc version 2.12.4.11 to 2.12.4.13:

    Fixed many typos in comments of the Makefile thanks to the review
    work of Michael Somos.

    Fixed typo in "help sysinfo".

    The Makefile rule, debug, is now more verbose and prints more information
    about the calc compiled constants.

    Added a more of calc resource files by
    Christoph Zurnieden <czurnieden at gmx dot de> including:

    infinities.cal - handle infinities symbolically, a little helper file
    intnum.cal - implementation of tanh sinh and Gauss-Legendre quadrature
    smallfactors.cal - find the factors of a number < 2^32
    strings.cal - implementation of isascii() and isblank()

    Reformatted some calc resource files.  Cleanup in comment the headers
    of some calc resource files.

    Minor formatting changes to a few help files.

    No need to be special picky about the test8900.cal calc resource file.

    Added a number of ctype-like builtins:

    isalnum - whether character is alpha-numeric
    isalpha - whether character is alphabetic
    iscntrl - whether character is a control character
    isdigit - whether character is a digit character
    isgraph - whether character is a graphical character
    islower - whether character is lower case
    isprint - whether character is a printable
    ispunct - whether character is a punctuation
    isspace - whether character is a space character
    isupper - whether character is upper case
    isxdigit - whether character a hexadecimal digit
    strcasecmp - compare two strings, case independent
    strncasecmp - compare two strings up to n characters, case independent
    strtolower - transform an ASCII string to lower case
    strtoupper - transform an ASCII string to upper case

    For details on these new builtins, see their help messages.
    Thanks goes to Inge Zurnieden <inge dot zurnieden at gmx dot de> for
    these new builtins.

    Calc source code is now picky v2.3 clean using:

        picky -s -v file file2 ..

    With the exception of:

        help/errorcodes.sed
        cal/set8700.line

    Due to the long lines in those files, we use:

        picky -w -s -v help/errorcodes.sed cal/set8700.line

    For more information about the picky tool, see:

        http://cis.csuohio.edu/~somos/picky.html

    Removed functions from strings.cal that have been replaced by
    the new ctype-like builtin functions.

    Fixed cal/Makefile to include missing intnum.cal file.

    Added detail_help_list make target to cal/Makefile.

    The detaillist make target in help/Makefile is now
    called detail_help_list.

    Removed requirement of gen_u0(h, n, v1) in lucas.cal that h
    be odd.  While still lucas(h, n) converts even h into an odd h
    internally by incrementing n, gen_u0(h, n, v1) will output even
    when h is even.


The following are the changes from calc version 2.12.4.6 to version 2.12.4.10:

    Updated RPM build process to remove use of deprecated flags.

    Applied a number of fixes to calc.spec and rpm.mk file.
    See calc.spec.in for details.  Changed rpm release to 2.1.

    Set MACOSX_DEPLOYMENT_TARGET=10.8 as we upgraded all of
    our development Mac OS X to 10.8.

    Libraries are chmod-ed as 0644 to allow for building rpms
    without root.

    Silenced annoying warning about unused variable 'intp'
    while compiling endian.c under some circumstances.

    Fixed typo in re-declaration warnings.  Thanks to
    Christoph Zurnieden <czurnieden at gmx dot de> for this report.

    Added a number of calc resource files by
    Christoph Zurnieden <czurnieden at gmx dot de> including:

    bernpoly.cal - Computes the nth Bernoulli polynomial at z for any n,z
    brentsolve.cal - root-finder implemented with the Brent-Dekker trick
    factorial.cal - product of the positive integers
    factorial2.cal - variety of integer functions quasi-related to factorial
    lambertw.cal - Computes Lambert's W-function at "z" at branch "branch"
    lnseries.cal - Calculates a series of natural logarithms at 1,2,3,4...n
    specialfunctions.cal - Calculates the value of the beta function
    statistics.cal - a wide variety of statistical functions
    toomcook.cal - Multiply by way of the Toom-Cook algorithm
    zeta2.cal - Calculate the value of the Hurwitz Zeta function

    Fixed a makefile bug that prevented the those new calc resource
    files from being installed.

    Improved the formatting of the output from:

        help resource

    We replaced COPYING-LGPL with the version that is found at
    http://www.gnu.org/licenses/lgpl-2.1.txt because that version
    contains some whitespace formatting cleanup.  Otherwise the
    license is the same.

    We fixed a number of places where "the the" was used
    when just "the" should be used.

        NOTE: Fixes to grammar, spelling and minor formatting
              problems are welcome.  Please send us your patches!

    With the exception of 3 source files, we became "picky" about
    line lengths and other issues reported by the picky tool:

        cal/test8900.cal
        cal/set8700.line
        help/errorcodes.sed

    The above 3 files now pass picky -w (OK except for line length).
    For more information about the picky tool, see:

        http://cis.csuohio.edu/~somos/picky.html


The following are the changes from calc version 2.12.4.3 to 2.12.4.5:

    Added gvec.cal resource script.

    Added calc-symlink make rule to setup symlinks from standard locations
    into a tree specified by a non-empty ${T} makefile variable.  Added
    calc-unsymlink to remove any symlinks that may have been created by
    the calc-symlink rule.

    If is OK for the calc-symlink make rule to pre-remove a symlink.

    Fixed bug was uncovered in calc that caused script failures when calc
    is called within a while loop in BASH if the while loop is fed from
    stdin due to calc's redirection/inheritance of stdin and no option
    to change this behavior.  Thanks gores to David C. Rankin
    <drankinatty at gmail dot com> for the bug fix and to David Haller
    <dnh at opensuse dot org> for helping debug this problem.


The following are the changes from calc version 2.12.4.0 to 2.12.4.2:

    Fixed a documentation bug for the sgn() builtin.

    Added the 1<<8/2 evaluation example to "help unexpected".  That
    expression evaluates to 128, not 16 as some C programmers might expect.

    Fixed a bug in solve.cal where high was not returned in some situations.

    Fixed a bug reported by Paul & Karen Tomlinson (paulnkaz at pktomlinson
    dot fsnet dot co dot uk) where calling log multiple times with different
    values of epsilon resulted in an incorrect value.

    Removed cvd rule from Makefiles.

    The Makefile used in the source rpm (calc-*.src.rpm) no longer uses
    the -Werror compile flag.  This is to help those distributions with
    compilers that make produce (hopefully) compilation warnings.
    NOTE: For testing and calc build purposes will recommend and will
    continue to use the -Werror flag.

    Fixed a typo in the Makefile where the make variable ${SAMPLE_OBJ}
    was misspelled as ${SAMPLE_OBJS}.

    Added prep makefile rule to make is easier to compile calc without
    an optimizer.  By doing:

        make clobber prep

    one may build a calc binary that is easier to debug.

    Fixed a bug where an certain typos (e.g., calling an unknown
    function) would previously cause calc to exit.

    Updated the COPYING file to reflect the new filenames associated
    with the SHA1 hash function, and removed mention of files related
    to the SHA (SHA0, not SHA1) and the MD5 hash functions (which is
    no longer supported in calc).

    Fixed a bug where a calling vsnprintf() twice created problems.
    The thanks for this fix goes to Matthew Miller (mattdm at mattdm
    dot org) for this patch.

    Michael Penk (mpenk at wuska dot com) reported success in installs
    under Windows via Cygwin by making a change to the Cygwin target.
    These changes have been folded into the main calc Makefile.
    The old recommendation of using 'make win32_hsrc' is no longer
    required for Cygwin.  See the README.WINDOWS file for details.

    Added dms.cal and hms.cal resource files.  The dms.cal is a more
    functional version of deg.cal.  It is a superset except that increment
    and decrement is on the arc second level.  The hms.cal is for
    24-hour cycle instead of the 360 degree cycle of dms.cal.

    Changed deg.cal object name from dms to deg so that the more functional
    dms.cal can own the dms object name.

    Updated 'help obj' to reflect changes to 'show objfunctions' and
    resource file example list since 1999.

    Fixed problem where CALC_BYTE_ORDER referring to CALC_BIG_ENDIAN
    and CALC_LITTLE_ENDIAN instead of BIG_ENDIAN and LITTLE_ENDIAN.


The following are the changes from calc version 2.12.3.0 to 2.12.3.3:

    Fixed the Jacobi function where it returned 1 when it should have
    returned 0.  Thanks goes to Kevin Sopp (baraclese at googlemail dot com)
    for discovering the problem and suggesting the nature if the fix.

    Calc versions will always be of the form x.y.z.w even when the
    MINOR_PATCH (w) is 0.  Thus, 2.12.3.0 will be printed as 2.12.3.0
    instead of just 2.12.3.

    Added MINGW32_NT-5.0 compile target based on a patch from
    Brian L. Angus (angus at eng dot utah dot edu).

    Removed the use of rpm.release in the Makefile.

    Mac OS Darwin targets no longer attempt to use ldconfig.  Under the
    Darwin target, the LDCONFIG make variable is redefined to be
    an empty value.  Thanks goes to Ralf Trinler (art at infra dot de)
    for reporting this problem.

    The ${CALC_INCDIR}/custom is no longer being removed at install time
    if it is empty.  Now when ${ALLOW_CUSTOM} make variable is empty,
    an empty ${CALC_INCDIR}/custom may be left behind.

    Fixed a problem where a "make clobber" would remove custom/Makefile
    and fail to rebuilt it.


The following are the changes from calc version 2.12.2.3 to 2.12.2.4:

    Added OpenBSD target.

    Using the -r test instead of the -e test in Makefiles because some
    out of date shells still do not have the -e test.

    The Makefile now avoids the use of if ! command because some out of
    date shells to not support the ! construct.


The following are the changes from calc version 2.12.1.1 to 2.12.2.2:

    Added an explicit Solaris target.

    Fixed confusion in Makefile where some uses of ${EXT} were misnamed ${EXE}.

    Added a "make strip" rule, per suggestion from Igor Furlan <primorec
    at sbcglobal dot net>, to allow one to strip previously built binary
    executables and libraries.

    Under the Darwin / OS X target, ${DARWIN_ARCH} is left empty meaning
    that calc is compiled for the native CPU type instead of Universal
    Binary (Intel and PPC).

    By default, the calc binary that is built for the rpm forces
    ${LD_SHARE} to be empty.  An empty ${LD_SHARE} means that the calc
    from the rpm does not set rpath.  This in turn causes the default
    system path to be searched when looking for libcalc and libcustcalc.

    The Makefile shipped with calc still sets ${LD_SHARE} for host targets.
    By default, the dynamic shared library search path for all targets
    starts with the source directory.  Starting the search in the source
    directory is convenient for testing and debugging but is not appropriate
    for installation on a production system.  To get the same effect
    as the calc binary in the calc rpm, try:

        make clobber
        make calc-dynamic-only BLD_TYPE=calc-dynamic-only LD_SHARE=
        make install

    The libcalc and libcustcalc shared libraries are now tied to
    the 4 level calc version instead of just 3 levels.  For example,
    under Linux calc version 2.12.2.1 uses /usr/lib/libcalc.so.2.12.2.1
    instead of just the /usr/lib/libcalc.so.2.12.2 file.  This change
    was made so that calc produced by 'make clobber; make all install'
    is consistent with the calc rpm.

    Calc is now releasing the calc-debuginfo rpm for those RPM users who
    which to use non-stripped libraries and binaries for debugging
    purposes.  By default, the calc rpm installed stripped binaries
    and libraries.

    Added this high priority item to the calc help/todo list:

        It is overkill to have nearly everything wind up in libcalc.
        Form a libcalcmath and a libcalclang so that an application
        that just wants to link with the calc math libs can use them
        without dragging in all of the other calc language, I/O,
        and builtin functions.

    Fixed the wording for the -i flag in the calc man page.

    Added some notes to the help/unexpected file regarding calc
    and interactive shells.

    Fixed bug where a FILEPOS was copied FPOS_POS_BITS octets instead of
    FPOS_POS_LEN octets.

    Split out ${READLINE_EXTRAS} Makefile variables from ${READLINE_LIB}
    to better deal with Fedora rpm requirements.

    Bit 8 (0x80) of calc_debug is reserved for custom debugging.
    See help/config and custom/HOW_TO_ADD for details.

    When the Makefile variable ${ALLOW_CUSTOM} is not defined or empty,
    the libcustcalc library is not built or linked against, certain make
    rules skip going into the custom sub-directory, the install
    rule skips certain custom installation actions, and the common
    C flags (${COMMON_CFLAGS}) is given -UCUSTOM.  Other make rules such
    as "make clean" and "make clobber" still work as before.  Also
    the Makefile.simple assumes that the Makefile variable ${ALLOW_CUSTOM}
    is -DCUSTOM.

    Clarified that the calc builtin functions rand() and random()
    operate over a half closed interval.  The help/rand and help/random
    refer to  the top of the interval as "beyond" instead of "max".

    Releasing source tar balls using bzip2 instead of with gzip.  So
    what was calc-something.tar.gz is now calc-something.tar.bz2.
    To "uncompress" use:

        bunzip2 calc-something.tar.bz2

    On some systems, one may untar directly by:

        tar -jxvf calc-something.tar.bz2

   The Makefile variable ${BYTE_ORDER} was replaced by ${CALC_BYTE_ORDER}.

   Changed the way the Makefile can force the calc byte order.  If you set
   the Makefile variable ${CALC_BYTE_ORDER} to be -DCALC_BIG_ENDIAN then
   endian.h will force the CPP symbol CALC_BYTE_ORDER to be BIG_ENDIAN.
   If you set ${CALC_BYTE_ORDER} to be -DCALC_LITTLE_ENDIAN then endian.h
   will force the CPP symbol CALC_BYTE_ORDER to be LITTLE_ENDIAN.
   If the Makefile variable ${CALC_BYTE_ORDER} is empty, then the CPP
   symbol CALC_BYTE_ORDER will set to the CPP symbol BYTE_ORDER as
   defined by some system include file (if the Makefile can find such
   an include file), or the Makefile compiling endian.c and hopefully
   using that result to set CPP symbol CALC_BYTE_ORDER.  Regardless of
   how it happens, the CPP symbol CALC_BYTE_ORDER should end up set in
   endian_calc.h include file.


The following are the changes from calc version 2.12.1.10 to 2.12.2:

    Put back the missing -s flags on the cscripts:  mersenne, 4dsphere,
    fprodcut, plus, and powerterm.  Thanks goes to Bradley Reed
    <bradreed1 at gmail dot com> for discovering this problem.

    All static variables are now declared with the symbol STATIC.
    All extern variables are now declared with the symbol EXTERN.
    All static functions are now declared with the symbol S_FUNC.
    All extern functions are now declared with the symbol E_FUNC.
    The include file decl.h defines these 4 symbols by default
    to static, extern, static, and extern respectively.  Under
    Windows, DLL is also defined according to the _EXPORTING symbol
    and is prepended to the EXTERN and E_FUNC symbols.  The decl.h
    file has replaced the win32dll.h file.

    When WITH_TLS is defined, calc attempts to compile with Thread Local
    Storage.  As of version 2.12.1.12 this mode is extremely experimental.
    Calc may not compile when WITH_TLS defined.

    Fixed E_FUNC vs EXTERN issues discovered by Mirko Viviani
    <mirko at objectlab dot org>.

    Removed include of <malloc.h>.  The building of the include file
    "have_malloc.h" has been removed from the Makefile.  One some
    systems such as FreeBSD, the file /usr/include/malloc.h exists
    and contains an forced error saying that stdlib.h should be used
    instead.  The Makefile symbol HAVE_MALLOC has been removed.

    Moved the sample code in the sample sub-directory up into the
    main source level.  The sample/many_random.c source file is
    now sample_many.c.  The sample/test_random.c source file is now
    sample_rand.c.  The sample Makefile and the sub-directory is no more.

    Renamed the following source files:

        math_error.h            ==>    lib_calc.h
        string.c                ==>    str.c
        string.h                ==>    str.h

    Renamed the following variables related to calc error processing:

        int calc_jmp            ==>    int calc_use_matherr_jmpbuf
        jmp_buf calc_jmp_buf    ==>    jmp_buf calc_matherr_jmpbuf

        int post_init           ==>    int calc_use_scanerr_jmpbuf
        jmp_buf jmpbuf          ==>    jmpbuf calc_scanerr_jmpbuf

        char *calc_error        ==>    char calc_err_msg[MAXERROR+1]

    These values are now declared in the lib_calc.h include file.
    The value MAXERROR is now defined in lib_calc.h instead of calc.h.
    The calc_err_msg[] buffer is now used for math errors as well
    as scan and parse errors.

    Parse/scan errors will not be printed if calc_print_scanerr_msg
    is zero.  By default:

        int calc_print_scanerr_msg = 1;

    This variable is declared in the lib_calc.h include file.  Storage
    comes from libcalc.

    Parse/scan warnings will not be printed if calc_print_scanwarn_msg
    is zero.  By default:

        int calc_print_scanwarn_msg = 1;

    This variable is declared in the lib_calc.h include file.  Storage
    comes from libcalc.

    The last parse/scan error message is stored in the calc_err_msg[]
    buffer.  This happens even when calc_print_scanerr_msg is zero.

    The last parse/scan warning message is stored in the calc_warn_msg[]
    buffer.  After each parse/scan warning condition is detected,
    the value calc_warn_cnt is incremented.  This happens even when
    calc_print_scanwarn_msg is zero.

    The calc_warn_msg[] buffer and calc_warn_cnt variables are declared
    in the lib_calc.h include file.  Storage comes from libcalc.

    See the file, LIBRARY or use the calc command "help libcalc" for
    more information on calc error processing.  This file has been
    updated to reflect the changes noted above in this section.

    The make install rule removes std_arg.h, have_malloc.h, math_error.h,
    string.h, and win32dll.h from ${INCDIR} if they exist.  These calc
    include files are no longer supported.

    Do reduce the number of special case .o build rules, the
    ${ALLOW_CUSTOM} make flag is added to ${CFLAGS} by default.  This means
    that if ALLOW_CUSTOM= -DCUSTOM, then -DCUSTOM is given to the compile
    line of most .c files.

    Calc -v reports "w/custom functions" or "w/o custom functions" on
    the version string depending on if calc was compiled with the
    ALLOW_CUSTOM= -DCUSTOM or not.

    Replaced the concept of compiler sets in the Makefile with
    host target section in the Makefile.  Initial host targets are:

        Linux
        Darwin
        FreeBSD
        (default)       <<== Target does not match any previous target name
        Simple

        NOTE: If your target is not supported below and the default target
              is not suitable for your needs, please send to the:

NOTE:           calc-contrib Email address no longer in use

              Email address an "ifeq ($(target),YOUR_TARGET_NAME)"
              ... "endif" set of lines from the Makefile so that
              we can consider them for the next release.

    The custom/Makefile is now constructed from 3 parts: custom/Makefile.head,
    the host target section in Makefile, and the custom/Makefile.tail.

    The top level Makefile and the custom/Makefile require a GNU make
    (such as gmake) or an equivalently advanced make.  On many targets,
    the default make is sufficient.  On FreeBSD for example, one must
    use gmake instead of make.

    If your target system does not have GNU make (or equivalent), then
    you should try using the Makefile.simple and custom/Makefile.simple
    files:

        mv Makefile Makefile.gmake
        cp Makefile.simple Makefile
        mv custom/Makefile custom/Makefile.gmake
        cp custom/Makefile.simple custom/Makefile
        make all

    Added the ability to build calc with dynamic libraries, static
    libraries or both.  Many thanks goes to Matthew Miller (mattdm
    at mattdm dot org) and Mirko Viviani (mirko at objectlab dot
    org) for this help, encouragement, and testing of this major change!

    Added BLD_TYPE Makefile variable to control how calc is
    built.  The BLD_TYPE value may be one of:

        BLD_TYPE= calc-dynamic-only
        BLD_TYPE= calc-static-only

    Each host target establishes a default BLD_TYPE value.  Of course
    one can override the host target BLD_TYPE on the make command line:

        make clobber
        make calc-dynamic-only BLD_TYPE=calc-dynamic-only

        make clobber
        make calc-static-only BLD_TYPE=calc-static-only

        NOTE: It is a very good idea to first clobber (remove) any previously
              built .o, libs and executables before switching the build
              between static and dynamic.

    which have the same effect as make all with a given build phase set.

    For Linux and Darwin, the default BLD_TYPE is calc-dynamic-only.
    For the simple case, BLD_TYPE is calc-static-only.  For the
    default target (the target does not match any of the previous
    defined targets), BLD_TYPE is calc-static-only.

    Added ${CSFLAGS} make variable to hold the {$CC} flags for compiling
    without shared library.  By default, ${CFLAGS} is ${CSFLAGS} with
    ${CC_SHARE} added to it.

    Added ${CC_SHARE}, ${LIBCALC_SHLIB}, ${LIBCUSTCALC_SHLIB}, and
    ${LD_SHARE} to the remaining compiler sets.

    Fixed make depend and make uninstall rules.   Performed various
    makefile syntax cleanups.

    Removed ${PROGS} and ${STATIC_PROGS} Makefile variables due to
    the new BLD_TYPE system (see above).

    Added missing help for cp, calcpath, and stoponerror.

    Noted that calc fails the regression test (and will crash at
    various times) when compiled with gcc v4.1.0.  This problem was
    first reported under Fedora Core 5 by Christian Siebert.

    Set the LESSCHARSET to iso8859 so that less will not confuse or
    upset the col utility with Invalid or incomplete multi-byte or wide
    characters.

    Updated the Free Software Foundation postal address and updated
    the COPYING-LGPL from http://www.fsf.org/licensing/licenses/lgpl.txt
    on 2007-Mar-14.  Calc is using the same Version 2.1 of the LGPL,
    only the postal address of the Free Software Foundation has
    been updated.  All source files were updated to RCS level 30.
    Thanks goes to Martin Buck (m at rtin-buck dor de) for this patch.

    Added printf arg checking for GNU C compilers that helps check
    printf-style functions in calc.  Thanks goes to Martin Buck (m at
    rtin-buck dor de) for this patch.

    Fixed issues where the argument of a printf-like did not match the
    format type.

    Removed build function md5().  The MD5 hash has been compromised to
    such a degree that is it no longer advisable to use this function.

    Removed build function sha().  The SHA hash has been compromised to
    such a degree that is it no longer advisable to use this function.
    Note that the SHA-1 hash has not been compromised to the same degree
    and so this hash function remains.

    Renamed shs1.c to sha1.c.  Renamed shs1.h to sha1.h.

    Added custom registers.  The custom register function:

        custom("register", 3)

    returns the value of custom register 3.  Custom registers, initialized
    with 0, may take on any calc value:

        custom("register", regnum, value)

    Added REGNUM_MAX to the sysinfo custom function to return the maximum
    register number:

        custom("sysinfo", "REGNUM_MAX")

    which defaults to 31.  The first custom register is 0 and thus the
    default number of custom registers is 32.

    Added E_OK #define in calc.h to indicate no error (0).

    Renamed C function powivalue() in value.c to powvalue() because it
    now handles raising NUMBER or COMPLEX to a NUMBER or COMPLEX power.

    The powervalue() function in value.c may be given a NULL epsilon
    which will cause to the builtin epsilon value to be used.

    Calc supports both real and complex exponentiation bases and exponents.
    For a ^ b and a ** b, "a" and "b" can be a real value or a complex value:

        2^3                     3i^4
        2.5 ^ 3.5               0.5i ^ 0.25
        2.5 ^ 2.718i            3.13145i ^ 0.30103i

    Fixed typos in the calc man page thanks to a Debian bug report
    by A. Costa <agcosta at gis dot .net> that was kindly forwarded
    to us by Martin Buck <m at rtin-buck dot de>.


The following are the changes from calc version 2.12.1.8 to 2.12.1.9:

    Fixed calc cscripts that contained comments that were not valid calc
    comments.  Improved calc comment documentation in "help unexpected"
    to help other avoid similar mistakes.  Calc comments are of the form:

        /* c style comments */
        /*
         * multi-line
         * comments
         */
        ## two or more #-signs
        ### in a row
        ### Note that # along is a calc unary and binary operator

    Added "help pound" or "help #' to document the # operator, comments,
    and the first line of cscript files.

    Documented these help commands in "help help":

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

    The usage help file is now formed from the contents of the calc man page.
    So "help usage" prints the version of the calc man page.  Added ${COL}
    makefile symbol to support the formation of the calc.usage file from
    calc.1 via the CALCPAGER (less) or NROFF (if NROFF is non-empty).

    The "help calc" command is now equivalent to "help help".

    The "help define" command is now equivalent to "help command".

    Fixed calc command line usage message.

    Fixed missing README.src file in RPM src and tgz src tarball.

    Removed HAVE_SNPRINTF test in version.c.  We now assume that
    all systems come with the standard snprintf() library function.

    Make does not assume that DONT_HAVE_VSPRINTF must be defined in
    order to test for varargs (via have_varvs.c).  Instead it uses the
    ${HAVE_VSPRINTF} to determine if the vsprintf() and vsnprintf()
    should be tested to assumed to exist or not exist.

    Tests for the existence of vsprintf() now also require the existence
    of vsnprintf().  Test for the existence of vsnprintf() now also
    require the existence of vsprintf().

    The #define CALC_SIZE_T was never used except when memmove() was
    not found.  This symbol was renamed to MEMMOVE_SIZE_T.  Calc
    requires that size_t must be a known type.

    Calc and cscripts are installed mode 0755 instead of 0555 to
    make rpmlint happy.

    Make clobber cleanup as suggested by Martin Buck <m at rtin-buck dot de>.
    The clobber rule now depends on the clean rule.


The following are the changes from calc version 2.12.1.6 to 2.12.1.7:

    Added the calc builtin function, usertime(), to return the amount of
    user CPU time used by the current process.  Unlike the old runtime()
    builtin, the CPU time reported for long running processes will not
    wrap around to 0 after only a few months.

    Added the calc built0in function, systime(), to return the amount of
    kernel CPU time used by the current process.

    The runtime() builtin function now returns the total amount of CPU
    time used by the current process.  This time includes both user mode
    and kernel mode time.  Unlike the old runtime() builtin, the builtin
    includes time spent executing operating system code on behalf of
    the current process.

    Fixed runtime() so that the CPU time reported for long running
    processes will wrap around to 0 for a long time.

    Added config("hz") to return the clock tick rate.  This is
    a read-only configuration value.

    Added regression tests for recently added config() parameters.

    Fixed the #define symbols that were created in have_strdup.h.
    Previously this file looked as if have_rusage.h has been
    included already.

    Restored the function of "help" (without any args) printing the
    default help file.  Thanks for this fix goes to Silvan Minghetti
    <bullet at users dot sourceforge dot net>.

    Fixed a problem where some old MS environments failed some of the
    regression tests because "read -once foo.cal" was not behaving
    correctly due to how the _fullpath() was being called.  Thanks for
    this fix goes to Anatoly <notexistent-anb at yandex dot ru>.

    Documented the mis-feature about how calc parses if, for, while
    and do statements in an unexpected way.   For example:

        This works as expected:

            if (expr) {
                ...
            }

        However this WILL NOT WORK AS EXPECTED:

            if (expr)
            {
                ...
            }

        because calc will parse the if being terminated by
        an empty statement followed by a

            if (expr) ;
            {
                ...
            }

    See also "help statement", "help unexpected", "help todo", and
    "help bugs".


The following are the changes from calc version 2.12.1 to 2.12.1.5:

    Fixed minor typos in the 'version 2.12.0 to 2.12.0.8' section below.
    Made minor formatting changes as well.

    Changed use of ${Q} in the Makefile to avoid an make "feature"
    related to OpenBSD.  Added ${RM} make variable for make tools that
    do not have builtin defined terms.

    Removed the ECHO_PROG Makefile variable.  Also removed it from
    the sysinfo() custom function.

    Improved the support for cross-compiled environments by using
    make symbols for all non-shell commands executed by Makefiles.

    Fixed a problem with the make chk awk script which failed under
    OS X 10.4.7.

    Fixed a few minor variables that were not set to default values in
    lower level Makefiles.

    Fixed a reference to a non-existent make variable in HOWTO.INSTALL.


The following are the changes from calc version 2.12.0 to 2.12.0.8:

    Fixed ellip.cal to deal with a calc syntax change that happened
    many ages ago but was never applied to this file until now.
    This bug was fixed by Ernest Bowen <ebowen at une dot edu dot au>.

    Fixed a problem where comments using # followed by a !, newline or
    another # works.  This bug was fixed by Ernest Bowen <ebowen at une
    dot edu dot au>.

    The show builtins display for functions with long descriptions
    is now broken into multi-line descriptions.

    The str functions, such as strcpy(s1, s2), will now copy as many
    characters as possible from s2 to s1, treating '\0' like any other
    character until the end of s2 is reached. If s2 is shorter than s1,
    a '\0' is inserted.

    The strcmp(s1, s2) builtin, for strings s1, s2: strcmp(s1, s2) == 0 now
    means the same as s1 == s2.

    The str(s) builtin has been changed so that it will return only the
    string formed by the characters of 's' up to the first '\0'.

    The substr(s, start, num) builtin has been changed so that '\0' characters
    are treated like any other.

    Fixed a bug where strcpy("", "a") used to cause a segmentation fault.
    This bug was fixed by Ernest Bowen <ebowen at une dot edu dot au>.

    Make minor change to natnumset.cal in how the tail variable is initialized.

    Fixed bugs in the strcmp, strncmp, strcpy, and strncpy help files.
    This bug was fixed by Ernest Bowen <ebowen at une dot edu dot au>.

    Added cal/screen.cal which Defines ANSI control sequences providing
    (i.e., cursor movement, changing foreground or background color,
    etc.) for VT100 terminals and terminal window emulators (i.e., xterm,
    Apple OS/X Terminal, etc.) that support them.  For example:

        ; read screen
        ; print green:"This is green. ":red:"This is red.":black

    Fixed a bug where too many open files returned E_FOPEN3.  Now
    a new error symbol F_MANYOPEN is used for too many open files.

    Added the builtin function fpathopen() to open a file while
    searching along a path:

        ; fd2 = fpathopen("tmp/date", "r", ".:~:~sc:/tmp:/var/tmp:/var")
        ; print fd2
        "/var/tmp/date"

    By default, fpathopen() searches along CALCPATH.

    Added the calcpath() builtin function to return the current value
    of CALCPATH.

    Fixed prompt characters in the EXAMPLE section of help files.

    Fixed problems related to the protect function and its documentation.
    This bug was reported by David Gilham <davidgilham at gmail dot com>.
    This bug was fixed by Ernest Bowen <ebowen at une dot edu dot au>.

    Raised the limit of exponent in exponential notation.  It was set to
    arbitrary 1000000 (making 1e1000001 in invalid exponential notation
    value).  The exponent for exponential notation is now int(MAXLONG/10).
    On 32 bit machines, this means a limit of 214748364.  On 64 bit
    machines, this means 922337203685477580.  Of course, you may not
    have enough memory to hold such huge values, but if you did you can
    now express such values in exponential notation.

    Added log() builtin for base 10 logarithm.

    Fixed problems where internal use of libc strcpy() might have caused
    a buffer overflow.  Calc now only uses libc strcpy() when the source
    string is a constant.

    The calc STRING and STRINGHEAD now use the standard size_t (an unsigned
    type) length.  Calc mostly uses size_t in dealing with string lengths
    and object sizes when possible.

    Added ${CCWERR} make variable to allow one to force compiler warnings
    to be treated as errors.  The ${CC} make variable now uses ${CCWERR}
    however the ${LCC} (used by the Makefile test code for building hsrc
    files) does not use ${CCWERR}.  By default, ${CCWERR} is empty.
    In development Makefiles, we set CCWERR= -Werror to force us to
    address compiler warnings before the next release.

    The calc make variable, CALCPAGER, now defaults to CALCPAGER= less
    because the less utility is now very common.  Set CALCPAGER= more
    if you do not have less.

    Calc source had two styles of switch indentation.  Converted the
    style where case statements were indented with respect to the switch
    statement into the style where the case statements are at the same
    level.  When comparing with older source, one may use the -b argument
    of the diff command to ignore changes in amount of white space:

        diff -b -r -u calc-2.11.11 calc-2.12.0

    The read, write, and help commands use the value of global string
    variable if the symbol name starts with a $.  For example:

        global x = "lucas.cal";
        read $x;        /* same as read lucas.cal or read "lucas.cal" */

    Added dotest.cal resource.  Based on a design by Ernest Bowen
    <ebowen at une dot edu dot au>, the dotest evaluates individual
    lines from a file.  The dotest() function takes 1 to 3 arguments:

        dotest(dotest_file [,dotest_code [,dotest_maxcond]])

        dotest_file

            Search along CALCPATH for dotest_file, which contains lines that
            should evaluate to 1.  Comment lines and empty lines are ignored.
            Comment lines should use ## instead of the multi like /* ... */
            because lines are evaluated one line at a time.

        dotest_code

            Assign the code number that is to be printed at the start of
            each non-error line and after **** in each error line.
            The default code number is 999.

        dotest_maxcond

            The maximum number of error conditions that may be detected.
            An error condition is not a sign of a problem, in some cases
            a line deliberately forces an error condition.  A value of -1,
            the default, implies a maximum of 2147483647.

        Global variables and functions must be declared ahead of time because
        the dotest scope of evaluation is a line at a time.  For example:

            ; read dotest.cal
            ; read set8700.cal
            ; dotest("set8700.line");

    Updated the todo / wish list items.  The top priority now is to
    convert calc to GNU autoconf / configure to build the calc.

        ; help todo

    Added missing help file for the stoponerror() builtin.

    Corrected and improved the help documentation for factor and lfactor.

    Fixed a problem where some error messages that should have been
    written to a file or string, went to stderr instead.  This bug was
    fixed by Ernest Bowen <ebowen at une dot edu dot au>.

    Corrected the documentation relating to the calc -c command line option.
    The -c relates to scan/parse errors only, not execution errors.

    Corrected a stack overflow problem where the math_fmt() in zio.c
    could be induced to overflow the stack.  This problem was independently
    reported by Chew Keong Tan of Secunia Research <vuln at secunia dot com>.

    Corrected a stack overflow problem where the scanerror() in token.c
    could be induced to overflow the stack by a malformed token.

    Made math_error() in math_error.c more robust against a error
    message constant that is too long.

    Made read_bindings() in hist.c more robust against very long bindings
    config lines.

    Made listsort() in listfunc.c and matsort() matfunc.c more robust
    against sorting of impossibly huge lists and matrices.

    Warnings about an undefining a builtin or undefined function, a
    constant before the comma operator, and an unterminated comment is
    now processed by scanerrors (not simply written directly to stderr).
    These warnings file and line number in which the "error" occurred
    as well as a more precise message than before.  If using -c on the
    calc command line or if stoponerror(-1), then assuming there are
    no other compile errors, only the unterminated comment will stop
    completion of the function being defined.

    The cal/regress.cal now reads most of the calc resource files.

    The issq() test had a slight performance boost.  A minor note
    was added to the help/issq file.

    Improved the documentation of the mul2, sq2, pow2, and redc2 config
    parameters in help/config.

    Added config("baseb"), a read-only configuration value to return
    the number of bits in the fundamental base in which calculations
    are performed.  This is a read-only configuration value.

    Calc now will allow syntax such as ++*p-- and  ++*----*++p----
    where p is an lvalue; successful evaluation of course require the
    successive operations to be performed to have operands of appropriate
    types; e.g. in *A, A is usually an lvalue whose current value is a
    pointer. ++ and -- act on lvalues. In the above examples there are
    implied parentheses from the beginning to immediately after p. If
    there are no pre ++ or -- operations, as in **p++.  The implied
    parentheses are from immediately before p to the end.

    Improved the error message when && is used as a prefix operator.

    Changed the help/config file to read like a builtin function help file.

    One can no longer set to 1, or to a value < 0, the config()
    parameters: "mul2", "sq2", "pow2", and "redc2".  These values
    in the past would result in improper configuration of internal
    calc algorithms.  Changed cal/test4100.cal to use the minimal
    value of 2 for "pow2", and "redc2".

    Changed the default values for the following config() parameters:

        config("mul2") == 1780
        config("sq2") == 3388
        config("pow2") == 176

        These values were determined established on a 1.8GHz AMD 32-bit
        CPU of ~3406 BogoMIPS by the new resource file:

            cal/alg_config.cal

   Regarding the alg_config.cal resource file:

        The best_mul2() function returns the optimal value of config("mul2").
        The best_sq2() function returns the optimal value of config("sq2").
        The best_pow2() function returns the optimal value of config("pow2").
        The other functions are just support functions.

        By design, best_mul2(), best_sq2(), and best_pow2() take a few
        minutes to run.  These functions increase the number of times a
        given computational loop is executed until a minimum amount of CPU
        time is consumed.  To watch these functions progress, one can set
        the config("user_debug") value.

        Here is a suggested way to use the alg_config.cal resource file:

            ; read alg_config
            ; config("user_debug",2),;
            ; best_mul2(); best_sq2(); best_pow2();
            ; best_mul2(); best_sq2(); best_pow2();
            ; best_mul2(); best_sq2(); best_pow2();

        NOTE: It is perfectly normal for the optimal value returned
        to differ slightly from run to run.  Slight variations due to
        inaccuracy in CPU timings will cause the best value returned to
        differ slightly from run to run.

        See "help resource" for more information on alg_config.cal.

    Updated the "help variable" text to reflect the current calc
    use of ` (backquote), * (star), and & (ampersand).

    Removal of some restrictions on the use of the same identifier
    for more than one of parameter, local, static or global variable.

        For example, at command level, one could use:

            for (local x = 0; x < 10; x++) print sqrt(x);

        At the beginning of a statement, "(global A)" is a way of
        indicating a reference to the variable A, whereas "global A"
        would be taken as a declaration. Parentheses are not required in
        "++global A" or "global A++" when "global" is used in this way.

        The patch extends this "specifier" (or "qualifier") feature
        to static variables, but such that "static A" refers only
        to a static variable at the current file and function scope
        levels. (If there is already a static variable A at the current
        file and function levels, a declaration statement "static A"
        would end the scope of that variable and define a new static
        variable with identifier A. A "global A" declaration is more
        drastic in that it ends the scope of any static variable A at
        the same or higher scope levels.)

        Unlike a static declaration in which an "initialization" occurs at
        most once, in the specifier case, "static A = expr" is simply an
        assignment which may be repeated any number of times.  An example
        of its use is:

            define np() = static a = nextprime(a);

        For n not too large, the n-th call to this function will
        return the n-th prime. The variable a here will be private to
        the function.

        Because one can use "global", "local" or "static" to specify a
        type of variable, there seems little point in restricting the
        ways identifiers that can be used in more than one of these
        or as parameters. Obviously, introducing A as a local variable
        when it is being used as a parameter can lead to confusion and a
        warning is appropriate, but if it is to be used only occasionally,
        it might be convenient to be able to refer to it as "local A"
        rather than introducing another identifier. While it may be
        silly to use the same identifier for both a parameter and local
        variable, it should not be illegal.

    Added warnings for possibly questionable code in function definitions.

    Added config("redecl_warn", boolean) to control if calc issues
    warnings about variables being declared.  The config("redecl_warn")
    value is TRUE by default.

    Added config("dupvar_warn", boolean) to control if calc issues
    warnings about when variable names collide.  The config("dupvar_warn")
    value is TRUE by default.  Examples of variable name collisions
    include when:

        * both local and static variables have the same name
        * both local and global variables have the same name
        * both function parameter and local variables have the same name
        * both function parameter and global variables have the same name

    Fix of a bug which causes some static variables not to be correctly
    unscoped when their identifiers are used in a global declaration.

    Change of "undefine" from a command-level keyword to statement level and
    introduction of an "undefine static A" statement to end the scope of a
    static variable A at the current file/function levels.

    Change/restored the syntax rules for "for" and "while" loops to
    recognize an unescaped newline in top-level command-level statements.

    Updated help/avg, help/define, help/fprintf, help/gcd, help/hash,
    help/hmean, help/lcm, help/max, help/min, help/null, help/poly,
    help/printf, help/ssq, help/strcat, help/strprintf, help/sum,
    help/xor.

    Changed the definition of the function ssq() to enable list arguments
    to be processed in the same way as in sum().  For example:

        ssq(1,2, list(3,4,list(5,6)), list(), 7, 8)

    returns the value of 1^2 + 2^2 + ... + 8^2 == 204.

    Added the calc resource sumtimes.cal, to give the runtimes for
    various ways of evaluating sums, sums of squares, etc, for large
    lists and matrices.  For example:

        read sumtimes
        doalltimes(1e6)

    Calc now ignores carriage returns (\r), vertical tabs (\v), and
    form feeds (\f) when token parsing.  Thus users on Windows systems
    can write files using their \r\n format and users on non-Windows
    systems can read them without errors.

    The quomod() builtin function now takes an optional 5th argument
    which controls the rounding mode like config("quomod") does, but
    only for that call.  Now quomod() is in line with quo() and mod()
    in that the final argument is an optional rounding mode.

    Added a "make uninstall" rule which will attempt to remove everything
    that was installed by a "make install".

    Changed the copyright line in the rpm spec file to a "License" line
    as per new rpm v4.4 syntax.

    The quomod() builtin function does not allow constants for its 3rd
    and 4th arguments.  Updated the "help quomod" file and added more
    quomod regression tests.

    Added patch from Ernest Bowen <ebowen at une dot edu dot au> to
    add the builtin: estr().  The estr(x) will return a representation
    of a null, string, real number, complex number, list, matrix,
    object. block, named block, error as a string.

    Added patch from Ernest Bowen <ebowen at une dot edu dot au> to
    add the builtin: fgetfile().  The fgetfile(x) will return the rest
    of an open file as a string.

    Improved help files for fgetfield, fputs, name, or quomod.


The following are the changes from calc version 2.11.10.1 to 2.11.11:

    Fixed a bug reported by the sourceforge user: cedars where:

        ln(exp(6)) == 3         /* WRONG!!! */

    incorrectly returned 1.  This bug was fixed by Ernest Bowen
    <ebowen at une dot edu dot au>.  The regression test
    was expanded to cover this issue.

    Added minor improvements to hash regression testing of pi().

    Fixed "help script" and the calc man page regarding the requirement
    of -f to be the last -flag in shell script mode.  Further clarified
    the meaning and placement of the -f flag.

    Moved issues with chi.cal intfile.cal into a "mis-features" section
    of the BUGS file.  See "help bugs" or the BUGS source file for details.

    Added the bug about:

        calc 'read ellip; efactor(13*17*19)'

    to the BUGS file.  See "help bugs" or the BUGS source file for details.
    Anyone want to track down and fix this bug?

    Fixed typo in the "help mat" example and improved the mat_print example.

    Renamed most COMPLEX C function names to start with c_ to avoid
    conflicts with new C standard functions.  Note that the calc
    builtin function names remain the same.   The C function names
    inside the C source that calc is written in changed.  This means
    that code that linked to libcalc.a will need to change in order
    to call calc's functions instead of the C standard functions.
    See cmath.h, comfunc.c, and commath.c for details.  See also
    http://www.opengroup.org/onlinepubs/009695399/basedefs/complex.h.html
    for names of the new C standard functions.

    Changed the calc man page to note that using -- in the command will
    separate calc options from arguments as in:

        calc -p -- -1 - -7

    Noted how Apple OS X can make use of readline in the Makefile.
    In particular:

        # For Apple OS X: install fink from http://fink.sourceforge.net
        #                 and then do a 'fink install readline' and then use:
        #
        READLINE_LIB= -L/sw/lib -lreadline -lhistory -lncurses

    Added linear.cal as a calc standard resource file.


The following are the changes from calc version 2.11.10 to 2.11.10:

    The cygwin config value is correctly tested while doing comparisons
    between config states.

    Added config("compile_custom") to determine if calc was compiled
    with -DCUSTOM.  By default, the Makefile uses ALLOW_CUSTOM= -DCUSTOM
    so by default, config("compile_custom") is TRUE.  If, however,
    calc is compiled without -DCUSTOM, then config("compile_custom")
    will be FALSE.  NOTE: The config("compile_custom") value is only
    affected by compile flags.  The calc -D runtime command line option
    does not change the config("compile_custom") value.  This is a
    read-only configuration value.

    Added config("allow_custom") to determine if the use of custom
    functions are allowed.  To allow the use of custom functions, calc
    must be compiled with -DCUSTOM (which it is by default) AND calc run
    be run with the -D runtime command line option (which it is not by
    default).  If config("allow_custom") is TRUE, then custom functions
    are allowed.  If config("allow_custom") is FALSE, then custom
    functions are not allowed.  This is a read-only configuration value.

    Correctly hash config state for windows and cygwin values.  The value
    of config("compile_custom") and config("allow_custom") also affect
    the hash of the config state.

    Fixed the custom/argv.cal test code to avoid use of a reserved
    builtin function name.

    Fixed custom/*.cal scripts to conform better with the cal/*.cal
    resource files.

    Removed the Makefile variables ${LONGLONG_BITS}, ${HAVE_LONGLONG},
    and ${L64_FORMAT}.  Removed longlong.c and longlong.h.  The use
    of HAVE_LONGLONG=0 was problematic.  The lack of complaints about
    the HAVE_LONGLONG=0 shows that the 'long long' type is wide spread
    enough to warrant not trying to support compilers without 'long long'.

    Removed the SVAL and SHVAL macros from zrand.c, zrand.h, and zmath.h
    as they were causing too many broken C pre-processors and C checkers
    to become confused.

    Added a 'make splint' rule to use the splint statically checking
    tool on the calc source.

    Removed support of the BSDI platform.  The BSDI platform is no longer
    directly supported and we lost our last BSDI machine on which we
    could test calc.  Best wishes to the former BSDI folk and thanks
    for breaking important ground in the Open Source Movement!

    Fixed several typos found in the documentation and builtin
    function output by C Smith <smichr at hotmail dot com>.

    Fixed -d so that:

        calc -d 2/3

    will print 0.66666666666666666667 without the leading tilde as
    advertised in the man page.

    Added a missing help file for the display builtin function as
    requested by Igor Furlan <primorec at sbcglobal dot net>.

    Changed the "help environment" file to reflect modern default
    values of CALCPATH and CALCRC.

    Added missing variables for printing by the "make env" rule.

    Added EXT Makefile variable so that Cygwin can install calc as
    calc.exe.  By default, EXT is empty so that calc is calc on most
    modern operating systems.  Thanks goes to Ullal Devappa Kini <wmbfqj
    at vsnl dot net> for helping identify this problem and testing our fix.

    Added custom function:

        custom("pmodm127", q)

    to compute 2^(2^127-1) mod q.  While currently slower than just
    doing pmod(2,2^127-1,q), it is added to give an example of a
    more complex custom function.  Call calc with the -C flag to
    use custom functions.

    Made slight changes to the custom/HOW_TO_ADD documentation.

    Fixed some \ formatting man page problems as reported by Keh-Cheng
    Chu <kehcheng at quake dot Stanford dot edu>.

    Fixed some comparison between signed and unsigned in md5.c
    that was reported for the PowerMac G5 2GHz MacOS 10.3 by
    Guillaume VERGNAUD <vergnaud at via dot ecp dot fr>.

    Fixed a number of pending issues with help files filling in
    missing  LIMITS, LINK LIBRARY, and SEE ALSO information,


The following are the changes from calc version 2.11.9 to 2.11.9.3:

    Fixed calc man page examples to move -f to the end of the line.
    Thanks goes to Michael Somos for pointing this out.

    Linux and gcc now compiled with -Wall -W -Wno-comment.

    Fixed a post increment that was reported by R. Trinler <trinler at
    web dot de> and fixed by Ernest Bowen <ernie at turing dot une dot
    edu dot au>.

    Fixed pi.cal to not depend on the buggy pre-2.11.9 post increment
    behavior.

    Added config("cygwin") to determine if calc was compiled under Cygwin.
    The config("cygwin") is a read-only configuration value that is 1
    when calc was compiled under Cygwin and 0 otherwise.  Regression
    tests 949 and 950 are skipped when config("cygwin") is true.

    The Makefile variable HAVE_NO_IMPLICIT is empty by default so that
    the Makefile will test if the compiler has a -Wno-implicit flag.

    Added HAVE_UNUSED Makefile variable.  If HAVE_UNUSED is empty,
    then the Makefile will run the have_unused program to determine
    if the unused attribute is supported.  If HAVE_UNUSED is set to
    -DHAVE_NO_UNUSED, then the unused attribute will not be used.

    The Makefile builds have_unused.h which defines, if the unused
    attribute is supported:

        #define HAVE_UNUSED /* yes */
        #define UNUSED __attribute__((unused)) /* yes */

    or defines, if the unused is not supported (or if the Makefile
    variable is HAVE_UNUSED= -DHAVE_NO_UNUSED):

        #undef HAVE_UNUSED /* no */
        #define UNUSED /* no */

    Fixed numerous warnings about comparison between signed and unsigned
    value warnings and unused parameter warnings in version.c, zrand.c,
    string.c, shs1.c, shs.c, qtrans.c, qmath.c, qfunc.c, md5.c, matfunc.c,
    hist.c, file.c, const.c, blkcpy.c, seed.c, opcodes.c, func.c, qio.c,
    zrandom.c, custom/c_argv.c, custom/c_devnull.c, custom/c_help.c,
    custom/c_sysinfo.c, addop.c and calc.c.

    Fixed some typos in this file.

    By default, compile with -O3 -g3.  The Makefile comments on how some
    distributions might need to use -O2 -g or -O -g.


The following are the changes from calc version 2.11.8.0 to 2.11.8.1:

    Updated HOWTO.INSTALL to reflect the new RPM files.

    Clarify that the internal hash as well as the hash builtin
    function used by calc, while based on the Fowler/Noll/Vo
    hash is NOT an FNV hash.

    Made slight performance improvements to calc by an optimization of how
    calc's internal hash is computed.  The "make chk" regression test
    runs about 1.5% faster (when compiled with -O3 on an AMD Athlon)
    NO_HASH_CPU_OPTIMIZATION is not defined.  Calc's internal hash values
    have not changed.  By default, NO_HASH_CPU_OPTIMIZATION is NOT defined
    and the slightly faster expression is used.

    A slight modification of what was known as the "calc new standard"
    configuration (calc -n or config("all", "newstd")) is now the default
    calc configuration.  The flag:

        calc -O

    was added to get the old classic calc configuration.  The flag command
    line flag, -n, now does nothing.  Use of -n is deprecated and may go
    away / be used for something else in the future.

    The following table gives the summary of these changes:

             pre v2.11.8                     v2.11.8
             default         pre v2.11.8     -O & oldstd      v2.11.8
             and oldstd      -n & newstd     classic cfg      default
             --------------------------------------------------------
    epsilon     1e-20           1e-10           1e-20           1e-20
    quo         2               2               2               2
    outround    2               24              2               24
    leadzero    0               1               0               1
    fullzero    0               1               0               0
    prompt      >               ;               >               ;
    more        >>              ;;              >>              ;;

    With the exception of epsilon being 1e-20, and fullzero being unset,
    the new default calc config is like it was (pre-2.11.8) with calc -n /
    config("all", "newstd").

    The new default config is the old classic config with outround being
    24, leadzero being set, and the prompts being ;'s.

    Fixed a bug in the evaluation of tanh(1e-23) with an epsilon(1e-100).
    Thanks goes to Dmitry G. Baksheyev <bd at nbsp dot nsk dot su>
    for reporting the problem, and thanks goes to Ernest Bowen
    <ernie at turing dot une dot edu dot au> for the fix.


The following are the changes from calc version 2.11.7.0 to 2.11.7.1:

    Added support to build calc RPMs thanks to Petteri Kettunen
    <petterik at users dot sourceforge dot net>.

    Added rpm rule to Makefile to build rpm set.  The rpm rule
    uses the rpm.mk Makefile and the calc.spec.in spec template.

    The default Makefile is now the Makefile used during rpm
    creation.  This Makefile assumes that system has readline,
    ncurses (-lreadline -lhistory -lncurses), and less.
    It compiled with a high gcc optimization level (-O3 -g3).
    The Makefile used during rpm creation is the Makefile
    that appears in the calc-src rpm as well.

    The Makefile shipped with the old style gziped tarball
    is still the same generic Makefile.

    The Makefile now uses ${MKDIR} ${MKDIR_ARG} when creating
    directories during installation.  By default, it does
    a mkdir -p when forming directories.

    Fixed attributes on include and lib calc-devel files.

    Adjusted the interaction between rpm.mk, and the calc.spec.in.
    Release number now comes from calc.spec.in only.

    Renamed calc and calc-devel RPMs to use .i686 instead of .i386.


The following are the changes from calc version 2.11.6.3 to date:

    Fixed a bug in deg.cal where fixdms() was being called with
    the wrong type of argument.

    Changed the value of digits(1) and digits(0) to be 1.  Now digits()
    returns number of digits in the standard base-b representation
    when x is truncated to an integer and the sign is ignored.
    To be more precise: when abs(int(x)) > 0, this function returns
    the value 1 + ilog(x, b).  When abs(int(x)) == 0, then this
    function returns the value 1.

    As the result of the above digits() change, the repeat.cal
    resource file script was modified to remove the special
    case for repeating a value of 1.  Also the regress tests
    #715, #977 and #978 were changed.

    Made a minor improvement to the "help places" documentation.

    Fixed dms_neg(a) in deg.cal thanks to a bug report by kaa
    <kaa76 at pochtamt dot ru>.


The following are the changes from calc version 2.11.6.0 to 2.11.6.2:

    Clarified remark in lucas.cal about use of n mod 2^n == 0.

    Fixed help typos reported by Marc Mezzarobba <mm at mm dot ovh dot org>.

    Forced system("") to return 0 under Windows.

    The direct.h include file is not used when compiling under Cygwin.

    Fixed bug where random(10,11) caused calc to dump core when issued
    the 2nd time.

    Moved the setting of the Makefile variable ${CALC_INCDIR} to
    the section where things like ${BINDIR} and ${LIBDIR} are set.
    Idea from Clifford Kite <kite_public1 at ev1 dot net>.

    The Makefile is shipped mode 0644 since a number of folks
    edit it (to build and check calc) as a non-root user and later
    on su to root to install.  Idea from Clifford Kite <kite_public1
    at ev1 dot net>.

    Added base2() builtin function to calc.  Normally calc prints
    values according to base().  Frequently some users want to see
    a value in two bases.  Flipping back and forth between to bases
    is a bit of a pain.  With base2(), calc will output a value twice:

        ; 234567
                234567
        ; base2(16),
        ; 234567
                234567 /* 0x39447 */
        ; 131072
                131072 /* 0x20000 */
        ; base2(0),
        ; 131072
        131072

    By default, base2() is disabled.  Calling base2(0) will also turn
    off the double base mode.  Thanks goes to Erik Anggard
    <erik dot anggard at packetfront dot com> for his idea and
    his initial patch.

    Added repeat.cal as a calc resource file script:

        repeat(digit_set, repeat_count)

        Return the value of the digit_set repeated repeat_count times.
        Both digit_set and repeat_count must be integers > 0.

        For example repeat(423,5) returns the value 423423423423423,
        which is the digit_set 423 repeated 5 times.

    Makefile no longer makes a direct reference to Red Hat 6.0.

    Added missing math_setmode2() prototype to zmath.h.

    Fixed some implicit declarations of functions by either making
    them explicit or by including the proper system .h files.

    Makefile no longer uses -Wno-implicit flag, by default, for
    gcc based compiles on calc source.  Makefile now attempts to
    compile no_implicit.c with an explicit -Wno-implicit arg in an
    effort to determine of -Wno-implicit is a valid compiler flag.
    If no_implicit.c is compiled with -Wno-implicit, then
    the file no_implicit.arg is created with the contents
    of the -Wno-implicit flag.  Otherwise no_implicit.arg
    is created as an empty file.

    Added the Makefile variable ${HAVE_NO_IMPLICIT}, which if
    not set to YES will prevent no_implicit.c from being
    compiled and prevent the -Wno-implicit flag from being used.
    If ${HAVE_NO_IMPLICIT} is not YES, then an empty no_implicit.arg
    file is created and no_implicit.c is not compiled.

    The seed.c file, because the pseudo_seed() function contains
    calls to a number of various system functions, attempts to
    compile with the -Wno-implicit flag (if allowed by the
    formation of the no_implicit.arg file).

    Misc make depend fixes and cleanup.

    Fixed formation of the custom/.all file.

    Fixed repeat(1, repeat_count) bug.


The following are the changes from calc version 2.11.5.5 to 2.11.5.9:

    Now using version numbers of one of these forms:

        x.y.z.w
        x.y.z
        x.y

    Changed the READLINE_LIB Makefile variable to not link with -lreadline
    by default.  If you do have readline, we recommend that you use it.
    If you can install the GNU readline:

        http://freshmeat.net/projects/gnureadline/
        http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html

    we recommend it.  But if not, you should set the USE_READLINE,
    READLINE_LIB, and READLINE_INCLUDE Makefile variables to empty.
    NOTE: See the BUGS file for a Linux issue when compiling calc
    with -O (or -O2 or -O3) AND with -g (or -g3) AND with readline.

    Removed an obsolete reference to TOPDIR.  This was fixed thanks to
    a bug report by Clifford Kite <kite_public1 at ev1 dot net>.
    Fixed other inconsistencies related to things like BINDIR.

    Fixed calc man page so that is refers to -f instead of the old -S flag.
    Fixed thanks to Clifford Kite <kite_public1 at ev1 dot net> for
    point this out.

    All for loops end with /dev/null to avoid any problems related
    to systems that cannot grok empty for loops.

    Changed the libcalc functions creal and cimag to c_real and c_imag
    to about conflicts with new libc such as those used by gcc v3.
    Thanks Eli Zaretskii <eliz at is dot elta dot co dot il> and
    Martin Buck <m at rtin-buck dot de> for alerting us to this conflict.

    The Makefile no longer hard code's /usr/include.  Instead it uses
    the ${INCDIR} Makefile variable.  Thanks goes to Eli Zaretskii
    <eliz at is dot elta dot co dot il> for pointing out this inconsistency.

    Added mods to support compilation under DJGPP.  DJGPP runs on 386
    and newer PCs running DOS or dos-compatible operating systems.
    See http://www.delorie.com/djgpp/.  Thanks goes to Eli Zaretskii
    <eliz at is dot elta dot co dot il> for sending in these mods.

    Updated README.WINDOWS to include information on building with DJGPP.

    The pld folks are building RPMs based on our calc distributions.
    See:  ftp://ftp.pld.org.pl/dists/ra/PLD/i686/PLD/RPMS or
    http://ftp.pld.org.pl/dists/ra/PLD/i686/PLD/RPMS more information.
    We appreciate their work in this regard.  In the next release, we
    plan to also build and release our own RPMs based on their efforts.

    Changed the Makefile variable CUSTOMLIBDIR to CUSTOMCALDIR.
    Changed the Makefile variable CSHAREDIR to CALC_SHAREDIR.
    Changed the Makefile variable INCDIRCALC to CALC_INCDIR.
    Removed the Makefile variable SHAREDIR.

    Updated the HOWTO.INSTALL and README.WINDOWS files.

    Fixed definition of MAXUFULL.  Thanks to a bus report from
    Jill Poland <jpoland at cadence dot com>.

The following are the changes from calc version 2.11.5t4.1 to 2.11.5t4.4:

    Updated dependency rules in Makefiles.

    NOTE: -DSRC, as used in 2.11.5t4.1 was renamed -DCALC_SRC
    in a later version.

    Calc include files use #include "foo.h" to include other calc
    header files if -DCALC_SRC.  Otherwise they use <calc/foo.h>.
    The -DCALC_SRC symbol is defined by default in calc's Makefile
    and so it uses the header files from within the calc src tree.
    If an external non-calc program includes an installed calc
    header file (from under /usr/include), and it does NOT define
    CALC_SRC, then it will obtain the calc header files from the
    correct system location (such as /usr/include/calc/foo.h).

    Added calc builtin function: version() which returns the calc
    version string.

    Added subject requirements for the calc-tester-request and
    calc-bugs-mail Email aliases.  See:

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

    for details.

    Corrected a bug that incorrectly set the default calc path
    back in version 2.11.5t4.  The default CALCPATH is now:

        .:./cal:~/.cal:/usr/share/calc:/usr/share/calc/custom

    and the default CALCRC is now:

        /usr/share/calc/startup:~/.calcrc:./.calcinit

    This fixes the missing bindings error and it places the calc
    resource files into the default path.

    If you are using the GNU readline then the Makefile recommends that
    you link with the ncurses library.

    Applied Makefile, cscript/Makefile and custom/Makefile patches to
    fix install mode problems, to deal with sorting and dates in I18n
    environments (such as Japanese), to fix some problems with calc.spec
    and to fix the cscript #! header lines.  Thanks goes to KAWAMURA Masao
    (kawamura at mlb.co.jp) for the bug report and patch!

    Fixed headers on fproduct.calc powerterm.calc 4dsphere.calc so
    that they are correctly changed on installation.

    Added ${GREP} Makefile variable.

    The top level Makefile now sets LANG=C and passes it down to
    lower level Makefiles.

    Updated URLs in cal/lucas.cal comments.

    Now shipping calc.spec, inst_files, spec-template and Makefile.linux
    with the standard calc source distribution.  Note that the standard
    Makefile has not changed.  The Makefile.linux only in minor ways
    needed to build calc rpms.

    Added $T Makefile variable.  $T is the top level directory under
    which calc will be installed.  The calc install is performed under $T,
    the calc build is performed under /.  The purpose for $T is to allow
    someone to install calc somewhere other than into the system area.
    For example when forming the calc rpm, the Makefile is called with
    T=$RPM_BUILD_ROOT.  If $T is empty, calc is installed under /.

    Removed all echo_XYZ rules except for echo_inst_files from lower
    level makefile.  The calc.spec will use a make install rule
    with T=$RPM_BUILD_ROOT.

    Updated LIBRARY file with instructions related to -DCALC_SRC,
    the new default include file location and -lcustcalc.


The following are the changes from calc version 2.11.5t3 to 2.11.5t4:

    The Makefile will now send both stdout and stderr to /dev/null
    when compiling hsrc intermediates.

    The config("verbose_quit") value was restored to a default
    value of FALSE.

    Added the cscript:

        powerterm [base_limit] value

    to write the value as the sum (or difference) of powers <= base_limit
    where base_limit by default is 10000.

    Applied a bug fix by Dr.D.J.Picton <dave at aps5.ph.bham.ac.uk>
    to have help with no args print the default help file.

    Renamed lavarand to LavaRnd.

    Added rules to build a calc rpm.

    All installed files are first formed as foo.new, and then moved
    into place as foo via a atomic rename.

    During installation, only files that are different are installed.
    If the built file and the installed file are the same, no
    installation is performed.

    Calc has new default installation locations:

    Makefile var   old location                       new location
    ------------   ------------                       ------------
    TOPDIR         /usr/local/lib                       <<no longer used>>
    BINDIR         /usr/local/bin                     /usr/bin
    SHAREDIR          <<not set>>                     /usr/share
    INCDIR         /usr/local/include                 /usr/include
    LIBDIR         /usr/local/lib/calc                /usr/lib
    CSHAREDIR         <<not set>>                     /usr/share/calc
    HELPDIR        /usr/local/lib/calc/help           /usr/share/calc/help
    INCDIRCALC     /usr/local/include/calc            /usr/include/calc
    CUSTOMLIBDIR   /usr/local/lib/calc/custom         /usr/share/calc/custom
    CUSTOMHELPDIR  /usr/local/lib/calc/help/custhelp  /usr/share/calc/custhelp
    CUSTOMINCDIR     <<not set>>                      /usr/include/calc/custom
    SCRIPTDIR      /usr/local/bin/cscript             /usr/bin/cscript
    MANDIR           <<not set>>                      /usr/share/man/man1
    CATDIR           <<not set>>                        <<not set>>

    The Makefile variable ${TOPDIR} is no longer used.  In some places
    it has been replaced by a new Makefile variable ${SHAREDIR}.  Some
    of the old TOPDIR functionality has been replaced by ${CSHAREDIR}.

    The install rules no longer remove old obsolete files.  We assume
    that these old files have long since vanished!  :-)

    Reduced the amount of output when doing a make all where nothing
    needs to be made.

    Reduced the amount of output when doing a make install where nothing
    needs to be installed.

    If you install using the new default locations, you can remove
    old calc files installed in the old default location by doing:

        make olduninstall


The following are the changes from calc version 2.11.5t2 to 2.11.5t2.1:

    Fixed a bug, reported by Ernest Bowen <ernie at turing dot
    une dot edu dot au> that caused command lines to be echoed in
    interactive mode.  Fixed a bug that sometimes left the terminal
    in a non-echoing state when calc exited.

    Renamed error codes E_FGETWORD1 and E_FGETWORD2 symbols to
    E_FGETFIELD1 and E_FGETFIELD2.

    Made a minor format change to the top of the calc man page.

    The findid() function in file.c 2nd argument changed.  The argument
    is now mostly a writable flag.  This function now finds the file
    I/O structure for the specified file id, and verifies that
    it is opened in the required manner (0 for reading or 1 for writing).
    If the 2nd argument is -1, then no open checks are made at all and
    NULL is then returned if the id represents a closed file.

    The calc builtin function, fopen(), now allows one to specify
    opening files in binary modes.  On POSIX / Linux / Un*x-like systems,
    text file is the same as a binary file and so 'b' to an fopen has
    no effect and is ignored.  However on systems such as MS Windows
    the 'b' / binary mode has meaning.  See 'help fopen' for details.

    On systems (such as MS Windows), calc will produce a different error
    message when it attempts to open /dev/tty.  This will condition
    will occur in things like calc scripts when they switch from ``batch
    processing'' commands from and want to start interactive mode.

    Regression tests fopen in binary mode in a few places where a
    difference between text and binary string lengths matter.
    The intfile calc resource file also uses binary mode.

    Changed the rand() builtin and its related functions srand() and
    randbit() to use the Subtractive 100 generator instead of the
    additive 55 generator.  This generator as improved random properties.
    As a result, of this change, the values produced by rand(),
    rand() and randbit() are now different.

    Updated regression tests for new rand() and randbit() output.

    Applied a bug fix from Ernest Bowen <ernie at turing dot une dot
    edu dot au> dealing with one-line "static" declaration like:

        static a = 1, b;

    Added regression test 8310 to test for the static bug fix.


The following are the changes from calc version 2.11.5t0 to 2.11.5t1.1:

    Fixed a compile problem with Linux 2.4 / Debian.  Thanks goes
    to Martin Buck <m at rtin-buck dot de> for help with this issue.

    Fixed a bug in how L64_FORMAT (it determined if "%ld" or "%lld"
    is appropriate for printing of 64 bit long longs) was determined.
    Thanks goes to Martin Buck <m at rtin-buck dot de> for reporting
    this bug and testing the fix.

    An effort was made to make calc easier to build under Windows
    using the Cygwin project (http://sources.redhat.com/cygwin/).
    Thanks to the work of Thomas Jones-Low (tjoneslo at softstart
    dot com), a number of #if defined(_WIN32)'s have been added
    to calc source.  These changes should not effect Windows
    free system such as GNU/Linux, Solaris, POSIX-like, etc ...

    Added windll.h to deal with Windows related DLL issues.
    Using the convention of 'extern DLL' instead of 'DLL extern'
    to deal with symbols that export to or import from a DLL.

    Added HAVE_MALLOC_H, HAVE_STDLIB_H, HAVE_STRING_H, HAVE_TIMES_H,
    HAVE_SYS_TIMES_H, HAVE_TIME_H, HAVE_SYS_TIME_H, HAVE_UNISTD_H
    and HAVE_URANDOM to the Makefile.  If these symbols are empty,
    then the Makefile looks for the appropriate system include file.
    If they are YES, then the Makefile will assume they exist.
    If they are NO, then the Makefile will assume they do not exist.

    Changed HAVE_URANDOM to match the empty, YES, NO values.
    If HAVE_URANDOM is empty, then the Makefile will look for /dev/urandom.
    If HAVE_URANDOM is YES, then the Makefile will assume /dev/urandom exists.
    If HAVE_URANDOM is NO, then the Makefile will assume /dev/urandom does
    not exist.

    If TERMCONTROL is -DUSE_WIN32, then the Windows terminal control
    (no TERMIOS, no TERMIO, no SGTTY) will be assumed.

    Added a win32_hsrc Makefile rule to create hsrc files appropriate
    for a Windows system using Cygwin gcc environment.  Added win32.mkdef
    which is used by the win32_hsrc rule to set the Windows specific
    Makefile values to build hsrc files.  The hsrc files are built
    under the win32 directory.

    Added FPOS_POS_BITS, OFF_T_BITS, DEV_BITS and INODE_BITS Makefile
    symbols to allow one to force the size of a file position, file
    offset, dev and inode value.  Leaving these values blank will
    Makefile to determine their size.

    Fixed a bug in the way file offsets, device and inode values are copied.

    Added chi.cal for a initial stab as a Chi^2 function.  The chi_prob()
    function does not work well with odd degrees of freedom, however.

    Added big 3 to config("resource_debug").  Calc resource file scripts
    check for config("resource_debug") & 8 prior to printing internal debug
    statements.  Thus by default they do not print them.

    Added intfile.cal as a calc resource file script:

        file2be(filename)

            Read filename and return an integer that is built from the
            octets in that file in Big Endian order.  The first octets
            of the file become the most significant bits of the integer.

        file2le(filename)

            Read filename and return an integer that is built from the
            octets in that file in Little Endian order.  The first octets
            of the file become the most significant bits of the integer.

        be2file(v, filename)

            Write the absolute value of v into filename in Big Endian order.
            The v argument must be on integer.  The most significant bits
            of the integer become the first octets of the file.

        le2file(v, filename)

            Write the absolute value of v into filename in Little Endian order.
            The v argument must be on integer.  The least significant bits
            of the integer become the last octets of the file.

    Added the following help aliases:

        copy    blkcpy
        read    command
        write   command
        quit    command
        exit    command
        abort   command
        cd      command
        show    command

    Added the cscript:

        fproduct filename term ...

    to write the big Endian product of terms to a filename.  Use - for stdout.

    Fixed calc path in help/script.

    Added read-only parameter, config("windows") to indicate if the system
    is MS Windows WIN32 like system.

    Configuration values that used to return "true" or "false" now return
    1 (a true value) or 0 (a false value).  Thus one can do:

        if (config("tab")) { ... } else { ... }

    The configuration values that now return 1 or 0 are:

        config("tilde")
        config("tab")
        config("leadzero")
        config("blkverbose")
        config("verbose_quit")
        config("windows")

    Now shipping a win32 sub-directory that contains hsrc .h files
    that have been attempted to be built for Windows.


The following are the changes from calc version 2.11.4t1 to 2.11.4t2:

    Added missing test8600.cal test file.

    Fixes cscript files to deal with the -S flag being replaced by
    -f and possibly other flags.

    Added regression tests for builtin functions bernoulli, catalan,
    euler, freeeuler, and sleep.  Added non-base 10 regression tests
    for digit, digits and places.

    The bernoulli.cal script now just calls the bernoulli() builtin
    function.  It remains for backward compatibility.

    The Makefile now builds have_fpos_pos.h to determine if the
    a non-scalar FILEPOS has a __pos structure element.  If it does,
    the FILEPOS_BITS is taken to be the size of just the __pos element.

    Misc fixes related to non-scalar (e.g., structure) FILEPOS.  Fixed
    a compile problems where non-scalar FILEPOS were incorrectly assigned.

    Fixed make depend rule.

    Return an error on malloc / realloc failures for bernoulli and
    euler functions.

    Added MAKEFILE_REV make variable to help determine Makefile version.
    Fixed the way the env rule reports Makefile values.


The following are the changes from calc version 2.11.3t0 to 2.11.4:

    Increased the maximum number of args for functions from 100 to 1024.
    Increased calc's internal evaluation stack from 1024 to 2048 args.
    Added test8600.cal to the regression suite to test these new limits.

    Updated and fixed misc typos in calc/README.

    Clarified in the COPYING file that ALL calc source files, both
    LGPL covered and exceptions to the LGPL files may be freely used
    and distributed.

    Added help files or updated for: bernoulli, calc_tty, catalan,
    digit, digits, euler, freeeuler, places and sleep.

    A collection of 18 patches from Ernest Bowen
    <ernie at turing dot une dot edu dot au>:

    (1)  A new flag -f has been defined which has the effect of a read
    command without the need to terminate the file name with a semicolon
    or newline.  Thus:

            calc "read alpha; read beta;"

    may be replaced by:

            calc -f alpha -f beta

    Quotations marks are recognized in a command like

            calc -f 'alpha beta'

    in which the name of the file to be read includes a space.

    (2) Flags are interpreted even if they are in a string, as in:

            calc "-q -i define f(x) = x^2;"

    which has the effect of:

            calc -q -i "define f(x) = x^2;"

    To achieve this, the use of getopts() in calc.c has been dropped in
    favor of direct reading of the arguments produced by the shell.
    In effect, until a "--" or "-s" or a calc command (recognized
    by not starting with '-') is encountered, the quotation signs in
    command lines like the above example are ignored.  Dropping getopts()
    permits calc to specify completely the syntax rules calc will apply
    to whatever it is given by the shell being used.

    (3) For executable script (also called interpreter) files with first
    line starting with "#!", the starting of options with -S has been
    replaced by ending the options with -f.  For example, the first line:

            #! full_pathname_for_calc -S -q -i

    is to be replaced by:

            #! full_pathname_for_calc -q -i -f

    Thus, if the pathname is /usr/bin/calc and myfile contains:

            #!/usr/bin/calc -q -i -f
            global deg = pi()/180;
            define Sin(x) = sin(x * deg);

    and has been made executable by:

            chmod u+x myfile

    myfile would be like a version of calc that ignored any startup
    files and had an already defined global variable deg and a function
    Sin(x) which will return an approximation to the sine of x degrees.
    The invocation of myfile may be followed by other options (since
    the first line in the script has only flagged options) and/or calc
    commands as in:

            ./myfile -c read alpha '; define f(x) = Sin(x)^2'

    (The quotation marks avoid shell interpretation of the semicolon and
    parentheses.)

    (4) The old -S syntax for executable scripts implied the -s flag so that
    arguments in an invocation like

            ./myfile alpha beta

    are passed to calc; in this example argv(0) = 'alpha', argv(1) =
    'beta'.  This has been changed in two ways: an explicit -s is required
    in the first line of the script and then the arguments passed in the
    above example are argv(0) = 'myfile', argv(1) = 'alpha', argv(1) = 'beta'.

    In an ordinary command line, "-s" indicates that the shell words
    after the one in which "-s" occurred are to be passed as arguments
    rather than commands or options.  For example:

            calc "-q -s A = 27;" alpha beta

    invokes calc with the q-flag set, one command "A = 27;", and two arguments.

    (5) Piping to calc may be followed by calc becoming interactive.
    This should occur if there is no -p flag but -i is specified, e.g.:

            cat beta | calc -i -f alpha

    which will do essentially the same as:

            calc -i -f alpha -f beta

    (6) The read and help commands have been  changed so that several
    files may be referred to in succession by separating their names
    by whitespace.  For example:

            ; read alpha beta gamma;

    does essentially the same as:

            ; read alpha; read beta; read gamma;

    This is convenient for commands like:

            calc read file?.cal

    when file?.cal expands to something like file1.cal file2.cal file3.cal:

            myfiles='alpha beta gamma'
            calc read $myfiles

    or for C-shell users:

            set myfiles=(alpha beta gamma)
            calc read $myfiles


    (7) The -once option for read has been extended to -f.  For example,

            calc -f -once alpha

    will ignore alpha if alpha has been read in the startup files.  In a
    multiple read statement, -once applies only to the next named file.
    For example

            ; read -once alpha beta -once gamma;

    will read alpha and gamma only if they have not already been read,
    but in any case, will read beta.

    (8) A fault in the programming for the cd command has been corrected
    so that specifying a directory by a string constant will work.  E.g:

            ; cd "my work"

    should work if the current directory has a directory with name "my work".

    (9) new functions bernoulli(n) and euler(n) have been defined to
    return the Bernoulli number and the Euler number with index n.
    After evaluation for an even positive n, this value and these for
    smaller positive even n are stored in a table from which the values
    can be reread when required.  The memory used for the stored values
    can be freed by calling the function freebernoulli() or freeeuler().

    The function catalan(n) returns the catalan number with index n.
    This is evaluated using essentially comb(2*n, n)/(n+1).

    (10) A function sleep(n) has been defined which for positive n calls
    the system function sleep(n) if n is an integer, usleep(n) for other
    real n.  This suspends operation for n seconds and returns the null
    value except when n is integral and the sleep is interrupted by a
    SIGINT, in which case the remaining number of seconds is returned.

    (11) The effect of config("trace", 8) which displays opcodes of
    functions as they are successfully defined has been restricted to
    functions defined with explicit use of "define".  Thus, it has been
    deactivated for the ephemeral functions used for evaluation of calc
    command lines or eval() functions.

    (12) The functions digit(), digits(), places() have been extended to
    admit an optional additional argument for an integral greater-than-one
    base which defaults to 10.  There is now no builtin limit on the
    size of n in digit(x, n, b), for example, digit(1/7, -1e100) which
    would not work before can now be handled.

    (13) The function, digits(x), which returns the number of decimal
    digits in the integer part of x has been changed so that if abs(x) <
    1, it returns 0 rather than 1.  This also now applies to digits(x,b).

    (14) Some programming in value.c has been improved.  In particular,
    several occurrences of:

            vres->v_type = v1->v_type;
            ...
            if (v1->v_type < 0) {
                    copyvalue(v1, vres);
                    return;
            }

    have been replaced by code that achieves exactly the same result:

            vres->v_type = v1->v_type;
            ...
            if (v1->v_type < 0)
                    return;

    (15) Some operations and functions involving null-valued arguments
    have been changed so that they return null-value rather than "bad
    argument-type" error-value.  E.g. null() << 2 is now null-valued
    rather than a "bad argument for <<" error-value.

    (16) "global" and "local" may now be used in expressions.  For example:

            ; for (local i = 0; i < 5; i++) print i^2;

    is now acceptable, as is:

            ; define f(x = global x) = (global x = x)^2;

    which breaks wise programming rules and would probably better be handled
    by something like:

            ; global x
            ; define f(t = x) = (x = t)^2;

    Both definitions produce the same code for f.  For non-null t, f(t)
    returns t^2 and assigns the value of t to x;  f() and f(t) with null t
    return x^2.

    Within expressions, "global" and "local" are to be followed by just one
    identifier.  In "(global a = 2, b)" the comma is a comma-operator; the
    global variable a is created if necessary and assigned the value 2, the
    variable b has to already exist.   The statement "global a = 2, b" is
    a declaration of global variables and creates both a and b if they
    don't already exist.

    (18) In a config object, several components have been changed from
    long to LEN so that they will now be 32 bit integers for machines with
    either 32 or 64-bit longs.  In setting such components, the arguments
    are now to less than 2^31.  Before this change:

            ; config("mul2", 2^32 + 3)

    would be accepted on a 64-bit machine but result in the same as:

            ; config("mul2", 3)


The following are the changes from calc version 2.11.2t0 to 2.11.2t1.0:

    Fixed a bug whereby help files are not displayed correctly on
    systems such as NetBSD 1.4.1.  Thanks to a fix from Jakob Naumann.

    Changed Email addresses to use asthe.com.  Changed URLs to use
    www.isthe.com.  NOTE: The Email address uses 'asthe' and the web
    site URL uses 'isthe'.

NOTE:   calc-bugs Email address no longer in use
NOTE:   calc-contrib Email address no longer in use
NOTE:   calc-tester-request Email address no longer in use

    Replaced explicit Email addresses found this file with the <user at
    site dot domain> notation to reduce the potential for those folks
    to be spammed.

    The Makefile attempts to detect the existence of /dev/urandom with -e
    instead of the less portable -c.

    Misc Makefile fixes.


The following are the changes from calc version 2.11.1t3 to 2.11.1t4:

    Removed non-portable strerror() tests (3715, 3724 and 3728) from
    calc/regress.cal.

    Fixed missing strdup() from func.c problem.

    Fixed a problem that would have come up on a very long #! command line
    if the system permitted it.


The following are the changes from calc version 2.11.1 to 2.11.1t2.2:

    Placed calc under version 2.1 of the GNU Lesser General Public License.

        The calc commands:

            help copyright
            help copying
            help copying-lgpl

        should display the generic calc copyright as well as the contents
        of the COPYING and COPYING-LGPL files.

        Those files contain information about the calc's GNU Lesser General
        Public License, and in particular the conditions under which you
        are allowed to change it and/or distribute copies of it.

    Removed the lint facility from the Makefile.  Eliminated Makefile
    variables: ${LCFLAGS}, ${LINT}, ${LINTLIB} and ${LINTFLAGS}.
    Removed the lint.sed file.

    Cleaned up help display system.  Help file lines that begin with
    '##' are not displayed.

    Calc source and documentation now uses these terms:

        *.cal files     calc resource file
        *.a files       calc binary link library
        #! files        calc shell script

    Renamed 'help stdlib' to 'help resource'.   The 'help stdlib' is
    aliased to 'help resource' for arg compatibility.

    Renamed config("lib_debug") to config("resource_debug").
    The config("lib_debug") will have the same effect as
    config("resource_debug") for backward compatibility.

    Renamed the source sub-directory lib to cal.  The default $CALCPATH
    now uses ./cal:~/cal (instead of ./lib:~/lib).  Changed LIB_PASSDOWN
    Makefile variable to CAL_PASSDOWN.

    Fixed misc compile warnings and bugs.

    Fixed problem of incorrect paths in the formation of installed
    calc shell scripts.

    Changed the recommended Comqaq cc compile to be -std0 -fast -O4 -static.

    Fixed a problem related to asking for help for a non-existent file.

    Added ./.calcinit to the default calcrc.

    Added cscript/README and help cscript to document the calc shell
    script supplied with calc.


The following are the changes from calc version 2.11.0t10 to 2.11.0t11:

    Misc code cleanup.  Removed dead code.  Removed trailing whitespace.
    Fixed whitespace to make the best use of 8 character tabs.

    Fixed some bugs relating to '// and %' in combination with some
    of the rounding modes based on a patch from Ernest Bowen
    <ernie at turing dot une dot edu dot au>.

    A patch from Klaus Alexander Seistrup <klaus at seistrup dot dk>, when
    used in combination with the GNU-readline facility, will prevent
    it from saving empty lines.

    Minor typos fixed in regress.cal

    Added 8500 test series and test8500.cal to perform more extensive
    tests on // and % with various rounding modes.

    The 'unused value ignored' messages now start with Line 999: instead
    of just 999:.

    Fixed the long standing issue first reported by Saber-C in the
    domul() function in zmil.c thanks to a patch by Ernest Bowen
    <ernie at turing dot une dot edu dot au>.

    Added zero dimensional matrices.  A zero dimensional matrix is defined as:

        mat A[]   or    A = mat[]

    Updated the help/mat file to reflect the current status of matrices
    including zero dimensional matrices.

    Added indices() builtin function as written by Ernest Bowen <ernie
    at turing dot une dot edu dot au> developed from an idea of Klaus
    Seistrup <klaus at seistrup dot dk>.  See help/indices for details.

    Fixed a number of insure warnings as reported by Michel van der List
    <vanderlistmj at sbphrd dot com>.

    Fixed a number of help file typos discovered by Klaus Alexander
    Seistrup <klaus at seistrup dot .dk>.

    Removed REGRESS_CAL as a Makefile variable.

    Added calcliblist and calcliblistfmt utility Makefile rules to allow
    one to print the list of distribution files that are used (but not
    built) to form either the libcalc.a or the libcustcalc.a library.

    Added a patch from <Randall.Gray at marine dot csiro dot au> to make
    ^D terminate, but *only* if the line it is on is completely empty.
    Removed lib/altbind and removed the CALCBINDINGS Makefile variable.

    A new config("ctrl_d") value controls how the ``delete_char'', which
    by default is bound to ^D (Control D), will or will not exit calc:

        config("ctrl_d", "virgin_eof")

            If ^D is the only character that has been typed on a line,
            then calc will exit.  Otherwise ^D will act according to the
            calc binding, which by default is a Emacs-style delete-char.

            This is the default mode.

        config("ctrl_d", "never_eof")

            The ^D never exits calc and only acts according calc binding,
            which by default is a Emacs-style delete-char.

            Emacs purists may want to set this in their ~/.calcrc startup file.

        config("ctrl_d", "empty_eof")

            The ^D always exits calc if typed on an empty line.  This
            condition occurs when ^D either the first character typed,
            or when all other characters on the line have been removed
            (say by deleting them).

            Users who always want to exit when ^D is typed at the beginning
            of a line may want to set this in their ~/.calcrc startup file.

        Note that config("ctrl_d") apples to the character bound to each
        and every ``delete_char''.  So if an alternate binding it setup,
        then those char(s) will have this functionality.

    Updated help/config and help/mode, improved the readability and
    fixed a few typos.  Documented modes, block formats and block bases
    ("mode", "blkfmt" & "blkbase") that were previously left off out of
    the documentation.

    The config("blkbase") and config("blkfmt") values return strings
    instead of returning integers.  One cannot use integers to set
    these values, so returning integers was useless.

    Applied the dangling name fix from Ernest Bowen
    <ernie at turing dot une dot edu dot au>.

    Show func prints function on order of their indices, and with
    config("lib_debug") & 4 == 4  some more details about the functions
    are displayed.

    Fixed another ``dangling name'' bug for when the object types list
    exceeded 2000.

    Fixed a bug related to opening to a calc session:

        define res_add(a,b) = obj res {r} = {a.r + b.r};
        ...
        obj res A = {1,2}. obj res B = {3,4}

    A hash of an object takes into account the object type.  If X and Y
    are different kinds of objects but have the same component values,
    they will probably return different rather than the same values for
    hash(X) and hash(Y).

    Added support for config("ctrl_d") to the GNU-readline interface
    as written by Klaus Alexander Seistrup <klaus at seistrup dot dk>.

        Currently, the config("ctrl_d", "virgin_eof") is not fully
        supported.  Under GNU-readline, it acts the same way as
        config("ctrl_d", "empty_eof").  Emacs users may find this
        objectionable as ``hi^A^D^D^D'' will cause calc to exit due to
        the issuing of one too many ^D's.

        Emacs users may want to put:

            config("ctrl_d", "never_eof"),;

        into their ~/.calcrc startup files to avoid this problem.

    Made misc documentation fixes.

    Fixed the make depend rule.

    Applied Ernest Bowen's <ernie at turing dot une dot edu dot au>
    complex function power(), exp() and transcendental function patch:

        Calc will return a "too-large argument" error-value for exp(x,
        epsilon) if re(x) >= 2^30 or if an estimate indicates that the
        result will have absolute value greater than 2^2^30 * epsilon.
        Otherwise the evaluation will be attempted but may fail due to
        shortage of memory or may require a long runtime if the result
        will be very large.

        The power(a, b, epsilon) builtin will return a "too-large result"
        if an estimate indicates that the result will have absolute value
        that is > 2^2^30 * epsilon.  Otherwise the evaluation will be
        attempted but may fail due to shortage of memory or may require
        a long runtime if the result will be very large.

        Changes have been made to the algorithms used for some special
        functions sinh(), cosh(), tanh(), sin(), cos(), etc., that make
        use of exp().  In particular  tanh(x)  is now much faster and
        doesn't run out of memory when x is very large - the value to
        be returned is then 1 to a high degree of accuracy.

        When the true value of a transcendental function is 1, as is
        cos(x) for x == 0, calc's version of the function will now return
        1 rather than the nearest multiple of epsilon.  E.g. cos(0, 3/8)
        no longer returns 9/8.

        The restriction of abs(n) < 1000000 on scale(x, n) has been
        removed.  The only condition n now has to satisfy for calc to
        attempt the operation is  n < 2^31, the same as for calc to
        attempt x << n and x^n.

        Changed root(x,n) so that when x is negative and n is odd it
        returns the principal complex n-th root of x rather than -1, e.g.
        root(-1,3) now returns -.5+.8660...i.

        Changed power(a,b) to permit a to be negative when b is real.
        E.g. power(-2,3) will now return 8 rather than cause a "negative
        base" error.

        Fixed several improper free and link problems in the comfunc.c code.

    Removed BOOL_B64 symbol from Makefile.

    The following config values return "true" or "false" strings:

            tilde  tab  leadzero  fullzero  blkverbose  verbose_quit

        These config values can still be set with same boolean strings
        ("on", "off", "true", "false", "t", ...) as well as via the
        numerical values 0 (for "false") and non-0 (for "true"), however.

    Added -s to the calc command line.  The -s flag will cause unused
    args (args after all of the -options on the command line) to remain
    as unevaluated strings.

    If calc is called with -s, then the new function argv() will return
    the number of strings on the command line.  Also argv(n) will return
    the n-th such string or null is no such string exists.

    Calc now handles calc shell scripts.  A calc shell script is an
    executable file that starts with:

            #!/usr/local/bin/calc -S

        Where ``/usr/local/bin/calc'' is the path to the calc binary.
        Additional -options may be added to the line, but it MUST
        start with -S.  For example, the executable file ``plus''
        contain the following:

            #!/usr/local/bin/calc -S -e
            /*
             * This is a simple calc shell script to add two values
             */
            print eval(argv(0)) + eval(argv(1));

        then the following command:

            ./plus 23 'pi(1e-5)'

        will print:

            26.14159

    If calc is called with -S as the first arg, then calc will assume that
    it is being called from a #! calc shell script file.  The -S implies
    the -s flag.  If -i is not given, -S also implies -d and -p.

    Fixed the problem with non-literal string type checking for the
    C printf-like functions.  Able to determine if "%ld" or "%lld"
    is appropriate for printing of 64 bit long longs by way of the C
    symbol L64_FORMAT in the longlong.h header file.

    The following lines are treated as comments by calc:

        #! this is a comment
        # this is a comment
        #       this is a comment
        #
        # The lone # above was also a comment
        ## is also a comment

    Improved how calc makes changes to file descriptor interactive state.
    Moved state changing code to calc_tty() and orig_tty() in lib_calc.c.
    The libcalc_call_me_last() function will restore all changed descriptor
    states that have not already been restored.

    Added the following read-only config values:

        config("program")       path to calc program or calc shell script
        config("basename")      basename of config("program")
        config("version")       calc version string


The following are the changes from calc version 2.11.0t8.9.1 to 2.11.0t9.4.5:

    The config("verbose_quit") will control the printing of the message:

            Quit or abort executed

        when a non-interactive ABORT, QUIT or EXIT is encountered.  By default,
        config("verbose_quit") is TRUE and the message is printed.  If one does:

            config("verbose_quit", 0)

        the message is disabled.

    Added 8400 regression test set and test8400.cal to test the new
    quit and config("verbose_quit") functionality.

    Fixed the BigEndian BASEB==16 regression bugs by correctly swapping
    16 bit HALFs in a 64 bit value (such as a 64 bit file pointer).

    Added calclevel() builtin to calculation level at which it is called.

    Added help/calclevel and help/inputlevel help files.

    Removed regression tests 951 and 5984 so that the regress test will
    run in non-interactively / without a TTY such as under Debian's
    build daemon.

    The eval(str) builtin will return an error-value rather than cause
    an execution error str has a scan-error.

    Declarations are permitted to end with EOF as well as a newline or ';'.

    When prompt() occurs while reading a file, it will take input from
    the terminal rather than taking it from a file.  For example:

            /* This demonstrates the use of prompt() and some other things  */
            config("verbose_quit", 0);
            define getnumber() {
                local x;
                for (;;) {
                    x = eval(prompt(">>> "));
                    if (isnum(x))
                        return x;
                    print "Not a number! Try again";
                }
            }
            print "This will display the sqrt of each number you enter";
            print "Enter quit to stop";
            for (;;) {
                print sqrt(getnumber());
            }
            print "Good bye";

        Comments entered at input terminal level may be spread over several
        lines.  For example:

            /*
             * Assume that this calc script is called: comment.cal
             * Then these commands now work:
             *  cat comment.cal | calc
             *  calc < comment.cal
             */
            print "Hello";

    Added:

        -D calc_debug[:lib_debug:[user_debug]]

    to set the initial value of config("calc_debug"), config("lib_debug")
    and config("user_debug").

    The : separated strings of -D are interpreted as signed 32 bit values.
    After an optional leading sign a leading zero indicates octal
    conversion, and a leading ``0x'' or ``0X'' hexadecimal conversion.
    Otherwise, decimal conversion is assumed.

    Reordered the config structure moving calc_debug ahead of lib_debug.

    Added bits 4 and 5 to config("calc_debug"):

        4       Report on changes to the state of stdin as well as changes
                to internal variables that control the setting and restoring
                of stdin.

        5       Report on changes to the run state of calc.

    Fixed portability issue in seed.c relating to /dev/urandom and ustat.

    Added a fix from Martin Buck <mb at netwings dot ch> to detect when
    calc aborts early instead of completing the regression test.
    Now 'make chk' will require the last line of calc output to
    end in the string ``Ending regression tests''.

    Added a patch from Martin Buck <mb at netwings dot ch> to allow use of
    GNU-readline.  Note that GNU-readline is not shipped with calc.
    His patch only provides the hooks to use it.  One must comment out:

            USE_READLINE=
            READLINE_LIB=
            READLINE_INCLUDE=

        and comment in:

            USE_READLINE= -DUSE_READLINE
            READLINE_LIB= -lreadline -lhistory
            READLINE_INCLUDE= -I/usr/include/readline

        in addition to pre-installing GNU-readline in your system to use
        this facility.

    Changed the "object already defined" math_error to a scanerror message.

    Removed the limit on the number of object types.

    Calc tarballs are now named calc-version.tar.gz and untar into
    a sub-directory called calc-version.

    Made a small change to declarations of static variables to reduce
    the internal opcodes needed to declare them.

    Fixed a permission problem on ranlib-ed *.a files that was reported
    by Michael Somos <somos at grail dot cba dot csuohio dot edu>.

    Added patch by Klaus Alexander Seistrup <klaus at seistrup dot dk>
    related to GNU-readline:

        + enable calc specific bindings in ~/.inputrc
        + save a copy of your session to disk and reload them next
          time you're using calc
        + only add a line to the history if it is different from
          the previous line

    Added the Makefile symbol HAVE_GETRUSAGE to determine if the
    system supports the getrusage() system call.

    Fixed the make depend code in the custom and sample Makefiles.

    Fixed how the help/builtin file is formed.  The help/Makefile is
    now given the name of the native C compiler by the top level Makefile.

    The include files are installed under INCDIRCALC (a new Makefile variable)
    which by default is ${INCDIR}/calc.  The INCDIR (also a new Makefile var)
    by default is /usr/local/include.  Include files previously installed
    directly under ${LIBDIR} will be removed.

    Added the piforever() function to lib/pi.cal.  It was written by
    Klaus Alexander Seistrup <klaus at seistrup dot dk> and was inspired by
    an algorithm conceived by Lambert Meertens.  (See also the ABC
    Programmer's Handbook, by Geurts, Meertens & Pemberton, published
    by Prentice-Hall (UK) Ltd., 1990.)  The piforever() function prints
    digits of pi for as long as your memory and system uptime allows.  :-)

    Fixed the URLs found throughout the source and documentation which did
    not and in /, but should for performance and server load reasons.

    Cleaned up and improved handling of "mat" and "obj".  The comma in:

            mat A[2], B[3];

        is changed to whatever is appropriate in the context:

            + comma operator
            + separator of arguments in a function call
            + separator of arguments in a definition
            etc.

        The expression (mat A[2]), B[3] returns B[3], assuming B already
        exists as something created by a statement like: global mat B[4].

        What used to be done by the expression:

            mat A[2], B[3]

        will now require something like:

            mat A[2], mat B[3]  or      A = mat[2], B = mat[3]

        For example, if obj point and obj pair are known types, the
        following is now allowed:

            L = list(mat[2], mat[3], obj point, obj pair)

        As another example, the following is allowed:

            define f(a = mat[2] = {3,4}) = 5 * a;

        as well as the following:

            obj point {x,y}, PP = obj pair {A,B} = {obj point, obj point}

        which creates two object types at compile time and when executed,
        assigns a pair-object value to a variable PP.

    Fixed a bug whereby a for loop would behave incorrectly.  For example:

            config("trace", 2),
            global x;
            define f() {for ( ; x > 0; x--) {print x;}}
            x = 5, f()

        will stop after printing 1 instead of looping forever.

    Added values l_format, which when CHECK_L_FORMAT is defined ahead
    of including longlong.h will help detect when a system can deal with
    'long long' but not '%lld' in printf.  If a system with 'long long'
    uses '%ld' to print a 64 bit value, then l_format will be > 0;
    otherwise if "%lld" is required, l_format will be < 0.

    Added HAVE_STRDUP Makefile variable as well as the have_strdup.c
    program that forms the have_strdup.h file.  The have_strdup.h file
    will define HAVE_STRDUP is the system has strdup().  If HAVE_STRDUP
    is not defined, then calc will use calc_strdup() to simulate
    the real strdup() function.

    Calc no longer makes use of sys_errlist and sys_nerr.  Some systems
    no longer support these values (even though they should from a
    legacy prospective).  Calc now relies on the fact that strerror()
    will return NULL of no such system error exists.  System errors >=
    10000 will be considered calc errors instead.  The Makefile symbol
    ERRNO_DECL has gone away as well as calc_errno.c and calc_errno.h.

    System errors that are are not known to to the libc strerror()
    function, will now print (via the strerror() calc builtin function)
    something such as:

            Unknown error 9999

    Fixed some insure code inspection tool issues that were discovered
    and investigated by Michel van der List <vanderlistmj at sbphrd dot com>.

    Made an effort to ensure that the v_subtype of VALUES are initialized
    to V_NOSUBTYPE through out the source code.

    Established a separate calc-bugs address from the calc-tester
    mailing list.  Using anti-spam address forms in order to try and
    stay under the radar of spammers as much as one can do so.


The following are the changes from calc version 2.11.0t8 to 2.11.0t8.9:

    Moved 'wishlist' enhancements from the help/todo file to a new
    help/wishlist file.  Ordered, by priority, help/todo items into
    Very High, High and Medium priority items.

    The BUGS file now has a 'bugs' section as well as a 'mis-features'
    section.

    Improved how calc internally dealt with reading EOF or '\0' characters.

    Calc now allows multiple defines to occur on the same line:
    (Thanks goes to Ernest Bowen <ernie at turing dot une dot edu dot au>)

        define f8300(x) = x^2; define g8300(x) = 1 - x;

    Improved calc's ability to deal with and recover from errors.

    Added inputlevel() builtin to return the input processing level.
    In an interact mode, inputlevel() returns 0.  When directly reading
    a calc script, inputlevel() returns 1.  When reading a script which
    in turn reads another script, inputlevel() returns 2.  etc...

    If $CALCRC has more than one file as in file1:file2 and an error
    occurs in file1, then calc -c will not read file2.

    Fixed some of the old Email addresses found in calc documentation.

    Added HAVE_USTAT, HAVE_GETSID, HAVE_GETPGID, HAVE_GETTIME, HAVE_GETPRID
    and HAVE_URANDOM symbols to the Makefile.  These symbols, along with
    have_ustat.c, have_getsid.c, have_getpgid.c, have_gettime.c and
    have_getprid.c form: have_ustat.h, have_getsid.h, have_getpgid.h,
    have_gettime.h, have_getprid.h and have_urandom.h which in turn
    are used by pseudo_seed() in seed.c to determine what types of
    system services can be used to form a pseudo-random seed.

    Fixed the way calc -c will continue processing $CALCRC when errors
    are encountered.  Unless -d is also given, calc -c will report
    when calc is unable to open a $CALCRC file.

    Fixed the lower level make depend rules.

    Misc cleanup on the have_*.c support source files.

    Misc source file cleanup for things such as } else { style consistency.

    Fixed the basis for FNV-1 hashes.  Prior to this fix, the hash()
    builtin produced FNV hash values that did not match the FNV-1
    algorithm as specified in:

        http://www.isthe.com/chongo/tech/comp/fnv/index.html

    Removed an unused argument in the function getbody() in codegen.c.

    Encountering of EOF in getbody() will cause a scanerror rather then
    stop activity.  This will now result in a scanerror:

        echo 'define f(x) { ' > myfile
        calc -i read myfile

    A '{' at the start of a command and a later matching '}' surrounding zero
    or more statements (and possibly newlines) results in a function body to
    be "evaluated".   This permits another command to follow on the same
    line as the '}' as in:

                {display(5)} read something;
        and:
                {static a = 5} define f(x) = a + x;

    String constants can now be concatenated.  For example:

        s = "curds" ' and ' "whey";

    Added FNV hash to the regression test suite.

    Added Ernest Bowen's <ernie at turing dot une dot edu dot au> fix for the
    FNV regression test of the hash() builtin function.

    Added Ernest Bowen's <ernie at turing dot une dot edu dot au> patch to
    improve the way config("calc_debug").  Now the lower 4 bits of the
    config("calc_debug") parameter have the following meaning:

       n               Meaning of bit n of config("calc_debug")

       0       Outputs shell commands prior to execution.

       1       Outputs currently active functions when a quit instruction
               is executed.

       2       Some details of shs, shs1 and md5 hash states are included
               in the output when these are printed.

       3       When a function constructs a block value, tests are
               made that the result has the properties required for use of
               that block, e.g. that the pointer to the start of the
               block is not NULL, and that its "length" is not negative.
               A failure will result in a runtime error.

    Changed the meaning of (config("calc_debug") & 1) from only printing
    the shell commands (and pausing) while displaying help files into
    the printing of any shell command prior to execution.

    Documented the meaning of config("lib_debug"):

        n               Meaning of bit n of config("lib_debug")

        0       When a function is defined, redefined or undefined at
                interactive level, a message saying what has been done
                is displayed.

        1       When a function is defined, redefined or undefined during
                the reading of a file, a message saying what has been done
                is displayed.

        The value for config("lib_debug") in both oldstd and newstd is
        3, but if calc is invoked with the -d flag, its initial value
        is zero.  Thus, if calc is started without the -d flag, until
        config("lib_debug") is changed, a message will be output when a
        function is defined either interactively or during the reading
        of a file.

    Changed the calc lib files to reflect the new config("lib_debug")
    bit field meaning.  Calc lib files that need to print extra information
    should now do something such as:

        if (config("lib_debug") & 3) {
                print "obj xyz defined";
                print "funcA([val1 [, val2]]) defined";
                print "funcB(size, mass, ...) defined";
        }

    Fixed the help/custom_cal, help/new_custom, and help/copy files so
    that they contain the correct contents instead of the 'usage' file.

    Fixed problem with loss of bindings when calc -i args runs into
    an error while processing 'args' and drops into interactive mode
    without the terminal bindings being set.

    Added patch from Ernest Bowen to establish the abort command as
    well as to clarify the roles of quit and exit.  See the help/command
    file for details.

    Updated to some extend, the help/statement and help/command help
    files with new information about SHOW, QUIT, EXIT and ABORT.

    Added show sizes to pzasusb8.cal.

    Updated calc man page and help/usage file to reflect recent
    command line changes.

    Fixed a bug, reported by Michael Somos <somos at grail dot cba dot
    csuohio dot edu>, which prevented calc -m from being used.

    Fixed misc compiler warnings.


The following are the changes from calc version 2.11.0t7 to 2.11.0t7.5:

    Calc has some new command line flags / command line meaning:
    (Thanks goes to Ernest Bowen <ernie at turing dot une dot edu dot au>)

        -i      Go into interactive mode if possible.

        -c      Continue reading command lines even after an execution
                error has caused the abandonment of a line

        To understand the -i and -c effects, consider the following
        file (call it myfile.cal) which has deliberate errors in it:

            print 1;
            mat A[1] = {2,3};
            print 2;
            epsilon(-1);
            print 3;

        calc read myfile

            Reports an error on the 2nd line and exits; prints 1 only.

        calc -c read myfile

            Report errors on the 2nd and 4th lines and exits; prints 1,2 and 3.

        calc -i read myfile

            Report errors on the 2nd and gives you a prompt; prints 1 only.

        calc -i -c read myfile

            Report errors on the 2nd and 4th and gives you a prompt;
            prints 1, 2 and 3.

        cat myfile | calc

            Reports an error on the 2nd line and exits; prints 1 only.

        cat myfile | calc -c

            Report errors on the 2nd and 4th lines and exits; prints 1,2 and 3.

        Note that continuation refers to command lines, not to statements.  So:

            calc -c 'print "start"; mat A[1] = {2,3}; print "end";'

        since it contains no newline, the whole string is compiled,
        but execution is abandoned when the error is encountered and
        the string ``end'' is not printed.

        You can use your shell to supply newlines in your command line
        arguments.  For example in sh, ksh, bash:

            calc -c 'print "start";
            mat A[1] = {2,3};
            print "end";'

        will print both ``start'' and ``end''.  C-shell users can do:

            calc -c 'print "start"; \
            mat A[1] = {2,3}; \
            print "end";'

        however sh, ksh, bash will not see ``end'' printed because their
        shell will remove the internal newlines.

    Added display(n) builtin which does almost the same as config("display",n)
    except that rather than causing an execution with an out-of-range or
    bad-type argument type, it simply writes a message to stderr.  This
    also now happens to the errmax() builtin.

    Added qtime.cal to the standard calc library.

    Added another command line flag to calc:

        -d      Disable display of the opening title and config("lib_debug",0)

        The command:

            calc 'read qtime; qtime(2)'

        will output something like:

            qtime(utc_hr_offset) defined
            It's nearly ten past six.

        whereas:

            calc -d 'read qtime; qtime(2)'

        will just say:

            It's nearly ten past six.

    A call of errmax(-1) will prevent errcount from aborting calc.

    Add the function stoponerror(n) which, as the name implies, controls
    if calc stop on an error based on the value of n:

        n > 0   stop on error even if -c was given on the command line
        n == 0  if -c, continue, without -c, stop
        n < 0   continue on error, even if -c was given on the command line

    Calc compilation now stops at the first scanerror.

    Restored the feature where -p disables the printing of leading tabs
    as of config("tab",0) had been executed.  So using calc in a pipe:

        calc -p 2+17 | whey

    will write '19' instead of '\t19' to the whey command.

    Updated calc man page and help/usage file to reflect recent
    command line changes.

    Converted start_done into a general calc run state enum called
    run_state within the calc source.

    Removed README.OLD.

    Added the Makefile variable ${LCC} to invoke the local c compiler.
    By default, ${CC} also run the ${LCC} compiler.  The distinction is
    useful when using something such as purify.  In the case of ${LCC},
    only the local C compiler is invoked.  In the case of ${CC} a purify
    compile is invoked.  Only the source that must be compiled and run
    on the local machine use ${LCC}; everything else uses ${CC}.

    Fixed memory buffer related problem in eatstring() in token.c.

    Fixed memory leaks related to putenv().

    Fixed memory leaks related to srandom().

    Fixed compilation warnings and problems on BSDI.

    Removed ${CCMAIN} as a variable from the Makefile.  Now files
    use either ${CFLAGS} for general C source and ${ICFLAGS} for
    intermediate C source (e.g., special code for building hsrc files).

    The main calc URL is now:

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

    Misc calc man page fixes.


The following are the changes from calc version 2.11.0t1 to 2.11.0t6.3:

    Removed the makefile symbol MAIN.  Now forcing all functions to correctly
    be declared main.  To satisfy some old broken compilers, a return 0;
    (instead of an exit(0);) is used at the end of main().

    A few of files that were added to calc used 4 character indentation
    whereas most of calc uses 8 character indentation.  These imported
    sources have been changed to conform better with the calc style.

    Added the program calc_errno.c and the Makefile symbol ERRNO_DECL.
    If ERRNO_DECL is empty, calc_errno.c will try various ways to
    declare errno, sys_errlist and sys_nerr.  On success or when
    it gives up, calc_errno will output the middle of the calc_errno.h
    header file.  If ERRNO_DECL is  -DERRNO_NO_DECL, or -DERRNO_STD_DECL
    or -DERRNO_OLD_DECL then the Makefile will build the middle
    of the calc_errno.h header file without calc_errno.c's help.

    The func.c file now includes the constructed header file calc_errno.h
    to ensure that errno, sys_errlist and sys_nerr are declared correctly.

    Changed check.awk to be more 'old awk' friendly.

    Made some of the source a little more ++ friendly.  We are NOT
    porting calc to C++!  We will NOT support C++ compilation of calc.
    Calc will written ANSI C.  We just compiled with a suggestion from
    Love-Jensen, John <jlove-jensen at globalmt dot com> to make calc's version
    of C a little more to C++ compilers.  We are simply avoiding symbols
    such as new or try for example.

    Renamed README to README.OLD.  Renamed README.FIRST to README.
    Updated README, lib/README and BUGS to reflect new URLs and addresses.

    Added a HOWTO.INSTALL file.

    Reordered cc Makefile variable sets in the main Makefile.

    Fixed a bug in hnrmod() and applied a fix that was reported by Ernest
    Bowen <ernie at turing dot une dot edu dot au>.  Added regression tests
    1103 to 1112 to confirm the fix.

    Fixed a bug in version.c related to MINOR_PATCHs in both the
    empty and non-empty MINOR_PATCH cases.

    Fixed malloc and bad storage issues reported by Michel van der List
    <vanderlistmj at sbphrd dot com>.

    Fixed some problems related to path processing while opening files.
    Under extreme cases, an excessively long filename or CALCPATH value
    could create problems.  Placed guards in opensearchfile() function
    in input.c to catch these cases.

    Fixed cases were malloc failures were silently ignored in input.c.

    Eliminated the PATHSIZE limit and the PATHSIZE symbol.

    Added MAX_CALCRC to limit the length of the $CALCRC environment
    variable to 1024 chars.

    Fixed the magic number relating to the initial number of constants
    declared by initconstants().  It is now related to the length
    of the initnumbs[] NUMBER array.

    Added a 'Dec Alpha / Compaq Tru64 cc (non-gnu) compiler set'
    section to the main Makefile.

    Fixed a string handling bug discovered by Dr.D.J.Picton
    <dave at aps5 dot ph dot bham dot ac dot uk> in the custom demo code.

    Fixed a bug in the hnrmod() builtin that was discovered by
    Ernest Bowen <ernie at turing dot une dot edu dot au>.

    Added FORCE_STDC symbol.  When defined it will force __STDC__ like
    conditions.  Thus for compilers with as the Solaris cc compiler
    that are ANSI-like but still define __STDC__ as 0, one can use
    -DFORCE_STDC and make use of ANSI-like features.

    Removed the CCSHS symbol from the Makefile.  The shs.c and shs1.c
    files are now compiled with full ${CFLAGS}.

    The custom.c file is now compiled with full ${CFLAGS}.

    Rewrote command line / argument processing code.  Calc is now
    using getopt(3) argument processing.

    Fixed a memory leak related to converting strings to numbers
    in the str2q() function in qio.c.

    Fixed a problem with reading uninitialized memory in the
    v_subtype of a VALUE in the copyvalue() function in value.c.

    Fixed problems in func.c where temporary VALUEs were not
    having their v_type elements initialized.

    Fixed a memory leak in qpi() in qtrans.c.

    Fixed a memory leak in math_getdivertedio() in zio.c.

    Fixed a problem with points going beyond the end of allocated
    memory in addstring() in string.c.

    Fixed a memory leak in zgcdrem(), f_putenv(), zlog() and
    zlog10() in zfunc.c.

    Fixed a memory leak in zdiv() and zshift() in zmath.c.

    Fixed memory leaks in zsrand() in zrand.c.

    Fixed a memory leak in zsrandom1() in zrandom.c.  Fixed memory
    leaks associated with replacing the internal random state with
    another random state.

    Added seed() builtin to return a 64 bit seed for a
    pseudo-random generator.

    Added functionality from Ernest Bowen <ernie at turing dot une dot
    edu dot au> to permit nested "= {...}" assignments for lists as well
    as matrices and objects.  Now one can have a list, matrix or object,
    some of whose elements are lists, matrices or objects, to any depth
    of recursion, and assign values to any number of particular elements
    by an appropriate "initialization" expression.  For example:

        A = mat[2] = {list(1,2), list(3,4,list(5,6))};

    and then assign values to the 6 number elements by:

        A = {{7,8}, {9,10,{11,12}}};

    Closed files that were previously left open from test4600.cal
    as executed by regress.cal and from opening /dev/null by
    regress.cal itself.

    Fixed memory leaks from f_strprintf() and f_putenv() in func.c.

    The regress.cal test suite calls freeredc(), freestatics() and
    freeglobals() at the end of the test suite to free storage
    consumed during the regression.

    Added custom function custom("pzasusb8", n) and lib/pzasusb8.cal based on
    Ernest Bowen's diagnostic patch.

    Thanks to the efforts of Ernest Bowen <ernie at turing dot une dot
    edu dot au> and Dr.D.J.Picton <dave at aps5 dot ph dot bham dot ac
    dot uk>, a nasty endian-ness bug in the sha and sha1 hash functions
    that showed up on machines such as the Sparc was fixed.

    Added functionality from Ernest Bowen <ernie at turing dot une
    dot edu dot au> to give arguments as well as function names after
    definitions when config("lib_debug") >= 0.

    Removed if (config("lib_debug") >= 0) { ... } the ends of most
    of the calc library scripts because it was redundant with the
    new config("lib_debug") >= 0 functionality.  Some of the calc
    library still has a partial section because some useful
    additional information was being printed:

        chrem.cal       deg.cal      lucas_tbl.cal   randrun.cal
        mfactor.cal     mod.cal      poly.cal        seedrandom.cal
        surd.cal        varargs.cal

    Fixed ellip.cal so that its defined function does not conflict with
    the factor() builtin function.

    Fixed mod.cal so that a defined function does not conflict with
    the mod() builtin function.

    The regression test suite now reads in most calc libs.  A few
    libs are not read because they, by design, produce output
    when read even when config("lib_debug") is set to -1.

    Increased the maximum number of object types that one can define
    from 10 to 128.

    Added a patch from Ernest Bowen <ernie at turing dot une dot edu
    dot au> to correctly hash a V_STR value-type that has an \0 byte
    inside it.

    A patch from Ernest Bowen <ernie at turing dot une dot edu dot au> now
    defines special meaning to the first 2 bits of config("lib_debug"):

        bit 0 set => messages printed when input is from a terminal
        bit 1 set => messages printed when reading from a file

    The lib/regress.cal regression suite does:

        config("lib_debug", -4);

    to eliminate lib messages (both bit 0 and bit 1 are not set).

    Fixed misc compile warnings and notices.


The following are the changes from calc version 2.10.3t5.38 to 2.11.0t0:

    Fixed a few compile problems found under Red Hat 6.0 Linux.


The following are the changes from calc version 2.10.3t5.38 to 2.11.3t5.46:

    Fixed a bug discovered by Ernest Bowen related to matrix-to-matrix copies.

    Bitwise operations on integers have been extended so that negative
    integers are treated in the same way as the integer types in C.

    Some changes have been made to lib/regress.cal and lib/natnumset.cal.

    Removed V_STRLITERAL and V_STRALLOC string type constants and
    renumbered the V_protection types.

    Added popcnt(x, bitval) builtin which counts the number of
    bits in x that match bitval.

    Misc compiler warning fixes.

    Fixed improper use of putchar() and printf() when printing rationals
    (inside qio.c).

    Fixed previously reported bug in popcnt() in relation to . values.

    Calc man page changes per suggestion from Martin Buck
    <Martin-2.Buck at student dot uni-ulm dot de>.  The calc man page is
    edited with a few more parameters from the Makefile.

    Misc Makefile changes per Martin Buck <Martin-2.Buck at student dot
    uni-ulm dot de>.

    Removed trailing blanks from files.

    Consolidated in the Makefile, where the debug and check rules are found.
    Fixed the regress.cal dependency list.

    Make chk and check will exit with an error if check.awk detects
    a problem in the regression output.  (Martin Buck)

    Fixed print line for test #4404.

    Moved custom.c and custom.h to the upper level to fix unresolved symbols.

    Moved help function processing into help.c.

    Moved nearly everything into libcalc.a to allow programs access to
    higher level calc objects (e.g., list, assoc, matrix, block, ...).

    Renamed PATCH_LEVEL to MAJOR_PATCH and SUB_PATCH_LEVEL to MINOR_PATCH.
    Added integers calc_major_ver, calc_minor_ver, calc_major_patch
    and string calc_minor_patch to libcalc.a.  Added CALC_TITLE to hold
    the "C-style arbitrary precision calculator" string.

    The function version(), now returns a malloced version string
    without the title.

    Consolidated multiple SGI IRIX -n32 sections (for r4k, r5k and r10k)
    into a single section.


The following are the changes from calc version 2.10.3t5.34 to 2.10.3t5.37:

    Per request from David I Bell, the README line:

      I am allowing this calculator to be freely distributed for personal uses

    to:

      I am allowing this calculator to be freely distributed for your enjoyment

    Added help files for:

        address agd arrow dereference free freeglobals freeredc freestatics
        gd isptr mattrace oldvalue saveval & * -> and .

    Fixed blkcpy() and copy() arg order and processing.  Now:

        A = blk() = {1,2,3,4}
        B = blk()
        blkcpy(B,A)
        blkcpy(B,A)

    will result in B being twice as long as A.

    Since "make chk" pipes the regression output to awk, we cannot
    assume that stdout and stderr are ttys.  Tests #5985 and #5986
    have been removed for this reason.  (thanks to Martin Buck
    <Martin-2.Buck at student dot uni-ulm dot de> for this report)

    Fixed the order of prints in regress.cal.  By convention, a print
    of a test line happens after the test.  This is because function
    parsed messages occur after the function is parsed.  Also the
    boolean test will verify before any print statements.  Therefore
    a non-test line is tested and printed as follows:

        y = sha();
        print '7125: y = sha()';

    The perm(a,b) and comb(a,b) have been extended to arbitrary real a and
    integer b.

    Fixed a bug in minv().

    Moved string.c into libcalc.a.

    The NUMBER union was converted back into a flat structure.  Changes
    where 'num' and 'next' symbols were changed to avoid #define conflicts
    were reverse since the #define's needed to support the union went away.

    Removed trailing blanks from files.

    Ernest Bowen <ernie at turing dot une dot edu dot au> sent in the
    following patch which is described in the next 34 points:

    (0) In the past:

                    A = B = strcat("abc", "def");

        would store "abc" and "def" as literal strings never to be freed, and
        store "abcdef" once each for both A and  B.  Now the "abc" and "bcd"
        are freed immediately after they are concatenated and "abcdef" is stored
        only once, just as the number 47 would be stored only once for

                    A = B = 47;

        The new STRING structure that achieves this stores not only the
        address of the first character in the string, but also the "length"
        with which the string was created, the current "links" count, and
        when links == 0 (which indicates the string has been freed) the
        address of the next freed STRING.  Except for the null string "",
        all string values are "allocated"; the concept of literal string
        remains for names of variables, object types and elements, etc.

    (1) strings may now include '\0', as in A = "abc\0def".  In normal printing
        this prints as "abc" and strlen(A) returns 3, but its "real" length
        of 7 is given by size(A). (As before there is an 8th zero character
        and sizeof(A) returns 8.)

    (2) If A is an lvalue whose current value is a string of size n, then
        for 0 <= i < n, A[i] returns the character with index i as an addressed
        octet using the same structure as for blocks, i.e. there is no
        distinction between a string-octet and a block-octet.  The same
        operations and functions can be used for both, and as before, an octet
        is in some respects a number in [0,256) and in others a one-character
        string.  For example, for A = "abc\0def" one will have both A[0] == "a"
        and A[0] == 97.  Assignments to octets can be used to change
        characters in the string, e.g. A[0] = "A", A[1] = 0, A[2] -= 32,
        A[3] = " " will change the above A to "A\0C def".

    (3) "show strings" now displays the indices, links, length, and some or all
        of the early and late characters in all unfreed strings which are values
        of lvalues or occur as "constants" in function definitions,
        using "\n", "\t", "\0", "\252", etc. when appropriate.  For example,
        the string A in (1) would be displayed as in the definition there.
        Only one line is used for each string.  I've also changed the
        analogous "show numbers" so that only some digits of numbers that
        would require more than one line are displayed.

    (4) "show literals" is analogous to "show constants" for number "constants"
        in that it displays only the strings that have been introduced by
        literal strings as in A = "abc".  There is a major difference between
        strings and numbers in that there are operations by which characters
        in any string may be changed.  For example, after A = "abc",
        A[0] = "X" changes A to "Xbc".  It follows that if a literal string
        is to be constant in the sense of never changing, such a character-
        changing operation should never be applied to that string.

        In this connection, it should be noted that if B is string-valued, then

                            A = B

        results in A referring to exactly the same string as B rather than to
        a copy of what is in B.  This is like the use of character-pointers in
        C, as in

                            char *s1, *s2;
                            s1 = "abc";
                            s2 = s1;

        To achieve the effect of

                            s2 = (char *) malloc(4);
                            strcpy(s2, s1);

        I have extended the str() function to accept a string as argument.  Then

                            A = str(B);

        will create a new string at a different location from that of B but
        with the same length and characters.  One will then have A == B,
        *A == *B, but &*A != &*B, &A[0] != &B[0].

        To assist in analyzing this sort of thing, I have defined a links()
        function which for number or string valued argument returns the number
        of links to the occurrence of that argument that is being referred to.
        For example, supposing "abc" has not been used earlier:

                            ; A = "abc"
                            ; links(A)
                                    2
                            ; links(A)
                                    1

        The two links in the first call are to A and the current "oldvalue";
        in the second call, the only link is to A, the oldvalue now being 2.


    (5) strcat(S1, S2, ...) works as before; contribution of a string stops when
        '\0' is encountered.  E.g.

                    strcat("abc\0def", "ghi")

        will return "abcghi".

    (6) For concatenation of full strings I have chosen to follow
        some other languages (like Java, but not Mathematica which uses "<>")
        and use "+" so that, e.g.

                    "abc\0def" + "ghi"

        returns the string "abc\0defghi".  This immediately gives obvious
        meanings to multiplication by positive integers as in

                    2 * "abc" = "abc" + "abc" = "abcabc",

        to negation to reverse as string as in

                    - "abc" = "cba",

        to multiplication by fractions as in

                    0.5 * "abcd" = "ab",

        (where the length is int(0.5 * size("abcd")), and finally, by combining
        these to

                     k * A    and      A * k

        for any real number k and any string A.   In the case of k == 1, these
        return a new string rather than A itself.  (This differs from
        "" + A and A + "" which return A.)

    (7) char(x) has been changed so that it will accept any integer x or octet
        as argument and return a string of size one with character value
        x % 256.  In the past calc has required 0 <= x < 256; now negative
        x is acceptable; for example, 1000 * char(-1) will now produce the
        same as 1000 * "\377" or 1000 * "\xff".

    (8) For a string s, test(s) now returns zero not only for the null string
        "" but also for a string all of whose characters are '\0'.

    (9) Similarly <, <=, etc. now compare all characters including occurrences
        of '\0' until a difference is encountered or the end of a string is
        reached.  If no difference is encountered but one string is longer than
        the other, the longer string is considered as greater even if the
        remaining characters are all '\0'.

    (10) To retain the C sense of comparison of null-terminated strings I have
         defined strcmp(S1, S2), and then, for completeness, strncmp(S1, S2, n).
         For similar reasons, strcpy(S1, S2) and strncpy(S1, S2, n) have been
         defined.

    (11) For strings, I have defined | and & as bitwise "or" and "and"
         functions, with S1 | S2 having the size of the larger of S1 and S2,
         S1 & S2 having the size of the smaller of S1 and S2.  By using, say,
         4-character strings, one can simulate a C integral type so far as the
         | and & operations are concerned.   It then seemed appropriate to
         use the operator ~ for a "bitwise complement" as in C.  Thus I have
         defined ~s for a string s to be the string of the same size as s
         with each character being complemented by the C ~ operation.

    (12) For boolean algebra work on strings it is convenient also to have
         the bitwise xor and setminus binary operations.  Using C's '^' for xor
         would be confusing when this is used elsewhere for powers, so I
         decided to use ~.  For setminus, I adopted the commonly used '\'.
         Strings of fixed size n can now be used for a boolean algebra
         structure with 8 * n elements.  The zero element is n * char(0),
         the unity is n * char(-1), and one have all of the usual laws like
         A & (B | C) == A & B | A * C,  A \ B = A & ~B, etc.

    (13) Having extended the bitwise operations for strings, it was appropriate
         to do the same for integers.  Definitions of the binary ~ and \
         operations for non-negative integers are straightforward.  For
         the unary ~ operation, I decided to do what C does with integer
         types, and defined ~N to be -N - 1.  With the appropriate extensions of
         |, &, \ and the binary ~, one gets in effect the boolean algebra of
         finite sets of natural numbers and their complements, by identifying
         the set with distinct integer elements i_1, i_2, ... with the integer

                    2^i_1 + 2^i_2 + ...

         For ~N for non-integer real N, I have simply used -N.  There is some
         logic in this and it is certainly better than an error value.
         I have not defined the binary operations |, &, ~, \ for non-integral
         arguments.

         The use of ~N in this way conflicts with calc's method of displaying
         a number when it has to be rounded to config("display") decimals.
         To resolve this, my preference would be to replace the printing of
         "~" as a prefix by a trailing ellipsis "...", the rounding always
         being towards zero.  E.g. with config("display", 5), 1/7 would print
         as ".14285..." rather than "~.14285".   The config("outround")
         parameter would determine the type of rounding only for the
         equivalent of config("tilde", 0).

    (14) For objects, users may create their own definitions for binary |,
         &, ~ and \ with xx_or, xx_and, xx_xor, xx_setminus functions.
         For unary ~ and \ operations, I have used the names xx_comp and
         xx_backslash.

    (15) For the obviously useful feature corresponding to cardinality of a
         set, I have defined #S for a string S to be the number of nonzero bits
         in S.   For a degree of consistency, it was then appropriate to
         define #N for a nonnegative integer N to be the number of nonzero bits
         in the binary representation of N.  I've extended this to arbitrary
         real N by using in effect #(abs(num(N))).  I feel it is better to make
         this available to users rather than having #N invoke an error message
         or return an error value.  For defining #X for an xx-object X, I
         have used the name xx_content to suggest that it is appropriate for
         something which has the sense of a content (like number of members of,
         area, etc.).

    (16) Having recognized # as a token, it seemed appropriate to permit its
         use for a binary operation.  For real numbers x and y I have defined
         x # y to be abs(x - y).  (This is often symbolized by x ~ y, but it
         would be confusing to have x ~ y meaning xor(x,y) for strings and
         abs(x-y) for numbers.)  Because '#' is commonly called the hash symbol,
         I have used xx_hashop to permit definition of x # y for xx-objects.

    (17) For a similar reason I've added one line of code to codegen.c so that
         /A returns the inverse of A.

    (18) Also for a list L, +L now returns the sum of the elements of L.  For
         an xx object A, +A requires and uses the definition of xx_plus.

    (19) I have given the unary operators ~, #, /, \, and except at the
         beginning of an expression + and -, the same precedence with
         right-to-left associativity.  This precedence is now weaker than
         unary * and &, but stronger than binary & and the shift and power
         operators.  One difference from before is that now

                            a ^ - b ^ c

         evaluates as a ^ (- (b ^ c)) rather than a ^ ((- b) ^ c).


    (20) For octets o1, o2, I've defined o1 | o2, o1 & o2, o1 ~ o2, ~o1 so
         that they return 1-character strings.  #o for an octet o returns the
         number of nonzero bits in o.

    (21) For substrings I've left substr() essentially as before, but
         for consistency with the normal block/matrix indexing, I've extended
         the segment function to accept a string as first argument.  Then

                    segment(A, m, n)

         returns essentially the string formed from the character with index m
         to the character with index n, ignoring indices < 0 and indices >=
         len(A); thus, if m and n are both in [0, size(A))
         the string is of length abs(m - n) + 1, the order of the characters
         being reversed if n < m.  Here the indices for a list of size len are
         0, 1, ..., len - 1.  As it makes some sense, if 0 <= n < size(A),

                    segment(A, n)

         now returns the one-character string with its character being that with
         index n in A.  (I've made a corresponding modification to the segment
         function for lists.)  Some examples, if A = "abcdef",

                    segment(A,2,4) = "cde",

                    segment(A,4,2) = "edc",

                    segment(A,3) = "d",

                    segment(A, -2, 8) = "abcdef",

                    segment(A,7,8) = "".

    (22) As essentially particular cases of segment(), I've defined
         head(A, n) and tail(A, n) to be the strings formed by the first
         or last abs(n) characters of A, the strings being4]5O~? reversed '
         if n is negative.   I've changed the definitions of head and tail for
         lists to be consistent with this interpretation of negative n.

    (23) Similarly I've left strpos essentially as at present, but search
         and rsearch have been extended to strings.  For example,

                    search(A, B, m, n)

         returns the index i of the first occurrence of the string B in A
         if m <= i < n, or the null value if there is no such occurrence.
         As for other uses of search, negative m is interpreted as
         size(A) + m, negative n as size(A) + n.  For a match in this
         search, all size(B) characters, including occurrences of '\0',
         in B must match successive characters in A.

         The function rsearch() behaves similarly but searches in reverse order
         of the indices.

    (24) A string A of length N determines in obvious ways arrays of M = 8 * N
         bits.  If the characters in increasing index order are c_0, c_1, ...
         and the bits in increasing order in c_i are b_j, b_j+1, ..., b_j+7
         where j = 8 * i, I've taken the array of bits determined by A to be

                    b_0, b_1, ..., b_M-1

         For example, since "a" = char(97) and 97 = 0b01100001, and
         "b" = char(98) = 0b01100010, the string "ab" determines the 16-bit
         array

                    1000011001000110

         in which the bits in the binary representations of "a" and "b" have
         been reversed.

         bit with index n in this array.   This is consistent with the use of
         bit for a number ch in [0,256), i.e. bit(char(ch), n) = bit(ch, n).
         For n < 0 or n >= size(A), bit(A,n) returns the null value.

    (25) For assigning values to specified bits in a string, I've defined
         setbit(A, n) and setbit(A, n, v).  The first assigns the value 1 to
         bit(A, n), the second assigns test(v) to bit(A, n).

    (26) For consistency with the corresponding number operations, the shift
         operations A << n and A >> n have been defined to give what look
         like right- and left-shifts, respectively.  For example, "ab" << 2
         returns the 16-bit array

                    0010000110010001

         in which the array for "ab" has been moved 2 bits to the right.

    (27) To achieve much the same as the C strcpy and strncpy functions for
         null-terminated strings, strcpy(S1, S2) and strncpy(S1, S2, n) have
         been defined.  Unlike the blkcpy() and copy() functions, the copying
         for these is only from the beginning of the strings.  Also, unlike C,
         no memory overflow can occur as the copying ceases when size(S1) is
         reached.  Note that these overwrite the content of S1 (which affects
         all strings linked to it) as well as returning S1.  Examples:

            S = strcpy(6 * "x", "abc")      <=>  S = "abc\0xx"

            S = strcpy(3 * "x", "abcdef")   <=>  S = "abc"

            S = strncpy(6 * "x", "abcd", 2) <=>  S = "ab\0xxx"

            S = strncpy(6 * "x", "ab", 4)   <=>  S = "ab\0\0xx"

            S = strncpy(6 * "x", "ab", 20)  <=>  S = "ab\0\0\0\0"

         If a new string S not linked to S1 is to be created, this can be
         achieved by using str(S1) in place of S1.  For example, the strcpy in

            A = "xxxxxx"
            S = strcpy(str("xxxxxx"), "abc")

         would not change the value of A.

    (28) I've extended the definitions of copy(A, B, ssi, num, dsi) and
         blkcpy(B, A, num, ssi, dsi) to allow for string-to-string copying
         and block-to-string copying, but num is now an upper bound for the
         number of characters to be copied - copying will cease before num
         characters are copied if the end of the data in the source A or the
         end of the destination B is reached.  As with other character-changing
         operations, copying to a string B will not change the locations of
         B[0], B[1], ... or the size of B.

         In the case of copying a string to itself, characters are copied in
         order of increasing index, which is different from block-to-block
         copying where a memmove is used.  This affects only copy from a
         string to itself.  For example,

                    A = "abcdefg";
                    copy(A, A, , , 2);

         will result in A == "abababa".  If the overwriting that occurs here
         is not wanted, one may use

                    A = "abcdefg";
                    copy(str(A), A, , , 2);

          which results in A == "ababcde".

    (29) perm(a,b) and comb(a,b) have been extended to accept any real a and
         any integer b except for perm(a, b) with integer a such that b <= a < 0
         which gives a "division by zero" error.  For positive b, both functions
         are polynomials in a of degree b;  for negative b, perm(a,b) is a
         rational function (1/((a + 1) * (a+2) ...) with abs(b) factors in the
         denominator), and comb(a,b) = 0.  (An obvious "todo" is to extend this
         to complex or other types of a.)

    (30) Although it is not illegal, it seems pointless to use a comma operator
         with a constant or simple variable as in

                    ; 2 * 3,14159
                            14159
                    ; a = 4; b = 5;
                    ; A = (a , b + 2);
                    ; A
                            7

         I have added a few lines to addop.c so that when this occurs a
         "unused value ignored" message and the relevant line number are
         displayed.  I have found this useful as I occasionally type ','
         when I mean '.'.

         There may be one or two other changes resulting from the way I have
         rewritten the optimization code in addop.c.  I think there was a bug
         that assumed that PTR_SIZE would be the same as sizeof(long).  By
         the way, the new OP_STRING is now of index rather than pointer type.
         It follows that pointers are now used in opcodes only for global
         variables.  By introducing a table of addresses of global variables
         like those used for "constants" and "literal strings", the use of
         pointers in opcodes could be eliminated.

    (31) When calc has executed a quit (or exit) statement in a function or
         eval evaluation, it has invoked a call to math_error() which causes
         a long jump to an initial state without freeing any data on the
         stack, etc.  Maybe more detail should be added to math_error(), but
         to achieve the freeing of memory for a quit statement and at the same
         time give more information about its occurrence I have changed the
         way opcodes.c handles OP_QUIT.  Now it should free the local variables
         and whatever is on the stack, and display the name and line-number,
         for each of the functions currently being evaluated.  The last
         function listed should be the "top-level" one with name "*".
         Strings being eval-ed will have name "**".

         Here is a demo:

            ; global a;
            ;
            ; define f(x) {local i = x^2; a++;
            ;; if (x > 5) quit "Too large!"; return i;}
            f() defined
            ; define g(x) = f(x) + f(2*x);
            g() defined
            ; g(2)
                    20
            ; g(3)
            Too large!
                    "f": line 3
                    "g": line 0
                    "*": line 6
            ; eval("g(3)")
            Too large!
                    "f": line 3
                    "g": line 0
                    "**": line 1
                    "*": line 7
            ; a
                    6

    (32) I've made several small changes like removing

                    if (vp->v_type == V_NUM) {
                            q = qinv(vp->v_num);
                            if (stack->v_type == V_NUM)
                                    qfree(stack->v_num);
                            stack->v_num = q;
                            stack->v_type = V_NUM;
                            return;
                    }

         from the definition of o_invert.  Presumably these lines were intended
         to speed up execution for the common case of numerical argument.
         Comparing the runtimes with and without these lines for inverting
         thousands of large random numbers in a matrix suggest that execution
         for real numbers is slightly faster without these lines.

         Maybe this and other similar treatment of "special cases" should be
         looked at more closely.

    (33) The new lib script lib/natnumset.cal demonstrates how the new
         string operators and functions may be used for defining and
         working with sets of natural numbers not exceeding a
         user-specified bound.


The following are the changes from calc version 2.10.3t5.28 to 2.10.3t5.33:

    Added hnrmod(v, h, n, r) builtin to compute:

        v % (h * 2^n + r), h>0, n>0, r = -1, 0 or 1

    Changed lucas.cal and mersenne.cal to make use of hnrmod().

    A number of changes from Ernest Bowen:

        (1) introduction of unary & and * analogous to those in C;

            For an lvalue var, &var returns what I call a
            value-pointer; this is a constant which may be assigned to
            a variable as in p = &var, and then *p in expressions has
            the same effect as var.  Here is a simple example of their use:

                ; define s(L) {local v=0; while (size(L)) v+= *pop(L);return v;}
                s() defined
                ; global a = 1, b = 2;
                ; L = list(&a, &b);
                ; print s(L)
                3
                ; b = 3;
                ; print s(L)
                4

            Octet-pointers, number-pointers, and string-pointers in
            much the same way, but have not attempted to do much with
            the latter two.

            To print a pointer, use the "%p" specifier.

            Some arithmetic operations has been defined for corresponding
            C operations.  For example:

                ; A = mat[4];
                ; p = &A[0];
                ; *(p+2) == A[2]
                ; ++p
                ; *p == A[1]

            There is at present no protection against "illegal" use of &
            and *, e.g. if one attempts here to assign a value to *(p+5),
            or to use p after assigning another value to A.

            NOTE: Unlike C, in calc &A[0] and A are quite different things.

            NOTE: If the current value of a variable X is an octet,
            number or string, *X may be used to to return the value of
            X; in effect X is an address and *X is the value at X.

            Added isptr(p) builtin to return 0 is p is not a pointer,
            and >0 if it is a pointer.  The value of isptr(p) comes from
            the V_XYZ #define (see the top of value.h) of the value to
            which p points.

            To allow & to be used as a C-like address operator, use of it
            has been dropped in calls to user-defined functions.  For the
            time being I have replaced it by the back-quote `.  For example:

                ; global a
                ; define f(a,b) = a = b
                ; f(&a,5)
                ; print a
                0
                ; f(`a,5)
                ; print a
                5

           However, one may use & in a similar way as in:

                ; define g(a,b) = *a = b
                ; g(&a, 7)
                ; print a
                7

           There is no hashvalue for pointers. Thus, like error values,
           they cannot be used as indices in an association.

           The -> also works in calc. For example:

                ; obj xy {x,y}
                ; obj uvw {u, v, w}
                ; obj xy A = {1,2}
                ; obj uvw B = {3,4,5}
                ; p = &A
                ; q = &B
                ; p->x
                        1
                ; p->y = 6
                ; A
                        obj xy {1, 6}
                ; q -> u
                        3
                ; p->y = q
                ; A
                        obj xy {1, v-ptr: 1400474c0}
                ; p->y->u
                        3
                ; p->y->u = 7
                ; B
                        obj uvw {7, 4, 5}
                ; p -> y = p
                ; A
                        obj xy {1, v-ptr: 140047490}
                ; p -> y -> x
                        1
                ; p->y->y
                        v-ptr: 140047490
                ; p->y->y-> x
                        1
                ; p->y->y->x = 8
                ; A
                        obj xy {8, v-ptr: 140047490}


        (2) a method of "protecting" variables;

            For the various kinds of "protection", of an l_value var,
            bits of var->v_subtype, of which only bits 0 and 1 have been
            used in the past to indicate literal and allocated strings.
            This has meant initialization of var->v_subtype when a new var
            is introduced, and for assignments, etc., examination of the
            appropriate bits to confirm that the operation is to be permitted.

            See help/protect for details.

        (3) automatic "freeing" of constants that are no longer required.

            For the "freeing" of constants, the definition of a NUMBER
            structure so that a NUMBER * q could be regarded as a
            pointing to a "freed number" if q->links = 0.

            The old q->num was changed to a union q->nu which had a pointer
            to the old q->num if q->links > 0 and to the next freed number
            if q->links = 0.  The old "num" is #defined to "nu->n_num".

            The prior method calc has used for handling "constants" amounted
            to leakage.  After:

                ; define f(x) = 27 + x;
                ; a = 27;

            It is of course necessary for the constant 27 to be stored, but
            if one now redefines f and a by:

                ; define f(x) = 45 + x;
                ; a = 45;

            There seems little point in retaining 27 as a constant and
            therefore using up memory.  If this example seems trivial,
            replace 27 with a few larger numbers like 2e12345, or better,
            -2e12345, for which calc needs memory for both 2e12345 and
            -2e12345!

            Constants are automatically freed a definition when a
            function is re- or un-defined.

            The qalloc(q) and qfree(q) functions have been changed so
            that that q->links = 0 is permitted and indicates that q
            has been freed.  If a number has been introduced as a
            constant, i.e. by a literal numeral as in the above
            examples, its links becoming zero indicates that it is no
            longer required and its position in the table of constants
            becomes available for a later new constant.

        (4) extension of transcendental functions like tan, tanh, etc.
            to complex arguments

        (5) definition of gd(z) and agd(z), i.e. the gudermannian and
            inverse gudermannian

        (6) introduction of show options for displaying information about
            current constants, global variables, static variables, and cached
            redc moduli.

            To help you follow what is going on, the following show
            items have been introduced:

                show constants ==> display the currently stored constants
                show numbers   ==> display the currently stored numbers
                show redcdata  ==> display the currently stored redc moduli
                show statics   ==> display info about static variables
                show real      ==> display only real-valued variables

            The constants are automatically initialized as constants and
            should always appear, with links >= 1, in in the list of constants.

            The show command:

                show globals

            has been redefined so that it gives information about all
            current global and still active static variables.

        (7) definition of functions for freeing globals, statics, redc values

            To free memory used by different kinds of variable, the following
            builtins have been added:

                freeglobals();          /* free all globals */
                freestatics();          /* free all statics */
                freeredc();             /* free redc moduli */
                free(a, b, ...);        /* free specific variables */

           NOTE: These functions do not "undefine" the variables, but
           have the effect of assigning the null value to them, and so
           frees the memory used for elements of a list, matrix or object.

           See 10) below for info about "undefine *".

        (8) enhancement of handling of "old value": having it return an
            lvalue and giving option of disabling updating.

            Now, by default, "." return an lvalue with the appropriate
            value instead of copying the old value.

            So that a string of commands may be given without changing
            the "oldvalue", the new builtin:

                saveval(0)

            function simply disables the updating of the "." value.
            The default updating can be resumed by calling:

                saveval(1)

            The "." value:

                ; 2 + 2
                4
                ; .
                4

            can now be treated as an unnamed variable.  For example:

                ; mat x[3,3]={1,2,3,4,5,6,7,8,9}
                ; x
                ; print .[1,2]
                6

        (9) for a list L defining L[i] to be same as L[[i]]

        (10) extending undefine to permit its application to all user-defined
             functions by using "undefine *".

             The command:

                undefine *

             undefines all current user-defined functions.  After
             executing all the above freeing functions (and if
             necessary free(.) to free the current "old value"), the
             only remaining numbers as displayed by:

                show numbers

             should be those associated with epsilon(), and if it has been
             called, qpi().

        (11) storing the most recently calculated value of qpi(epsilon)i and
             epsilon so that when called again with the same epsilon it
             is copied rather than recalculated.

        (12) defining trace() for square matrices

        (13) expression in parentheses may now be followed by a qualifier
             computable with its type

             When an expression in parentheses evaluates to an lvalue
             whose current value is a matrix, list or object, it may
             now be followed by a qualifier compatible with its type.

             For example:

                ; A = list(1,2,4);
                ; B = mat[2,2] = {5,6,7,8};
                ; define f(x) = (x ? A : B)[[1]];
                ; print f(1), f(0)
                2 6

                ; obj xy {x,y}
                ; C = obj xy = {4,5}
                ; p = &C
                ; *p.x
                Not indexing matrix or object
                ; (*p).x
                4

        (14) swap(a,b) now permits swapping of octets in the same or different
             blocks.

             For example:

                ; A = blk() = {1,2,3}
                ; B = blk() = {4,5,6}
                ; swap(A[0], B[2])
                ; A
                        chunksize = 256, maxsize = 256, datalen = 3
                        060203

    A few bug fixes from Ernest Bowen:

        B1: qcmpi(q, n) in qmath.c sometimes gave the wrong result if
                LONG_BITS > BASEB, len = 1 and nf = 0, since it then
                reduces to the value of (nf != q->num.v[1]) in which
                q->num.v[1] is not part of the size-1 array of HALFs for
                q->num.  At present this is used only for changing opcodes
                for ^2 and ^4 from sequences involving OP_POWER to
                sequences using OP_SQUARE, which has no effect on the
                results of calculations.

        B2: in matdet(m) in matfunc.c, a copy of the matrix m was not freed
                when the determinant turned out have zero value.

        B3: in f_search() in func.c, a qlinking of the NUMBER * storing the
                the size of a file was not qfreed.

        B4: in comalloc() in commath.c the initial zero values for real and
                imag parts are qlinked but not qfreed when nonzero values are
                assigned to them.  Rather than changing
                the definition of comalloc(), I have included any relevant
                qfrees with the calls to comalloc() as in
                        c = comalloc();
                        qfree(c->real);
                        c->real = ...

        B5: in calls to matsum(), zeros are qlinked but not qfreed.  Rather
                than changing addnumeric(), I have changed the definition
                of matsum(m) so that it simply adds the components of m,
                which requires only that the relevant additions be defined,
                not that all components of m be numbers.


    Simple arithmetic expressions with literal numbers are evaluated
    during compilation rather than execution.  So:

        define f(x) = 2 + 3 + x;

    will be stored as if defined by:

        define f(x) = 5 + x;

    Fixed bug with lowhex2bin conversation in lib_util.c.  It did not
    correctly convert from hex ASCII to binary values due to a table
    loading error.

    Fixed porting problem for NetBSD and FreeBSD by renaming the
    qdiv() function in qmath.c to qqdiv().

    Improved the speed of mfactor (from mfactor.cal library) for
    long Mersenne factorizations.  The default reporting loop
    is now 10000 cycles.

    SGI Mips r10k compile set is specified for IRIX6.5 with v7.2
    compilers.  A note for pre-IRIX6.5 and/or pre-v7.2 compilers
    is given in the compile set.

    Added regression tests related to saveval(), dot and pointers.


The following are the changes from calc version 2.10.3t5.11 to 2.10.3t5.27:

    The todo help file as been updated with the in-progress items:

        xxx - block print function is not written yet ...

    Expanded the role of blk() to produce unnamed blocks as in:

                B = blk(len, chunk)

    and named blocks as in:

                B = blk(str, len, chunk)

    A block may be changed (with possible loss of data only if len is less
    than the old len) by:

                C = blk(B, len, chunk)

    For an unnamed block B, this creates a new block C and copies
    min(len, oldlen) octets to it, B remaining unchanged.   For a named
    block, the block B is changed and C refers to the same block as B,
    so that for example, C[i] = x will result in B[i] == x.  Thus, for a
    named block, "B = " does nothing (other than B = B) in:

                B = blk(B, len, chunk)

    but is necessary for changing an unnamed block.

    Renamed rmblk() to blkfree().

    The builtin function blkfree(val) will free memory allocated to block.
    If val is a named block, or the name of a named block, or the
    identifying index for a named block, blkfree(val) frees the
    memory block allocated to this named block.  The block remains
    in existence with the same name, identifying index, and chunksize,
    but its size and maxsize becomes zero and the pointer for the start
    of its data block null.

    The builtin function blocks() returns the number of blocks that
    have been created but not freed by the blkfree() function.  When called
    as blocks(id) and the argument id less than the number of named
    blocks that have been created, blocks(id) returns the named block
    with identifying index id.

    Removed the artificial limit of 20 named blocks.

    Added name() builtin to return the name of a type of value
    as a string.

    Added isdefined() to determine of a value is defined.

    Added isobjtype() to determine the type of an object.

    The isatty(v) builtin will return 1 if v is a file that associated
    with a tty (terminal, xterm, etc.) and 0 otherwise.  The isatty(v)
    builtin will no longer return an error if v is not a file or
    is a closed file.

    The isident(m) builtin will return 1 if m is a  identity matrix
    and 0 otherwise.  The isident(m) builtin will no longer return an
    error if m is not a matrix.

    Added extensive testing of isxxx() builtins and their operations
    on various types.

    Added md5() builtin to perform the MD5 Message-Digest Algorithm.

    Renamed isset() to bit().

    Blocks will expand when required by the copy() builtin function:

        ; f = fopen("help/full", "r")
        ; B = blk()
        ; B
                chunksize = 256, maxsize = 256, datalen = 0
        ; copy(B, f)
        ; B
                chunksize = 256, maxsize = 310272, datalen = 310084
                2a2a2a2a2a2a2a2a2a2a2a2a2a0a2a20696e74726f0a2a2a2a2a2a2a2a2a...

        NOTE: Your results will differ because changes to help/full.

    The blkcpy() builtin args now more closely match that
    of memcpy(), strncpy:

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

    The copy() builtin args now more closely match that the cp command:

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

    but otherwise does the same thing as blkcpy.

    Fixed lint problems for SunOS.

    Added have_memmv.c and HAVE_MEMMOVE Makefile variable to control
    use of memmove().  If empty, then memmove() is tested for and if
    not found, or if HAVE_MEMMOVE= -DHAVE_NO_MEMMOVE then an internal
    version of memmove() is used instead.

    Added regression tests for sha, sha1 and md5 builtin hash functions.

    Added xx_print to to the list of object routines are definable.
    Added xx_print.cal to the library to demo this feature.

    Moved blkcpy() routines have been moved to blkcpy.[ch].

    The blkcpy() & copy() builtins can not copy to/from numbers.
    For purposes of the copy, only the numerator is ignored.

    Resolved a number of missing symbols for libcalc users.

    Added lib_util.{c,h} to the calc source to support users of
    libcalc.a.  These utility routines are not directly used by
    calc but are otherwise have utility to those programmers who
    directly use libcalc.a instead.

    Added sample sub-directory.  This sub-directory contains a few
    sample programs that use libcalc.a.  These sample programs are
    built via the all rule because they will help check to see that
    libcalc.a library does not contain external references that
    cannot be resolved.  At the current time none of these sample
    programs are installed.

    Added a libcalc_call_me_last() call to return storage created
    by the libcalc_call_me_first() call.  This allows users of libcalc.a
    to free up a small amount of storage.

    Fixed some memory leaks associated with the random() Blum generator.

    Fixed fseek() file operations for SunOS.

    Fixed convz2hex() fencepost error.  It also removes leading 0's.

    Plugged a memory leak relating to pmod.  The following calculation:

        pmod(2, x, something)

    where x was not 2^n-1 would leak memory.  This has been fixed.


The following are the changes from calc version 2.10.3t5.1 to 2.10.3t5.10:

    Misc printf warning bug fixes.

    Calc now permits chains of initializations as in:

                obj point {x,y} P = {1,2} = {3,4} = {5,6}

    Here the initializations are applied from left to right.  It may
    look silly, but the 1, 2, ... could be replaced by expressions with
    side effects.  As an example of its use suppose A and B are
    expressions with side effects:

                P = {A, B}

    has the effect of P.x = A; P.y = B.  Sometimes one might want these in
    the reverse order: P.y = B; P.x = A.  This is achieved by:

                P = { , B} = {A}

    Another example of its use:

                obj point Q = {P, P} = {{1, 2}, {3, 4}}

    which results in Q having Q.x.x = 1, Q.x.y = 2, etc.

    The role of the comma in has been changed.  Expressions such as:

                mat A[2], B[3]

    are equivalent to:

                (mat A[2]), (mat B[3])

    Now, expr1, expr2  returns type of expr2 rather than EXPR_RVALUE.  This
    permits expressions such as:

                (a = 2, b) = 3

    Also, expr1 ? expr2 : expr3  returns type(expr2) | type(expr3).
    This will make the result an lvalue (i.e. EXPR_RVALUE bit not set)
    For example, if both expr2 and expr3 are lvalues.  Then:

                a ? b : c = d

    has the effect of b = d if a is "nonzero", otherwise c = d.

    This may be compared with

                d = a ? b : c

    which does d = b if a is "nonzero", otherwise d = c.

    And now, expr1 || expr2 and expr1 && expr2 each return
    htype(expr1)| type(expr2).  So for example:

                a || b = c

    has the effect of a = c if a is "nonzero", otherwise b = c.
    And for example:

                a && b = c

    has the effect of a = c if a is "zero", otherwise b = c.

    At top level, newlines are neglected between '(' and the matching
    ')' in expressions and function calls.  For example, if f() has been
    already defined, then:


                a = (
                        2
                        +
                        f
                        (
                        3
                        )
                    )

    and

                b = sqrt (
                        20
                        ,
                        1
                    )

    will be accepted, and in interactive mode the continue-line prompt
    will be displayed.

    When calc sees a "for", "while", "do", or "switch", newlines will be
    ignored (and the line-continuation prompt displayed in interactive mode)
    until the expected conditions and statements are completed.
    For example:

        s = 0;
        for (i = 0; i < 5; i++)
        {
                s += i;
        }
        print s;

    Now 's' will print '10' instead of '5'.

    Added more regression tests to regress.cal.  Changed the error
    counter from 'err' to 'prob'.  The errmax() is set very high and
    the expected value of errcount() is kept in ecnt.

    Added the 'unexpected' help file which gives some unexpected
    surprises that C programmers may encounter.

    Updated the 'help', 'intro' and 'overview' to reflect the
    full list of non-builtin function help files.  Reordered the
    'full' help file.

    The blkalloc() builtin has been renamed blk().

    Only a "fixed" type of BLOCK will be used.  Other types of
    blocks in the future will be different VALUE types.

    Introduced an undefine command so that

                    undefine f, g, ...

    frees the memory used to store code for user-defined functions f,
    g, ..., effectively removing them from the list of defined
    functions.

    When working from a terminal or when config("lib_debug") > 0 advice
    that a function has been defined, undefined, or redefined is
    displayed in format "f() defined".

    Some experimental changes to block and octet handling, so that after:

                    B = blk(N)

    B[i] for 0 <= i < N behaves for some operations like an lvalue for
    a USB8 in B.

    xx_assign added to object functions to permit the possibility of
    specifying what A = B will do if A is an xx-object.  Normal
    assignment use of = is restored by the command: undefine
    xx_assign.

    For error-value err, errno(err) returns the error-code for err and
    stores this in calc_errno;  error(err) returns err as if
    error(errno(err)) were called.

    Anticipating probable future use, names have been introduced for
    the four characters @, #, $, `.  This completes the coverage of
    printable characters on a standard keyboard.

    Added sha() builtin to perform the old Secure Hash Algorithm
    (SHS FIPS Pub 180).

    Added sha1() builtin to perform the new Secure Hash Standard-1
    (SHS-1 FIPS Pub 180-1).

    Added ${LD_DEBUG} Makefile variable to allow for additional
    libraries to be compiled into calc ... for debugging purposes.
    In most cases, LD_DEBUG= is sufficient.

    Added ${CALC_ENV} makefile variable to allow for particular
    environment variables to be supplied for make {check,chk,debug}.
    In most cases, CALC_ENV= CALCPATH=./lib is sufficient.

    Added ${CALC_LIBS} to list the libraries created and used to
    build calc.  The CALC_LIBS= custom/libcustcalc.a libcalc.a
    is standard for everyone.

    Improved how 'make calc' and 'make all' rules work with respect
    to building .h files.

    Added 'make run' to only run calc interactively with the
    ${CALC_ENV} calc environment.  Added 'make cvd', 'make dbx'
    and 'make gdb' rules to run debug calc with the respective
    debugger with the ${CALC_ENV} calc environment.

    Added cvmalloc_error() function to lib_calc.c as a hook for
    users of the SGI Workshop malloc debugging library.

    Cut down on places where *.h files include system files.
    The *.c should do that instead where it is reasonable.

    To avoid symbol conflicts, *.h files produced and shipped
    with calc are enclosed that as similar to the following:

        #if !defined(__CALC_H__)
        #define __CALC_H__
        ..
        #endif /* !__CALC_H__ */

    Added memsize(x) builtin to print the best approximation of the
    size of 'x' including overhead.  The sizeof(x) builtin attempts
    to cover just the storage of the value and not the overhead.
    Because -1, 0 and 1 ZVALUES are static common values, sizeof(x)
    ignores their storage.  Also sizeof(x) ignores the denominator of
    integers, and the imaginary parts of pure real numbers.  Added
    regression tests for memsize(), sizeof() and size().


The following are the changes from calc version 2.10.3t4.16 to 2.10.3t5.0:

    The calc source now comes with a custom sub-directory which
    contains the custom interface code.  The main Makefile now
    drives the building and installing of this code in a similar
    way that it drives the lib and help sub-directories.  (see below)

    Made minor edits to most help files beginning with a thru e.

    The errno(n) sets a C-like errno to the value n; errno() returns
    the current errno value.  The argument for strerror() and error()
    defaults to this errno.

    Added more error() and errno() regression tests.

    The convention of using the global variable lib_debug at the
    end of calc library scripts has been replaced with config("lib_debug").
    The "lib_debug" is reserved by convention for calc library scripts.
    This config parameter takes the place of the lib_debug global variable.
    By convention, "lib_debug" has the following meanings:

        <-1     no debug messages are printed though some internal
                    debug actions and information may be collected

        -1      no debug messages are printed, no debug actions will be taken

        0       only usage message regarding each important object are
                    printed at the time of the read (default)

        >0      messages regarding each important object are
                    printed at the time of the read in addition
                    to other debug messages

    The "calc_debug" is reserved by convention for internal calc routines.
    The output of "calc_debug" will change from release to release.
    Generally this value is used by calc wizards and by the regress.cal
    routine (make check).  By convention, "calc_debug" has the following
    meanings:

        <-1     reserved for future use

        -1      no debug messages are printed, no debug actions will be taken

        0       very little, if any debugging is performed (and then mostly
                    in alpha test code).  The only output is as a result of
                    internal fatal errors (typically either math_error() or
                    exit() will be called). (default)

        >0      a greater degree of debugging is performed and more
                    verbose messages are printed (regress.cal uses 1).

    The "user_debug" is provided for use by users.  Calc ignores this value
    other than to set it to 0 by default (for both "oldstd" and "newstd").
    No calc code or shipped library will change this value other than
    during startup or during a config("all", xyz) call.

    The following is suggested as a convention for use of "user_debug".
    These are only suggestions: feel free to use it as you like:

        <-1     no debug messages are printed though some internal
                    debug actions and information may be collected

        -1      no debug messages are printed, no debug actions will be taken

        0       very little, if any debugging is performed.  The only output
                    are from fatal errors. (default)

        >0      a greater degree of debugging is performed and more
                    verbose messages are printed

    Added more code related to the BLOCK type.

    Added blkalloc() builtin.

    Split NAMETYPE definition out into nametype.h.

    Added OCTET type for use in processing block[i].

    Added free, copy, cmp, quickhash and print functions for
    HASH, BLOCK and OCTET.

    Added notes to config.h about what needs to be looked at when
    new configuration items are added.

    The null() builtin now takes arguments.

    Given the following:

        obj point {x,y}
        obj point P, Q

    will will now create P and Q as obj point objects.

    Added xx_or, xx_and, xx_not and xx_fact objfuncs.

    Added the custom() builtin function.  The custom() builtin
    interface is designed to make it easier for local custom
    modification to be added to calc.  Custom functions are
    non-standard or non-portable code.  For these reasons, one must can
    only execute custom() code by way of an explicit action.

    By default, custom() returns an error.  A new calc command line
    option of '-C' is required (as well as ALLOW_CUSTOM= -DCUSTOM
    Makefile variable set) to enable it.

    Added -C as a calc command line option.  This permits the
    custom() interface to be used.

    Added ALLOW_CUSTOM Makefile variable to permanently disable
    or selective enable the custom builtin interface.

    The rm() builtin now takes multiple filenames.  If the first
    arg is "-f", then 'no-such-file' errors are ignored.

    Added errcount([count]) builtin to return or set the error
    counter.  Added errmax([limit]) to return or set the error
    count limiter.

    Added -n as a calc command line option.  This has the effect
    of calling config("all", "newstd") at startup time.

    Added -e as a calc command line option to ignore all environment
    variables at startup time.  The getenv() builtin function will
    still return values, however.

    Added -i as a calc command line option.  This has the effect
    ignoring when errcount() exceeds errmax().

    Changed the config("maxerr") name to config("maxscan").  The
    old name of "maxerr" is kept for backward compatibility.

    Using an unknown -flag on the calc command like will
    generate a short usage message.

    Doing a 'help calc' displays the same info as 'help usage'.

    The 'make check' rule now uses the -i calc command line flag
    so that regress.cal can continue beyond when errcount exceeds
    errmax.  In regress.cal, vrfy() reports when errcount exceeds
    errmax and resets errmax to match errcount.  This check
    and report is independent of the test success of failure.

    Fixed missing or out of order tests in regress.cal.

    Misc Makefile cleanup in lib/Makefile and help/Makefile.

    The default errmax() value on startup is now 20.

    The custom() interface is now complete.  See help/custom and
    custom/HOW_TO_ADD files, which show up as the custom and new_custom
    help files, for more information.

    The help command will search ${LIBDIR}/custhelp if it fails to find
    a file in ${LIBDIR}.  This allows the help command to also print
    help for a custom function.  However if a standard help file and a
    custom help file share the same name, help will only print the
    standard help file.  One can skip the standard help file and print
    the custom help file by:

        help custhelp/name

    or by:

        custom("help", "name")

    Added minor sanity checks the help command's filename.

    Added show custom to display custom function information.

    Added the contrib help page to give information on how
    and where to submit new calc code, modes or custom functions.

    Added comment information to value.h about what needs to be
    checked or modified when a new value type is added.

    Both size(x) and sizeof(x) return information on all value types.
    Moved size and sizeof information from func.c and into new file: size.c.

    Added custom("devnull") to serve as a do-nothing interface tester.

    Added custom("argv" [,arg ...]) to print information about args.

    Added custom("sysinfo", "item") to print an internal calc #define
    parameter.

    The make depend rule also processes the custom/Makefile.

    Added xx_max and xx_min for objfuncs.

    The max(), min() builtins work for lists.


The following are the changes from calc version 2.10.3t3 to 2.10.3t4.15:

    The priority of unary + and - to that of binary + and - when they are
    applied to a first or only term.  Thus:

        -16^-2 == -1/256
        -7^2 == -49
        -3! == -6

    Running ranlib is no longer the default.  Systems that need RANLIB
    should edit the Makefile and comment back in:

        RANLIB=ranlib

    Dropped support of SGI r8k.

    Added support for the SGI r5k.

    Added support for SGI Mips compiler version 7.1 or later.

    Removed "random" as a config() option.

    Removed CCZPRIME Makefile variable.

    Added zsquaremod() back into zmod.c to be used by the Blum-Blum-Shub
    generator for the special case of needing x^2 mod y.

    Moved the Blum-Blum-Shub code and defines from zrand.c and zrand.h
    into zrandom.c and zrandom.h.  Now only the a55 generator resides
    in zrand.c and zrand.h.

    Added random, srandom and randombit help files.

    Added random(), srandom() and randombit() builtin functions.  The
    cryptographically strong random number generator is code complete!

    Removed cryrand.cal now that a Blum-Blum-Shub generator is builtin.

    Improved the speed of seedrandom.cal.  It now uses the 13th
    builtin Blum-Blum-Shub seed.

    The randmprime.cal script makes use of the Blum-Blum-Shub generator.

    Added randombitrun.cal and randomrun.cal calc library files.
    These are the Blum-Blum-Shub analogs to the randbitrun.cal
    and randrun.cal a55 tests.

    Improved hash.c interface to lower level hash functions.  The hash
    interface does not yet have a func.c interface ...  it is still
    under test.

    Added randombitrun.cal to test the Blum-Blum-Shub generator.

    Added calc.h, hash.h, shs.h and value.h to LIB_H_SRC because some
    of the libcalc.a files need them.

    In the original version, each call to newerror(str) created a new
    error-value.  Now a new value will be created only if str has not
    been used in a previous call to newerror().  In effect, the string
    serves to identify the error-value; for example:

            return newerror("Non-integer argument");

    can be used in one or more functions, some of which may be
    repeatedly called, but after it has been called once, it will
    always return the same value as if one had initially used the
    assignment:

            non_integer_argument_error = newerror("Non-integer argument")

    and then in each function used:

            return non_integer_argument_error;

    The new definition of newerror() permits its freer use in cases like:

            define foo(a) {

                    if (!isint(a))
                            return newerror("Non-integer argument");
                    ...
            }

    One might say that "new" in "newerror" used to mean being different
    from any earlier error-value.  Now it means being not one of the
    "original" or "old" error-values defined internally by calc.

    As newerror() and newerror("") specify no non-null string, it has
    been arranged that they return the same as newerror("???").

    Added "show errors" command analogous to "show functions" for
    user-defined functions.  One difference is that whereas the
    functions are created by explicit definitions, a new described
    error is created only when a newerror(...) is executed.

    Fixed macro symbol substitution problem uncovered by HPUX cpp bug in
    HVAL and related zrand.h macros.

    Added +e to CCMISC for HP-UX users.

    Fixed the prompt bug.

    Eliminated the hash_init() initialization function.

    The 'struct block' has been moved from value.c to a new file: block.h.

    Added "blkmaxprint" config value, which limits the octets to print
    for a block.  A "blkmaxprint" of 0 means to print all octets of a
    block, regardless of size.  The default is to print only the first
    256 octets.

    The "blkverbose" determines if all lines, including duplicates
    should be printed.  If TRUE, then all lines are printed.  If false,
    duplicate lines are skipped and only a "*" is printed in a style
    similar to od.  This config value has not meaning if "blkfmt" is
    "str".  The default value for "blkverbose" is FALSE: duplicate
    lines are not printed.

    The "blkbase" determines the base in which octets of a block
    are printed.  Possible values are:

        "hexadecimal"           Octets printed in 2 digit hex
        "hex"

        "octal"                 Octets printed in 3 digit octal
        "oct"

        "character"             Octets printed as chars with non-printing
        "char"                      chars as \123 or \n, \t, \r

        "binary"                Octets printed as 0 or 1 chars
        "bin"

        "raw"                   Octets printed as is, i.e. raw binary
        "none"

    The default "blkbase" is "hex".

    The "blkfmt" determines for format of how block are printed:

        "line"          print in lines of up to 79 chars + newline
        "lines"

        "str"           print as one long string
        "string"
        "strings"

        "od"            print in od-like format, with leading offset,
        "odstyle"          followed by octets in the given base
        "od_style"

        "hd"            print in hex dump format, with leading offset,
        "hdstyle"          followed by octets in the given base, followed
        "hd_style"         by chars or '.' if no-printable or blank

    The default "blkfmt" is "hd".

    Fixed a bug in coth() when testing acoth using coth(acoth(x)) == x
    within the rounding error.

    Assignments to matrices and objects has been changed.  The assignments in:

        A = list(1,2,3,4);
        B = makelist(4) = {1,2,3,4};

    will result in A == B.  Then:

        A = {,,5}

    will result in A == list(1,2,5,4).

    Made minor edits to most help files beginning with a thru d.

    Fixed error in using cmdbuf("").


The following are the changes from calc version 2.10.3t0 to 2.10.3t2:

    Bumped to version 2.10.3 due to the amount of changes.

    Renamed qabs() to qqabs() to avoid conflicts with stdlib.h.

    Fixed a casting problem in label.c.

    A lot of work was performed on the code generation by Ernest Bowen
    <ernie at turing dot une dot edu dot au>.    Declarations no longer
    need to precede code:

        define f(x) {
                local i = x^2;
                print "i = ":i;
                local j = i;
                ...
        }

    The scope of a variable extends from the end of the declaration (including
    initialization code for the variable) at which it is first created
    to the limit given by the following rules:

        local variable: to the end of the function being defined

        global variable: to the end of the session with calc

        static within a function definition: to the first of:

            an end of a global, static or local declaration (including
            initialization code) with the same identifier

            the end of the definition

        static at top level within a file: to the first of:

            the next static declaration of the identifier at top level
            in the file,

            the next global declaration of the identifier at top level
            in the file or in any function definition in the file,

            the next global declaration of the identifier at any level
            in a file being read as a result of a "read" command,

            the end of the file.

    The scope of a top-level global or static variable may be
    interrupted by the use of the identifier as a parameter or local or
    static variable within a function definition in the file being
    read; it is restored (without change of value) after the definition.

    For example, The two static variables a and b are created,
    with zero value, when the definition is read; a is initialized
    with the value x if and when f(x) is first called with a positive
    even x, b is similarly initialized if and when f(x) is first called
    positive odd x.  Each time f(x) is called with positive integer x,
    a or b is incremented.  Finally the values of the static variables
    are assigned to the global variables a and b, and the resulting
    values displayed.  Immediately after the last of several calls to
    f(x), a = 0 if none of the x's have been positive even, otherwise
    a = the first positive even x + the number of positive even x's,
    and b = 0 if none of the x's have been positive odd, otherwise
    b = the first positive odd x + the number of positive odd x's:

        define f(x) {
                if (isint(x) && x > 0) {
                        if (iseven(x)) {
                                static a = x;
                                a++;
                        } else {
                                static b = x;
                                b++;
                        }
                }
                global a = a, b = b;
                print "a =",a,"b =",b;
        }

    Fixed some faults in the handling of syntax errors for the matrix
    and object creation operators mat and obj.  In previous versions of calc:

        mat;                            <- Bad dimension 0 for matrix
        mat A;                          <- Bad dimension 0 for matrix
        global mat A;                   <- Bad dimension 0 for matrix
        mat A[2], mat B[3]              <- Semicolon expected
        global mat A[2], mat B[3]       <- Bad syntax in declaration statement

    Now:

        this statement                  has the same effect as
        --------------                  ----------------------
        mat A[2], B[3]                  (A = mat[2]), B[3]

        global mat A[2], B[3]           global A, B; A = mat[2]; B = mat[3];

    Initialization remains essentially as before except that for objects,
    spaces between identifiers indicate assignments as in simple variable
    declarations.  Thus, after:

        obj point {x,y};
        obj point P, Q R = {1,2}

    P has {0,0}, Q and R have {1,2}.  In the corresponding expression with
    matrices commas between identifiers before the initialization are ignored.
    For example:

        this statement                  has the same effect as
        --------------                  ----------------------
        mat A, B C [2] = {1,2}          A = B = C = (mat[2] = {1,2})

    One can also do things like:

        L = list(mat[2] = {1,2}, obj point = {3,4}, mat[2] = {5,6})
        A = mat[2,2] = {1,2,3,4}^2
        B = mat[2,2] = {1,2,3,4} * mat[2,2] = {5,6,7,8}

    where the initialization = has stronger binding than the assignment = and
    the * sign.

    Matrices and objects can be mixed in declarations after any simple
    variables as in:

        global a, b, mat A, B[2] = {3,4}, C[2] = {4,5}, obj point P = {5,6}, Q

    Fixed some bugs related to global and static scoping.  See the
    5200 regress test and lib/test5200.cal for details.

    Optimized opcode generator so that functions defined using '=' do not
    have two unreached opcodes.  I.e.,:

        define f(x) = x^2
        show opcodes f

    Also unreachable opcodes UNDEF and RETURN are now not included at
    the end of any user-defined function.

    Changed the "no offset" indicator in label.c from 0 to -1; this
    permits goto jumps to the zero opcode position.

    Changed the opcode generation for "if (...)" followed by
    "break", "continue", or "goto", so that only one jump opcode is
    required.

    A label can now be immediately by a right-brace.  For example:

        define test_newop3(x) {if (x < 0) goto l132; ++x; l132: return x;}

    The LONG_BITS make variable, if set, will force the size of a long
    as well as forcing the USB8, SB8, USB16, SB16, USB32, SB32,
    HAVE_B64, USB64, SB64, U(x) and L(x) types.  If the longbits
    program is given an arg (of 32 or 64), then it will output
    based on a generic 32 or 64 bit machine where the long is
    the same size as the wordsize.

    Fixed how the SVAL and HVAL macros were formed for BASEB==16 machines.

    Dropped explicit Makefile support for MIPS r8k since these processors
    no longer need special compiler flags.

    SGI 6.2 and later uses -xansi.


The following are the changes from calc version 2.10.2t33 to 2.10.2t34:

    Fixed a bug related to fact().

    Thanks to Ernest Bowen <ernie at turing dot une dot edu dot au>,
    for two or three arguments,

            search(x, val, start);
            rsearch(x, val, start);

    and for matrix, list or association x:

            search(f, str, start);
            rsearch(f, str, start);

    for a file stream f open for reading, behave as before except for a few
    differences:

        (1) there are no limits on the integer-valued start.

        (2) negative values of start are interpreted as offsets from the size of
            x and f.  For example,

                    search(x, val, -100)

            searches the last 100 elements of x for the first i for which
            x[[i]] = val.

        (3) for a file f, when start + strlen(str) >= size(f) and
            search(f, str, start) returns null, i.e. str is
            not found, the file position after the search will be

                    size(f) - strlen(str) + 1

            rather than size(f).

    For four arguments:

            search(a, b, c, d)
            rsearch(a, b, c, d),

    a has the role of x or f, and b the role of val or str as described
    above for the three-argument case, and for search(), c is
    essentially "start" as before, but for rsearch() is better for c
    and d to be the same as for search().  For a non-file case, if:

             0 <= c < d <= size(a),

    the index-interval over which the search is to take place is:

             c <= i < d.

    If the user has defined a function accept(v,b), this is used rather
    than the test v == b to decide for matrix, list, or association
    searches when a "match" of v = a[[i]] with b occurs. E.g.  after:

             define accept(v,b) = (v >= b);

    then calling:

             search(a, 5, 100, 200)

    will return, if it exists, the smallest index i for which
    100 <= i < 200 and a[[i]] >= 5.  To restore the effect of
    the original "match" function, one would then have to:

             define accept(v,b) == (v == b).

    Renamed the calc symbol BYTE_ORDER to CALC_BYTE_ORDER in order
    to avoid conflict.

    Added beer.cal and hello.cal lib progs in support of:   :-)

        http://www.ionet.net/~timtroyr/funhouse/beer.html
        http://www.latech.edu/~acm/HelloWorld.shtml


The following are the changes from calc version 2.10.2t25 to 2.10.2t32:

    Eliminated use of VARARG and <varargs.h>.  Calc supports only
    <stdarg.h>.  The VARARGS Makefile variable has been eliminated.

    Source is converted to ANSI C.  In particular, functions
    will now have ANSI C style args.  Any comments from old K&R
    style args have been moved to function comment section.

    Removed prototype.h.  The PROTO() macro is no longer needed
    or supported.

    Added mfactor.cal to find the smallest factor of a Mersenne number.

    The built .h file: have_times.h, determines if the system has
    <time.h>, <times.h>, <sys/time.h> and <sys/times.h>.

    Because shs.c depends on HASHFUNC, which in turn depends on
    VALUE, shs.o has been moved out of libcalc.a.  For the same
    reasons, hash.h and shs.h are not being installed into
    the ${LIBDIR} for now.

    A number of the regression tests that need random numbers now
    use different seeds.

    Fixes for compiling under BSDI's BSD/OS 2.0.  Added a Makefile
    section for BSD/OS.

    Added a Makefile compile section for Dec Alpha without gcc ...
    provides a hack-a-round for Dec Alpha cc bug.

    Minor comment changes to lucas.cal.

    Added pix.cal, a slow painful but interesting way to compute pix(x).

    Confusion over the scope of static and global values has been reduced
    by a patch from Ernest Bowen <ernie at turing dot une dot edu dot au>.

        The change introduced by the following patch terminates the
        scope of a static variable at any static declaration with the
        same name at the same level, or at any global declaration with
        the same name at any level.  With the example above, the scope
        of the static "a" introduced in the third line ends when the
        "global a" is read in the last line.  Thus one may now use the
        same name in several "static" areas as in:

            ; static a = 10;
            ; define f(x) = a + x;
            ; static a = 20;
            ; define g(x) = a + x;
            ; global a;

        The first "a" exists only for the definition of f(); the second
        "a" only for the definition of g().  At the end one has only
        the global "a".

        Ending the scope of a static variable in this way is consistent
        with the normal use of static variables as in:

            ; static a = 10;
            ; define f(x) {static a = 20; return a++ + x;}
            ; define g(x) = a + x;
            ; global a;

        The scope of the first "a" is temporarily interrupted by the
        "static a" in the second line; the second "a" remains active
        until its scope ends with the ending of the definition of f().
        Thus one ends with g(x) = 10 + x and on successive calls to
        f(), f(x) returns 20 + x, 21 + x, etc.  With successive "static
        a" declarations at the same level, the active one at any stage
        is the most recent; if the instructions are being read from a
        file, the scope of the last "static a" ends at the end-of-file.

        Here I have assumed that no "global a" is encountered.  As
        there can be only one global variable with name "a", it seems
        to me that its use must end the scope of any static "a".  Thus
        the changes I introduce are such that after:

            ; global a = 10;
            ; define f(x) = a + x;
            ; static a = 20;
            ; define g(x) = a + x;
            ; define h(x) {global a = 30; return a + x;}
            ; define i(x) = a + x;

        g(x) will always return 20 + x, and until h(x) has been called,
        f(x) and i(x) will return 10 + x; when h(x) is called, it
        returns 30 + x and any later call to f(x) or i(x) will return
        30 + x.  It is the reading of "global a" in the definition of
        h() that terminates the scope of the static a = 20, so that the
        "a" for the last line is the global variable defined in the
        first line.  The "a = 30" is executed only when h() is called.

        Users who find this confusing might be well advised to use
        different names for different variables at the same scope level.

        The other changes produced by the patch are more straightforward,
        but some tricky programming was needed to get the possibility of
        multiple assignments and what seems to be the appropriate order
        of executions and assignments.  For example, the order for the
        declaration:

                global a, b = expr1, c, d = expr2, e, f

        will be:

                evaluation of expr1;
                assignment to b;
                evaluation of expr2;
                assignment to d;

        Thus the effect is the same as for:

                a = 0; b = expr1; c = 0; d = expr2; e = 0; f = 0;

        The order is important when the same name is used for different
        variables in the same context.  E.g. one may have:

                define f(x) {
                        global a = 10;
                        static a = a;
                        local a = a--;

                        while (--a > 0)
                                x++;
                        return x;
                }

        Every time this is called, the global "a" is assigned the value
        10.  The first time it is called, the value 10 is passed on to
        the static "a" and then to the local "a".  In each later call
        the "static a = a" is ignored and the static "a" is one less than
        it was in the preceding call.  I'm not recommending this style of
        programming but it is good that calc will be able to handle it.

        I've also changed dumpop to do something recent versions do not do:
        distinguish between static and global variables with the same name.

        Other changes: commas may be replaced by spaces in a sequence of
        identifiers in a declaration. so one may now write:

                global a b c = 10, d e = 20

        The comma after the 10 is still required.  Multiple occurrences
        of an identifier in a local declaration are now acceptable as
        they are for global or static declarations:

                local a b c = 10, a = 20;

        does the same as:

                local a b c;
                a = b = c = 10;
                a = 20;

        The static case is different in that:

                static a b c = 10, a = 20;

        creates four static variables, the first "a" having a very short and
        useless life.

    Added new tests to verify the new assignments above.

    Added the builtin test(x) which returns 1 or 0 according as x tests
    as true or false for conditions.

    Added have_posscl.c which attempts to determine if FILEPOS is
    a scalar and defines HAVE_FILEPOS_SCALAR in have_posscl.h
    accordingly.  The Makefile variable HAVE_POSSCL determines
    if have_posscl.c will test this condition or assume non-scalar.

    Added have_offscl.c which attempts to determine if off_t is
    a scalar and defines HAVE_OFF_T_SCALAR in have_posscl.h
    accordingly.  The Makefile variable HAVE_OFFSCL determines
    if have_offscl.c will test this condition or assume non-scalar.

    Reading to EOF leaves you positioned one character beyond
    the last character in the file, just like Un*x read behavior.

    Calc supports files and offsets up to 2^64 bytes, if the OS
    and file system permits.


The following are the changes from calc version 2.10.2t4 to 2.10.2t24:

    Added makefile debugging rules:

        make chk        like a 'make check' (run the regression tests)
                        except that only a few lines around interesting
                        (and presumable error messages) are printed.
                        No output if no errors are found.

        make env        print important makefile values

        make mkdebug    'make env' + version information and a
                        make with verbose output and printing of
                        constructed files

        make debug      'make mkdebug' with a 'make clobber'
                        so that the entire make is verbose and
                        a constructed files are printed

     Improved instructions in 'BUGS' section on reporting problems.
     In particular we made it easy for people to send in a full
     diagnostic output by sending 'debug.out' which is made as follows:

        make debug > debug.out

     Added -v to calc command line to print the version and exit.

     Fixed declarations of memcpy(), strcpy() and memset() in the
     case of them HAVE_NEWSTR is false.

     Fixed some compile time warnings.

     Attempting to rewind a file this is not open generates an error.

     Noted conversion problems in file.c in triple X comments.

     Some extremely brain dead shells cannot correctly deal with if
     clauses that do not have a non-empty else statement.  Their
     exit bogosity results in make problems.  As a work-a-round,
     Makefile if clauses have 'else true;' clauses for if statements
     that previously did not have an else clause.

     Fixed problems where the input stack depth reached the 10 levels.

     The show keyword is now a statement instead of a command:

        ; define demo() {local f = open("foo", "w"); show files; fclose(f);}
        ; demo()

     Added a new trace option for display of links to real and complex
     numbers.  This is activated by config("trace", 4).  The printing of
     a real number is immediately followed by "#" and the number of links
     to that number; complex numbers are printed in the same except for
     having "##" instead of "#".  <ernie at turing dot une dot edu dot au>

     The number of links for a number value is essentially the number of value
     locations at which it is either stored or deemed to be stored.  Here a
     number value is the result of a reading or evaluation; when the result
     is assigned to lvalues, "linking" rather than copying occurs.  Different
     sets of mutually linked values may contain the same number.  For example:

        a = b = 2 + 3; x, y = 2 + 3;

     a and b are linked, and x and y are linked, but a and x are not linked.

     Revised the credits help file and man page.  Added archive help
     file to indicate where recent versions of calc are available.

     The regression test suite output has been changed so that it will
     output the same information regardless of CPU performance.  In
     particular, CPU times of certain tests are not printed.  This allows
     one to compare the regression output of two different systems easier.

     A matrix or object declaration is now considered an expression
     and returns a matrix or object of the specified type.  Thus one may
     use assignments like:

        A = mat[2];             /* same as: mat A[2]; */
        P = obj point;          /* same as: obj point P; */

     The obj and mat keywords may be with "local", "global", "static" as in:

        local mat A[2];

     Several matrices or objects may be assigned or declared in the one
     statement, as in:

        mat A, B[2], C[3];      /* same as: mat A[2], B[2], C[3] */

     except that only one matrix creation occurs and is copied as in:

        A = B = mat[2];

     Initialization of matrices and objects now occur before assignments:

        mat A, B [2] = {1,2};   /* same as: A = B = (mat[2] = {1,2}); */

     Missing arguments are considered as "no change" rather than
     "assign null values".  As in recent versions of calc, the default
     value assigned to matrix elements is zero and the default for object
     elements is a null value).  Thus:

        mat A[2] = {1,2};
        A = { , 3};

     will change the value of A to {1,3}.

     If the relevant operation exists for matrices or has been defined for
     the type of object A is, the assignment = may be combined with +, -, *,
     etc. as in:

        A += {3, 4};            /* same as: A[0] += 3; A[1] += 4; */
        A += { };               /* same as: A += A; */

     In (non-local) declarations, the earlier value of a variable may be
     used in the initialization list:

        mat A[3]={1,2,3}; mat A[3]={A[2],A[1],A[0]}; /* same as: A={3,2,1} */

     Also:

        mat A[3] = {1,2,3};
        mat A[3] = {A, A, A};

     produces a 3-element matrix, each of whose elements is a 3-element matrix.

     The notation A[i][j] requires A[i] to be a matrix, whereas B[i,j]
     accesses an element in a 2-dimensional matrix.  Thus:

        B == A[i]       implies         A[i][j] = B[j]

     There is requirement in the use of A[i][j] that the matrices A[i]
     for i = 0, 1, ... all be of the same size.  Thus:

        mat A[3] = {(mat[2]), (mat[3]), (mat[2])};

     produces a matrix with a 7-element structure:

        A[0][0], A[0][1], A[1][0], A[1][1], A[1][2], A[2][0], A[2][1]

     One can initialize matrices and objects whose elements are matrices
     and/or objects:

        obj point {x,y}
        obj point P;
        obj point A = {P,P};

     or:

        obj point {x,y};
        obj point P;
        mat A[2] = {P,P};
        A = {{1,2}, {3,4}};

     The config("trace", 8) causes opcodes of newly defined functions
     are displayed.  Also show can now show the opcodes for a function.
     For example:

        config("trace", 8);
        define f(x) = x^2;
        show opcodes f;
        define g(x,y) {static mat A[2]; A += {x,y}; return A;}
        show opcodes g
        g(2,3);
        show opcodes g;
        g(3,4);

     The two sequences displayed for f should show the different ways
     the parameter is displayed.  The third sequence for g should also
     show the effects of the static declaration of A.

     Fixed a number of compiler warning and type cast problems.

     Added a number of new error codes.

     Misc bug fixes for gcc2 based Sparc systems.

     Fixed a bug in the SVAL() macro on systems with 'long long'
     type and on systems with 16 bit HALFs.

     Reduced the Makefile CC set:

         CCOPT are flags given to ${CC} for optimization
         CCWARN are flags given to ${CC} for warning message control
         CCMISC are misc flags given to ${CC}

         CFLAGS are all flags given to ${CC}
                [[often includes CCOPT, CCWARN, CCMISC]]
         ICFLAGS are given to ${CC} for intermediate progs

         CCMAIN are flags for ${CC} when files with main() instead of CFLAGS
         CCSHS are flags given to ${CC} for compiling shs.c instead of CFLAGS

         LCFLAGS are CC-style flags for ${LINT}
         LDFLAGS are flags given to ${CC} for linking .o files
         ILDFLAGS are flags given to ${CC} for linking .o files
                  for intermediate progs

         CC is how the C compiler is invoked

    Added more tests to regress.cal.

    Port to HP-UX.

    Moved config_print() from config.c to value.c so prevent printvalue()
    and freevalue() from being unresolved symbols for libcalc.a users.

    Calc will generate "maximum depth reached" messages or errors when
    reading or eval() is attempted at maximum input depth.

    Now each invocation of make is done via ${MAKE} and includes:

        MAKE_FILE=${MAKE_FILE}
        TOPDIR=${TOPDIR}
        LIBDIR=${LIBDIR}
        HELPDIR=${HELPDIR}

    Setting MAKE_FILE= will cause make to not re-make if the Makefile
    is edited.

    Added libinit.c which contains the function libcalc_call_me_first().
    Users of libcalc.a MUST CALL libcalc_call_me_first BEFORE THEY USE
    ANY OTHER libcalc.a functions!

    Added support for the SGI IRIX6.2 (or later) Mongoose 7.0 (or later)
    C Compiler for the r4k, r8k and r10k.  Added LD_NO_SHARED for
    non-shared linker support.

    Re-ordered and expanded options for the DEBUG make variable.

    Make a few minor cosmetic comment changes/fixes in the main Makefile.

    Statements such as:

                mat A[2][3];

    now to the same as:

                mat M[3];
                mat A[2] = {M, M};

    To initialize such an A one can use a statement like

                A = {{1,2,3}, {4,5,6}};

    or combine initialization with creation by:

                mat A[2][3] = {{1,2,3}, {4,5,6}};

    One would then have, for example, A[1][0] = 4.  Also, the inner braces
    cannot be removed from the initialization for A:

                mat A[2][3] = {1,2};

    results in exactly the same as:

                mat A[2] = {1,2};

    Added rm("file") builtin to remove a file.

    The regress test sections that create files also use rm() to remove
    them before and afterward.

    Added 4400-4500 set to test new mat and obj initialization rules.

    Added 4600 to test version file operations.

    Added CCZPRIME Makefile variable to the set for the short term
    to work around a CC -O2 bug on some SGI machines.

    Added regression test of _ variables and function names.

    Added read of read and write, including read and write test for
    long strings.

    Fixed bug associated with read of a long string variable.

    Renumbered some of the early regress.cal test numbers to make room
    for more tests.  Fixed all out of sequence test numbers.  Fixed some
    malformed regression reports.

    Renamed STSIZE_BITS to OFF_T_BITS.  Renamed SWAP_HALF_IN_STSIZE to
    SWAP_HALF_IN_OFF_T.


The following are the changes from calc version 2.10.2t1 to 2.10.2t3:

    Fixed bug in the regression suite that made test3400 and test4100
    fail on correct computations.

    The randbit() builtin, when given to argument, returns 1 random bit.

    Fixed a bug in longlong.c which made is generate a syntax error
    on systems such as the PowerPC where the make variable LONGLONG
    was left empty.

    By default, the Makefile leaves LONGLONG_BITS empty to allow for
    testing of 64 bit data types.  A few hosts may have problems with
    this, but hopefully not.  Such hosts can revert back to LONGLONG_BITS=0.

    Improved SGI support.  Understands SGI IRIX6.2 performance issues
    for multiple architectures.

    Fixed a number of implicit conversion from unsigned long to long to avoid
    unexpected rounding, sign extension, or loss of accuracy side effects.

    Added SHSCC because shs.c contains a large expression that some
    systems need help in optimizing.

    Added "show files" to display information about all currently open files.

    Calc now prevents user-defined function having the same name as a
    builtin function.

    A number of new error codes (more than 100) have been added.

    Added ctime() builtin for date and time as string value.
    Added time() builtin for seconds since 00:00:00 1 Jan 1970 UTC.
    Added strerror() builtin for string describing error type.
    Added freopen() builtin to reopen a file.
    Added frewind() builtin to rewind a file.
    Added fputstr() builtin to write a null-terminated string to a file.
    Added fgetstr() builtin to read a null-terminated string from a file.
    Added fgetfield() builtin to read next field from file.
    Added strscan() builtin to scan a string.
    Added scan() builtin to scan of a file.
    Added fscan() builtin to scan of a file.
    Added fscanf() builtin to do a formatted scan of a file.
    Added scanf() builtin to do a formatted scan of stdin.
    Added strscanf() builtin to do a formatted scan of a string.
    Added ungetc() builtin to unget character read from a file.

    As before, files opened with fopen() will have an id different from
    earlier files.  But instead of returning the id to the FILEIO slot
    used to store information about it, calc simply uses consecutive
    numbers starting with 3.  A calc file retains its id, even when the
    file has been closed.

    The builtin files(i) now returns the file opened with id == i
    rather than the file with slot number i.  For any i <= lastid,
    files(i) has at some time been opened.  Whether open or closed, it
    may be "reopened" with the freopen() command.  This write to a file
    and then read it, use:

        f = fopen("junk", "w")
        freopen(f, "r")

        To use the same stream f for a new file, one may use:

            freopen(f, mode, newfilename)

        which closes f (assuming it is open) and then opens newfilename on f.

        And as before:

            f = fopen("curds", "r")
            g = fopen("curds", "r")

        results in two file ids (f and g) that refer to the same file
        name but with different pointers.

    Calc now understands "w+", "a+" and "r+" file modes.

    If calc opens a file without a mode there is a "guess" that mode
    "r+" will work for any files with small descriptors found to be
    open.  In case it doesn't (as apparently happens if the file had
    not been opened for both reading and reading) the function now also
    tries "w" and "r", and if none work, gives up.  This avoids having
    "open" files with null fp.

    The builtin rewind() calls the C rewind() function, but one may
    now rewind several files at once by a call like rewind(f1, f2).
    With no argument, rewind() rewinds all open files with id >= 3.

    The functions fputstr(), fgetstr() have been defined to include the
    terminating '\0' when writing a string to a file.  This can be done
    at present with a sequence of instructions like:

        fputs(f, "Landon"); fputc(f, 0);
        fputs(f, "Curt"); fputc(f, 0);
        fputs(f, "Noll"); fputc(f, 0);

        One may now do:

            fputstr(f, "Landon", "Curt", "Noll");

        and read them back by:

            rewind(f);
            x = fgetstr(f);     /* returns "Landon" */
            y = fgetstr(f);     /* returns "Curt" */
            z = fgetstr(f);     /* returns "Noll" */

    The builtin fgetfield() returns the next field of non-whitespace
    characters.

    The builtins scan(), fscan(), strscan() read tokens (fields of
    non-whitespace characters) and evaluates them.  Thus:

        global a,b,c;
        strscan("2+3  4^2\n c=a+b", a, b, 0);

        results in a = 5, b = 16, c = 21

    The functions scanf, fscanf, strscanf behave like the C functions
    scanf, fscanf, sscanf.   The conversion specifiers recognized are "%c",
    "%s", "%[...]" as in C, with the options of *, width-specification,
    and complementation (as in [^abc]), and "%n" for file-position, and
    "%f", "%r", "%e", "%i" for numbers or simple number-expressions - any
    width-specification is ignored; the expressions are not to include any
    white space or characters other than decimal digits, +, -, *, /, e, and i.
    E.g. expressions like 2e4i+7/8 are acceptable.

    The builtin size(x) now returns the size of x if x is an open file
    or -1 if x is a file but not open.  If s is a string, size(s) returns
    characters in s.

    Added builtin access("foo", "w") returns the null value if a file
    "foo" exists and is writable.

    Some systems has a libc symbolic qadd() that conflicted with calc's
    qadd function.  To avoid this, qadd() has been renamed to qqadd().

    The calc error codes are produced from the calcerr.tbl file.
    Instead of changing #defines in value.h, one can not edit calcerr.tbl.
    The Makefile builds calcerr.h from this file.

    Calc error codes are now as follows:

        <0                      invalid
        0 .. sys_nerr-1         system error ala C's errno values
        sys_nerr .. E__BASE-1   reserved for future system errors
        E__BASE .. E__HIGHEST   calc internal errors
        E__HIGHEST+1 .. E_USERDEF-1     invalid
        E_USERDEF ..            user defined errors

    Currently, E__BASE == 10000 and E_USERDEF == 20000.  Of course,
    sys_nerr is system defined however is likely to be < E__BASE.

    Renamed CONST_TYPE (as defined in have_const.h) to just CONST.
    This symbol will either be 'const' or an empty string depending
    on if your compiler understands const.

    CONST is beginning to be used with read-only tables and some
    function arguments.  This allows certain compilers to better
    optimize the code as well as alerts one to when some value
    is being changed inappropriately.  Use of CONST as in:

        int foo(CONST int curds, char *CONST whey)

    while legal C is not as useful because the caller is protected
    by the fact that args are passed by value.  However, the
    in the following:

        int bar(CONST char *fizbin, CONST HALF *data)

    is useful because it calls the compiler that the string pointed
    at by 'fizbin' and the HALF array pointer at by 'data' should be
    treated as read-only.


The following are the changes from calc version 2.10.1t21 to 2.10.2t0:

    Bumped patch level 2.10.2t0 in honor of having help files for
    all builtin functions.  Beta release will happen at the end of
    the 2.10.2 cycle!!!

    Fewer items listed in BUGS due to a number of bug fixes.

    Less todo in the help/todo file because more has already been done.  :-)

    All builtin functions have help files!  While a number need cleanup
    and some of the LIMITS, LIBRARY and SEE ALSO sections need fixing
    (or are missing), most of it is there.  A Big round of thanks goes to
    <ernie at turing dot une dot edu dot au> for his efforts in initial
    write-ups for many of these files!

    The recognition of '\' as an escape character in the format argument
    of printf() has been dropped.  Thus:

        printf("\\n");

    will print the two-character string "\n" rather than the a
    one-character carriage return.  <ernie at turing dot une dot edu dot au>

    Missing args to printf-like functions will be treated as null values.

    The scope of of config("fullzero") has been extended to integers,
    so that for example, after config("mode","real"), config("display", 5),
    config("fullzero", 1), both:

        print 0, 1, 2;
        printf("%d %d %d\n", 0, 1, 2);

    print:

        .00000 1.00000, 2.00000

    The bug which caused calc to exit on:

        b = "print 27+"
        eval(b)

    has been fixed.  <ernie at turing dot une dot edu dot au>

    Fixed bugs in zio.c which caused eval(str(x)) == x to fail
    in non-real modes such as "oct".  <ernie at turing dot une dot edu dot au>

    The following:

        for (i = 1; i < 10; i++) print i^2,;

    now prints the same as:

        for (i = 1; i < 10; i++) print i^2,;

    The show globals will print '...' in the middle of large values.
    <ernie at turing dot une dot edu dot au>

    The param(n) builtin, then n > 0, returns the address rather than
    the value of the n-th argument to save time and memory usage.  This
    is useful when a matrix with big number entries is passed as an arg.
    <ernie at turing dot une dot edu dot au>

    The param(n) builtin, then n > 0, may be used as an lvalue:

        ; define g() = (param(2) = param(1));
        ; define h() = (param(1)++, param(2)--);
        ; u = 5
        ; v = 10
        ; print g(u, &v), u, v;
        5 5 5
        ; print h(&u, &v), u, v;
        5 6 4

    Missing args now evaluate to null as in:

        A = list(1,,3)
        B = list(,,)
        mat C[] = {,,}
        mat D[] = { }


The following are the changes from calc version 2.10.1t20 to 2.10.1t20:

    Changes made in preparation for Blum Blum Shub random number generator.

    REDC bug fixes: <ernie at turing dot une dot edu dot au>

        Fixed yet another bug in zdiv which occasionally caused the "top digit"
        of a nonzero quotient to be zero.

        Fixed a bug in zredcmul() where a rarely required "topdigit" is
        sometimes lost rather than added to the appropriate carry.

    A new function zredcmodinv(ZVALUE z, ZVALUE *res) has been defined
    for evaluating rp->inv in zredcalloc().  <ernie at turing dot une
    dot edu dot au>

    New functions zmod5(ZVALUE *zp) and zmod6(ZVALUE z, ZVALUE *res)
    have been defined to give O(N^1.585)-runtime evaluation of z % m
    for large N-word m.  These require m and BASE^(2*N) // m to have
    been stored at named locations lastmod, lastmodinv.  zmod5() is
    essentially for internal use by zmod6() and zpowermod().  <ernie at
    turing dot une dot edu dot au>

    Changes to rcmul(x,y,m) so that the result is always in [0, m-1].
    <ernie at turing dot une dot edu dot au>

    Changes to some of the detail of zredcmul() so that it should run slightly
    faster.  Also changes to zredcsq() in the hope that it might achieve
    something like the improvement in speed of x^2 compared with x * x.
    <ernie at turing dot une dot edu dot au>

    A new "bignum" algorithm for evaluating pmod(x,k,m) when
    N >= config("pow2").  For the multiplications and squaring
    modulo m, or their equivalent, when N >= config("redc2"),
    calc has used evaluations corresponding to rcout(x * y, m),
    for which the runtime is essentially that of three multiplications.
    <ernie at turing dot une dot edu dot au>

    Yet more additions to the regress.cal test suite.

    Fixed some ANSI-C compile nits in shs.c and quickhash.c.

    Plugs some potential memory leaks in definitions in func.c.
    Expressions such as qlink(vals[2]) in some circumstances are
    neither qfreed nor returned as function values.
    <ernie at turing dot une dot edu dot au>

    The nextcand() and prevcand() functions handle modval, modulus
    and skip by using ZVALUE rather than ZVALUE * and dropping
    the long modulus, etc.  <ernie at turing dot une dot edu dot au>

    Changed a couple of occurrences of itoq(1) or itoq(0) to &_qone_
    and &_qzero_.  <ernie at turing dot une dot edu dot au>

    In definition of f_primetest, changed ztolong(q2->num) to ztoi(q2->num)
    so that the sign of count in ptest(n, count, skip) is not lost; and
    ztolong(q3->num) to q3->num so that skip can be any integer.
    <ernie at turing dot une dot edu dot au>

    In zprime.c, in definition of small_factor(), adds "&& *tp != 1" to
    the exit condition in the for loop so that searching for a factor
    will continue beyond the table of primes, as required for e.g.
    factor(2^59 - 1).  <ernie at turing dot une dot edu dot au>

    Changed zprimetest() so that skip in ptest(n, count, skip)
    determines the way bases for the tests are selected.  Neg values of
    n are treated differently.   When considering factorization,
    primeness, etc. one is concerned with equivalence classes which for
    the rational integers are {0}, {-1, 1}, {-2, 2}, etc.  To refer to
    an equivalence class users may use any of its elements but when
    returning a value for a factor the computer normally gives the
    non-negative member.  The same sort of thing happens with integers
    modulo an integer, with fractions, etc., etc.  E.g. users may refer
    to 3/4 as 6/8 or 9/12, etc.  A simple summary of the way negative n
    is treated is "the sign is ignored". E.g. isprime(-97) and
    nextprime(-97) now return the same as isprime(97) and nextprime(97).
    <ernie at turing dot une dot edu dot au>


The following are the changes from calc version 2.10.1t11 to 2.10.1t19:

    Added many more regression tests to lib/regress.cal.  Some
    due to <ernie at turing dot une dot edu dot au>.

    Added many help files, most due to <ernie at turing dot une dot edu dot au>.

    Fixed exp() and ln() so that when they return a complex value with
    a zero imaginary component, isreal() is true.  <ernie at turing dot
    une dot edu dot au>

    Fixed cast problem in byteswap.c.  <ernie at turing dot une dot edu dot au>

    Fixed memory leak problem where repeated assignments did not
    free the previous value.  <ernie at turing dot une dot edu dot au>

    Complex number ordering/comparison has been changed such that:

        a < b implies a + c < b + c
        a < b and c > 0 implies a * c < b * c
        a < b implies -a > -b

    To achieve a "natural" partial ordering of the complex numbers
    with the above properties, cmp(a,b) for real or complex numbers
    may be considered as follows:

        cmp(a,b) = sgn(re(a) - re(b)) + sgn(im(a) - im(b)) * 1i

    The cmp help file has been updated.

    Change HASH type to QCKHASH.  The HASH type is a name better suited
    for the upcoming one-way hash interface.

    Added the CONFIG type; a structure containing all of the configuration
    values under the control of config().  Added V_CONFIG data type.
    The call config("all") returns a V_CONFIG.  One may now save/restore
    the configuration state as follows:

        x = config("all")
        ...
        config("all",x)

    Added two configuration aliases, "oldstd" (for old backward compatible
    standard configuration) and "newstd" (for new style configuration).
    One may set the historic configuration state by:

        config("all", "oldstd")

    One may use what some people consider to be a better but not backward
    compatible configuration state by:

        config("all", "newstd")

    Renamed config.h (configuration file built during the make) to conf.h.
    Added a new config.h to contain info on the V_CONFIG type.

    Fixed some ANSI C compile warnings.

    The show config output is not indented by only one tab, unless
    config("tab",0) in which case it is not indented.

    The order of show config has been changed to reflect the config
    type values.

    Changed declaration of sys_errlst in func.c to be char *.

    Added quo(x,y,rnd) and mod(x,y,rnd) to give function interfaces
    to // and % with rounding mode arguments.  Extended these functions
    to work for list-values, complex numbers and matrices.
    <ernie at turing dot une dot edu dot au>

    For integer x, cfsim(x,8) returns 0.
    <ernie at turing dot une dot edu dot au>

    Fixed config("leadzero").  <ernie at turing dot une dot edu dot au>

    Set config("cfsim",8) by default (in "oldstd").  Setup initial idea for
    config("all", "newstd") to be the default with the following changes:

        display         10
        epsilon         1e-10
        quo             0
        outround        24
        leadzero        1
        fullzero        1
        prompt          "; "            (allows full line cut/paste)
        more            ";; "           (allows full line cut/paste)

    The "newstd" is a (hopefully) more preferred configuration than the
    historic default.

    The fposval.h file defines DEV_BITS and INODE_BITS giving the
    bit size of the st_dev and st_ino stat elements.  Also added
    SWAP_HALF_IN_DEV and SWAP_HALF_IN_STSIZE.

    Added sec(), csc(), cot(), sech(), csch(), coth(), asec(), acsc(),
    acot(), asech(), acsch() and acoth() builtins. <ernie at turing dot
    une dot edu dot au>

    The initmasks() call is no longer needed.  The bitmask[] array
    is a compiled into zmath.c directly.

    Added isconfig(), ishash(), isrand() and israndom() builtins to
    test is something is a configuration state, hash state, RAND
    state or RANDOM state.

    The lib/cryrand.cal library now no longer keeps the Blum prime
    factors used to form he Blum modulus.  The default modulus has
    been expanded to 1062 bits product of two Blum primes.

    The function hash_init() is called to initialize the hash function
    interface.

    Misc calc man page fixes and new command line updates.

    Fixed bug related to srand(1).

    Cleaned up some warning messages.

    All calls to math_error() now have a /*NOTREACHED*/ comment after
    them.  This allows lint and compiler flow progs to note the jumpjmp
    nature of math_error().  Unfortunately some due to some systems
    not dealing with /*NOTREACHED*/ comments correctly, calls of the form:

        if (foo)
                math_error("bar");

    must be turned into:

        if (foo) {
                math_error("bar");
                /*NOTREACHED*/
        }

    The ploy() function can take a list of coefficients.  See the
    help/poly file.  Added poly.c.  <ernie at turing dot une dot edu
    dot au>

    Fixes and performance improvements to det().  <ernie at turing dot
    une dot edu dot au>

    Renamed atoq() and atoz() to str2q() and str2z() to avoid conflicts
    with libc function names.

    Fixed use of ${NROFF_ARG} when ${CATDIR} and ${NROFF} are set.

    Fixed SWAP_HALF_IN_B64 macro use for Big Endian machines without
    long long or with LONGLONG_BITS=0.

    Added error() and iserror() to generate a value of a given error type.
    See help/error for details.  <ernie at turing dot une dot edu dot au>

    Added singular forms of help files.  For example one can now get
    help for binding, bug, change, errorcode and type.

    The builtin mmin(x, md) has been changed to return the same as
    mod(x, md, 16).  The old mmin(x, md) required md to be a positive
    integer and x to be an integer.  Now md can be any real number; x
    can be real, complex, or a matrix or list with real elements, etc.
    <ernie at turing dot une dot edu dot au>

    The builtin avg(x_1, x_2, ...) has been changed to accept list-valued
    arguments:  a list x_i contributes its elements to the list of
    items to be averaged.  E.g. avg(list(1,2,list(3,4)),5) is treated
    as if it were avg(1,2,3,4,5).  If an error value is encountered in
    the items to be averaged, the first such value is returned.  If the
    number of items to be averaged is zero, the null value is returned.
    <ernie at turing dot une dot edu dot au>

    The builtin hmean(x_1, x_2, ...) has been changed to admit types
    other than real for x_1, x_2, ...; list arguments are treated in
    the same way as in avg().  <ernie at turing dot une dot edu dot au>

    The builtin eval(str) has been changed so that when str has a
    syntax error, instead of call to math_error(), an error value is
    returned.  <ernie at turing dot une dot edu dot au>

    The old frem(x,y) builtin returned the wrong value when y was a power of
    2 greater than 2, e.g. f(8,4) is returned as 4 when its value should be 2.
    This has been fixed by a small change to the definition of zfacrem().
    Calc used to accept with no warning or error message, gcdrem(0,2) or
    generally gcdrem(0,y) for any y with abs(y) > 1, but then went into an
    infinite loop.  This has been fixed by never calling zfacrem() with zero x.
    Both frem(x,y) and gcdrem(x,y) now reject y = -1, 0 or 1 as errors.  For
    nonzero x, and y == -1 or 1, defining frem(x,y) and gcdrem(x,y) to equal
    abs(x) is almost as natural as defining x^0 to be 1.  Similarly, if x is
    not zero then gcdrem(x,0) == 1.  <ernie at turing dot une dot edu dot au>

    Plugged some more memory leaks.

    Fixed bug related randbit(x) skip (where x < 0).

    Added seedrandom.cal to help users use the raw random() interface well.

    Made extensive additions and changes to the rand() and random() generator
    comments in zrand.c.

    Fixed a bug in fposval.c that prevented calc from compiling on systems
    with 16 bit device and/or inodes.  Fixed error messages in fposval.c.

    Fixed bug that would put calc into an infinite loop if it is ran
    with errors in startup files (calc/startup, .calcrc).
    Ha Lam <hl at kuhep5 dot phsx dot ukans dot edu>


The following are the changes from calc version 2.10.0t13 to 2.10.1t10:

    Added SB8, USB8, SB16, USB16, SB32, USB32 typedefs, determined by
    longbits and declared in longbits.h, to deal with 8, 16 and 32 bit
    signed and unsigned values.

    The longbits.h will define HAVE_B64 with a 64 bit type (long or
    longlong) is available.   If one is, then SB64 and US64 typedefs
    are declared.

    The U(x) and L(x) macros only used to define 33 to 64 bit signed
    and unsigned constants.  Without HAVE_B64, these macros cannot
    be used.

    Changed the way zmath.h declares types such as HALF and FULL.

    Changed the PRINT typedef.

    The only place where the long long type might be used is in longlong.c
    and if HAVE_LONGLONG, in longbits.h if it is needed.  The only place
    were a long long constant might be used is in longlong.c.  Any
    long long constants, if HAVE_LONGLONG, are hidden under the U(x) and
    L(x) macros on longbits.h.  And of course, if you don't have long long,
    then HAVE_LONGLONG will NOT be defined and long long's will not be used.

    The longlong.h file is no longer directly used by the main calc source.
    It only comes into play when compiling the longbits tool.

    Added config("prompt") to change the default interactive prompt ("> ")
    and config("more") to change the default continuation prompt (">> ").

    Makefile builds align32.h with determines if 32 bit values must always
    be aligned on 32 bit boundaries.

    The CALCBINDINGS file is searched for along the CALCPATH.  The Makefile
    defines the default CALCBINDINGS is "bindings" (or "altbind") which
    is now usually found in ./lib or ${LIBDIR}.

    Per Ernest Bowen <ernie at turing dot une dot edu dot au>, an optional
    third argument was added  sqrt() so that in sqrt(x,y,z), y and z have
    essentially the same role as in appr(x,y,z) except that of course
    what is being approximated is the sqrt of x.  Another difference is
    that two more bits of z are used in sqrt: bit 5 gives the option of
    exact results when they exist (the value of y is then ignored) and
    bit 6 returns the non-principal root rather than the principal value.

    If commands are given on the command line, leading tabs are not
    printed in output.  Giving a command on the command line implies
    that config("tab",0) was given.

    Pipe processing is enabled by use of -p.  For example:

        echo "print 2^21701-1, 2^23209-1" | calc -p | fizzbin

    In pipe mode, calc does not prompt, does not print leading tabs
    and does not print the initial version header.

    Calc will now form FILE objects for any open file descriptor > 2
    and < MAXFILES.  Calc assumes they are available for reading
    and writing.  For example:

        $ echo "A line of text in the file on descriptor 5" > datafile
        $ calc 5<datafile
        C-style arbitrary precision calculator (version 2.10.1t3)
        [Type "exit" to exit, or "help" for help.]

        ; files(5)
                FILE 5 "descriptor[5]" (unknown_mode, pos 0)
        ; fgetline(files(5))
                "A line of text in the file on descriptor 5"

    The -m mode flag now controls calc's ability to open files
    and execute programs.  This mode flag is a single digit that
    is processed in a similar way as the octal chmod values:

        0   do not open any file, do not execute progs
        1   do not open any file
        2   do not open files for reading, do not execute progs
        3   do not open files for reading
        4   do not open files for writing, do not execute progs
        5   do not open files for writing
        6   do not execute any program
        7   allow everything (default mode)

    Thus if one wished to run calc from a privileged user, one might
    want to use -m 0 in an effort to make calc more secure.

    The -m flags for reading and writing apply on open.
    Files already open are not effected.  Thus if one wanted to use
    the -m 0 in an effort to make calc more secure, but still be
    able to read and write a specific file, one might do:

        calc -m 0 3<a.file 4>b.file

        NOTE: Files presented to calc in this way are opened in an unknown
              mode.  Calc will try to read or write them if directed.

    The maximum command line size it MAXCMD (16384) bytes.  Calc objects to
    command lines that are longer.

    The -u flag cause calc to un-buffer stdin and stdout.

    Added more help files.  Improved other help files.

    Removed trailing blanks from files.

    Removed or rewrite the formally gross and disgusting hacks for
    dealing with various sizes and byte sex FILEPOS and off_t types.

    Defined ilog2(x), ilog10(x), ilog(x,y) so that sign of x is ignored,
    e.g. ilog2(x) = ilog2(abs(x)).

    The sixth bit of rnd in config("round", rnd) and config("bround", rnd)
    is used to specify rounding to the given number of significant
    digits or bits rather than places, e.g. round(.00238, 2, 32)
    returns .0023, round(.00238, 2, 56) returns .0024.


The following are the changes from calc version 2.9.3t11 to 2.10.0t12:

    The default ${LIBDIR}/bindings CALCBINDINGS uses ^D for editing.
    The alternate CALCBINDINGS ${LIBDIR}/altbind uses ^D for EOF.

    The Makefile CC flag system has been changed.  The new CC flag system
    includes:

        CCMAIN are flags for ${CC} when compiling only files with main()
        CCOPT are flags given to ${CC} for optimization
        CCWARN are flags given to ${CC} for warning message control
        CCMISC are misc flags given to ${CC}

        CNOWARN are all flags given to ${CC} except ${CCWARN} flags
        CFLAGS are all flags given to ${CC}
        ICFLAGS are given to ${CC} for intermediate progs

        LCFLAGS are CC-style flags for ${LINT}
        LDFLAGS are flags given to ${CC} for linking .o files
        ILDFLAGS are given to ${CC} for linking .o's for intermediate progs

        CC is how the C compiler is invoked

    The syntax error:

        print a[3][[4]]

    used to send calc into a loop printing 'missing expression'.  This
    has been fixed.

    Added config("maxerr") and config("maxerr",val) to control the
    maximum number of errors before a computation is aborted.

    Removed regress.cal test #952 and #953 in case calc's stdout or
    stderr is re-directed to a non-file by some test suite.

    Changed how <stdarg.h>, <varags.h> or simulate stdarg is determined.
    Changed how vsprintf() vs sprintf() is determined.  The args.h file
    is created by Makefile to test which combination works.  Setting
    VARARG and/or HAVE_VSPRINTF in the Makefile will alter these tests
    and direct a specific combination to be used.  Removed have_vs.c,
    std_arg.h and try_stdarg.c.  Added have_stdvs.c and have_varvs.c.

    Added 3rd optional arg to round(), bround(), appr() to specify the type of
    rounding to be used.

    Moved fnvhash.c to quickhash.c.

    Fixed a bug in appr rounding mode when >= 16.

    Added test2600.cal and test2700.cal. They are used by the regress.cal
    to provide a more extensive test suite for some builtin numeric
    functions.


The following are the changes from calc version 2.9.3t9.2+ to 2.9.3t10:

    Added many help files for builtin functions and some symbols.
    More help files are needed, see help/todo.

    Removed the calc malloc code.  Calc now uses malloc and free to
    manage storage since these implementations are often written to
    work best for the local system.  Removed CALC_MALLOC code and
    Makefile symbol.  Removed alloc.c.

    Added getenv("name"), putenv("name=val") and putenv("name, "val")
    builds for environment variable support thanks to "Dr." "D.J." Picton
    <dave at aps2 dot ph dot bham dot ac dot uk>.

    Added system("shell command") builtin to execute shell commands,
    thanks to "Dr." "D.J." Picton <dave at aps2 dot ph dot bham dot ac dot uk>.

    Added isatty(fd) builtin to determine if fd is attached to a tty
    thanks to "Dr." "D.J." Picton <dave at aps2 dot ph dot bham dot ac dot uk>.

    Added cmdbuf() builtin to return the command line executed by calc's
    command line args thanks to "Dr." "D.J." Picton <dave at aps2 dot
    ph dot bham dot ac dot uk>.

    Added strpos(str1,str2) builtin to determine the first position where
    str2 is found in str1 thanks to "Dr." "D.J." Picton
    <dave at aps2 dot ph dot bham dot ac dot uk>.

    Fixed bug that caused:

        global a,b,c            (newline with no semicolon)
        read test.cal

    the read command to not be recognized.

    The show command looks at only the first 4 chars of the argument so
    that:

        show globals
        show global
        show glob

    do the same thing.

    Added show config to print the config values and parameters thanks
    to Ernest Bowen <ernie at turing dot une dot edu dot au>.

    Added show objtypes to print the defined objects thanks to Ernest Bowen
    <ernie at turing dot une dot edu dot au>.

    Added more builtin function help files.

    Fixed the 3rd arg usage of the root builtin.

    Expanded the regress.cal regression test suite.

    Fixed -- and ++ with respect to objects and assignment (see the 2300
    series in regress.cal).

    Added isident(m) to determine if m is an identity matrix.

    The append(), insert() and push() builtins can now append between
    1 to 100 values to a list.

    Added reverse() and join() builtins to reverse and join lists
    thanks to Ernest Bowen <ernie at turing dot une dot edu dot au>.

    Added sort() builtin to sort lists thanks to Ernest Bowen
    <ernie at turing dot une dot edu dot au>.

    Added head(), segment() and tail() builtins to return the head,
    middle or tail of lists thanks to Ernest Bowen <ernie at turing dot
    une dot edu dot au>.

    Added more and fixed some help files.

    The builtin help file is generated by the help makefile.  Thus it will
    reflect the actual calc builtin list instead of the last time someone
    tried to update it correctly.  :-)

    Fixed non-standard void pointer usage.

    Fixed base() bug with regards to the default base.

    Renamed MATH_PROTO() and HIST_PROTO() to PROTO().  Moved PROTO()
    into prototype.h.

    Fixed many function prototypes.  Calc does not declare functions
    as static in one place and extern in another.  Where reasonable
    function prototypes were added.  Several arg mismatch problems
    were fixed.

    Added support for SGI MIPSpro C compiler.

    Changes the order that args are declared to match the order
    of the function.  Some source tools got confused when:
    arg order did not match as in:

        void
        funct(foo,bar)
                int bar;        /* this caused a problem */
                char *foo;      /* even though it should not! */
        {
        }


The following are the changes from calc version 2.9.3t8 to 2.9.3t9.2:

    Use of the macro zisleone(z) has been clarified.  The zisleone(z) macro
    tests if z <= 1.  The macro zisabsleone(z) tests of z is 1, 0 or -1.
    Added zislezero(z) macro.  Bugs are related to this confusion have
    been fixed.

    Added zge64b(z) macro to zmath.h.

    Added the macro zgtmaxufull(z) to determine if z will fit into a FULL.
    Added the macro zgtmaxlong(z) to determine if z will fit into a long.
    Added the macro zgtmaxulong(z) to determine if z will fit into a unsigned
    long.

    Added the macro ztoulong(z) to convert an absolute value of a ZVALUE to
    an unsigned long, or to convert the low order bits of a ZVALUE.
    Added the macro ztolong(z) to convert an absolute value of a ZVALUE to
    an long, or to convert the low order bits of a ZVALUE.

    Some non-ANSI C compilers define __STDC__ to be 0, whereas all ANSI
    C compiles define it as non-zero.  Code that depends on ANSI C now
    uses #if defined(__STDC__) && __STDC__ != 0.

    Fixed ptest(a,b) bug where (a mod 2^32) < b.  Previously ptest()
    incorrectly returned 1 in certain cases.

    The second ptest() argument, which is now optional, defaults to 1.
    This ptest(x) is the same as ptest(x,1).

    Added an optional 3rd argument to ptest().  The 3rd arg tells how many
    tests to skip.  Thus ptest(a,10) performs the same probabilistic
    tests as ptest(a,3) and ptest(a,7,3).

    The ptest() builtin by default will determine if a value is divisible
    by a trivial prime.  Thus, ptest(a,0) will only perform a quick trivial
    factor check.  If the test count is < 0, then this trivial factor check
    is omitted.  Thus ptest(a,10) performs the same amount of work as
    ptest(a,3) and ptest(a,-7,3) and the same amount of work as
    ptest(a,-3) and ptest(a,7,3).

    Added nextcand(a[,b[,c]]) and prevcand(a[,b[,c]]) to search for the
    next/previous value v > a (or v < a) that passes ptest(v[,b[,c]]).
    The nextcand() and prevcand() builtins take the same arguments
    as ptest().

    Added nextprime(x) and and prevprime(x) return the next and
    previous primes with respect to x respectively.  As of this
    release, x must be < 2^32.  With one argument, they will return
    an error if x is out of range.  With two arguments, they will
    not generate an error but instead will return y.

    Fixed some memory leaks, particularly those related with pmod().

    Fixed some of the array bounds reference problems in domult().

    Added a hack-a-round fix for the uninitialized memory reference
    problems in zsquare/dosquare.

    The LIBRARY file has been updated to include a note about calling
    zio_init() first.  Also some additional useful macros have been noted.

    The lfactor() function returns -1 when given a negative value.
    It will not search for factors beyond 2^32 or 203280221 primes.
    Performance of lfactor() has been improved.

    Added factor(x,y) to look for the smallest factor < min(sqrt(x),y).

    Added libcalcerr.a for a math_error() routine for the convince of
    progs that make use of libcalc.a.  This routine by default will
    print an message on stderr and exit.  It can also be made to
    longjump instead.  See the file LIBRARY under ERROR HANDING.

    Added isprime() to test if a value is prime.  As of this release,
    isprime() is limited to values < 2^32.  With one argument,
    isprime(x) will return an error if x is out of range.  With
    two arguments, isprime(x,y) will not generate an error but
    instead will return y.

    Added pix(x) to return the number of primes <= x.  As of this
    release, x must be < 2^32.  With one argument, pix(x) will
    return an error if x is out of range.  With two arguments,
    pix(x,y) will not generate an error but instead will return y.

    Fixed the way *.h files are formed.  Each file guards against
    multiple inclusion.

    Fixed numeric I/O on 64 bit systems.  Previously the print and
    constant conversion routines assumed a base of 2^16.

    Added support for 'long long' type.  If the Makefile is setup
    with 'LONGLONG_BITS=', then it will attempt to detect support
    for the 'long long' type.  If the Makefile is setup with
    'LONGLONG_BITS=64', then a 64 bit 'long long' is assumed.
    Currently, only 64 bit 'long long' type is supported.
    Use of 'long long' allows one to double the size of the
    internal base, making a number of computations much faster.
    If the Makefile is setup with 'LONGLONG_BITS=0', then the
    'long long' type will not be used, even if the compiler
    supports it.

    Fixed avg() so that it will correctly handle matrix arguments.

    Fixed btrunc() limit.

    The ord("string") function can now take a string of multiple
    characters.  However it still will only operate on the first
    character.

    Renamed stdarg.h to std_arg.h and endian.h endian_calc.h to
    avoid name conflicts with /usr/include on some systems that
    have make utilities that are too smart for their own good.

    Added additive 55 shuffle generator functions rand(), randbits()
    and its seed function srand().  Calling rand(a,b) produces a
    random value over the open half interval [a,b).  With one arg,
    rand(a) is equivalent to rand(0,a).  Calling rand() produces
    64 random bits and is equivalent to rand(0,2^64).

    Calling randbit(x>0) produces x random bits.  Calling randbit(skip<0)
    skips -skip bits and returns -skip.

    The srand() function will return the current state.  The call
    srand(0) returns the initial state.  Calling srand(x), where
    x > 0 will seed the generator to a different state.  Calling
    srand(mat55) (mat55 is a matrix of integers at least 55 elements long)
    will seed the internal table with the matrix elements mod 2^64.
    Finally calling srand(state) where state is a generator state
    also sets/seeds the generator.

    The cryrand.cal library has been modified to use the builtin
    rand() number generator.  The output of this generator is
    different from previous versions of this generator because
    the rand() builtin does not match the additive 55 / shuffle
    generators from the old cryrand.cal file.

    Added Makefile support for building BSD/386 releases.

    The cmp() builtin can now compare complex values.

    Added the errno() builtin to return the meaning of errno numbers.

    Added fputc(), fputs(), fgets(), ftell(), fseek() builtins.

    Added fsize() builtin to determine the size of an open file.

    Supports systems where file positions and offsets are longer than 2^32
    byte, longer than long and/or are not a simple type.

    When a file file is printed, the file number is also printed:

        FILE 3 "/etc/motd" (reading, pos 127)

    Added matsum() to sum all numeric values in a matrix.

    The following code now works, thanks to a fix by <ernie at turing
    dot une dot edu dot au> (Ernest Bowen):

                mat A[3] = {1, 2, 3};
                A[0] = A;
                print A[0];

    Also thanks to ernie, calc can process compound expressions
    such as 1 ? 2 ? 3 : 4 : 5.

    Also^2 thanks to ernie, the = operator is more general:

                (a = 3) = 4             (same as a = 3; a = 4)
                (a += 3) *= 4           (same as a += 3; a *= 4)
                matfill(B = A, 4)       (same as B = A; matfill(B, 4);)

    Also^3 thanks to ernie, the ++ and -- operators are more general.

                a = 3
                ++(b = a)               (a == 3, b == 4)
                ++++a                   (a == 5)
                (++a)++ == 6            (a == 7)
                (++a) *= b              (a == 32, b == 4)

    Fixed a bug related to calling epsilon(variable) thanks to ernie.

    Removed trailing whitespace from source and help files.

    Some compilers do not support the const type.  The file have_const.h,
    which is built from have_const.c will determine if we can or should
    use const.  See the Makefile for details.

    Some systems do not have uid_t.  The file have_uid_t.h, which
    is built from have_uid_t.c will determine if we can or should
    depend on uid_t being typedefed by the system include files.
    See the Makefile for details.

    Some systems do not have memcpy(), memset() and strchr().  The
    file have_newstr.h, which is built from have_newstr.c will
    determine if we can or should depend libc providing these
    functions.  See the Makefile for details.

    The Makefile symbol DONT_HAVE_VSPRINTF is now called HAVE_VSPRINTF.
    The file have_vs.h, which is built from have_vs.c will determine if
    we can or should depend libc providing vsprintf().  See the Makefile
    for details.

    Removed UID_T and OLD_BSD symbols from the Makefile.

    A make all of the upper level Makefile will cause the all rule
    of the lib and help subdirs to be made as well.

    Fixed bug where reserved keyword used as symbol name caused a core dump.


The following are the changes from calc version 2.9.3t7 to 2.9.3t7:

    The 'show' command by itself will issue an error message
    that will remind one of the possible show arguments.
    (thanks to Ha S. Lam <hl at kuhep4 dot phsx dot ukans dot edu>)

    Fixed an ANSI-C related problem with the use of stringindex()
    by the show command.  ANSI-C interprets "bar\0foo..." as if
    it were "bar\017oo...".

    Added a cd command to change the current directory.
    (thanks to Ha S. Lam <hl at kuhep4 dot phsx dot ukans dot edu>)

    Calc will not output the initial version string, startup
    message and command prompt if stdin is not a tty.  Thus
    the shell command:

        echo "fact(100)" | calc

    only prints the result.  (thanks to Ha S. Lam <hl at kuhep4 dot phsx
    dot ukans dot edu>)

    The zmath.h macro zisbig() macro was replaced with zlt16b(),
    zge24b(), zge31b(), zge32b() and zgtmaxfull() which are
    independent of word size.

    The 'too large' limit for factorial operations (e.g., fact, pfact,
    lcmfact, perm and comb) is now 2^24.  Previously it depended on the
    word size which in the case of 64 bit systems was way too large.

    The 'too large' limit for exponentiation, bit position (isset,
    digit, ), matrix operations (size, index, creation), scaling,
    shifting, rounding and computing a Fibonacci number is 2^31.
    For example, one cannot raise a number by a power >= 2^31.
    One cannot test for a bit position >= 2^31.  One cannot round
    a value to 2^31 decimal digit places.  One cannot compute
    the Fibonacci number F(2^31).

    Andy Fingerhut <jaf at dworkin dot wustl dot edu> (thanks!) supplied
    a fix to a subtle bug in the code generation routines.  The basic
    problem was that addop() is sometimes used to add a label to
    the opcode table of a function.  The addop() function did some
    optimization tricks, and if one of these labels happens to be an
    opcode that triggers optimization, incorrect opcodes were generated.

    Added utoz(), ztou() to zmath.c, and utoq(), qtou() to qmath.c
    in preparation for 2.9.3t9 mods.


The following are the changes from calc version 2.9.2 to 2.9.3t7:

    Calc can now compile on OSF/1, SGI and IBM RS6000 systems.

    A number of systems that have both <varargs.h> and <stdarg.h> do
    not correctly implement both types.  On some System V, MIPS and DEC
    systems, vsprintf() and <stdarg.h> do not mix.  While calc will
    pass the regression test, use of undefined variables will cause
    problems.  The Makefile has been modified to look for this problem
    and work around it.

    Added randmprime.cal which find a prime of the form h*2^n-1 >= 2^x
    for some given x.  The initial search points for 'h' and 'n'
    are selected by a cryptographic pseudo-random generator.

    The library script nextprim.cal is now a link to nextprime.cal.
    The lib/Makefile will take care of this link and install.

    The show command now takes singular forms.  For example, the
    command 'show builtin' does the same as 'show builtins'.  This
    allows show to match the historic singular names used in
    the help system.

    Synced 'show builtin' output with 'help builtin' output.

    Fixed the ilog2() builtin.  Previously ilog2(2^-20) returned
    -21 instead of -20.

    The internal function qprecision() has been fixed.  The changes
    ensure that for any e for which 0 < e <= 1:

        1/4 < sup(abs(appr(x,e) - x))/e  <= 1/2.

    Here 'sup' denotes the least upper bound over values of x (supremum).
    Previously calc did: 1/4 <= sup(abs(appr(x,e) - x))/e  < 1.

    Certain 64 bit processors such as the Alpha are now supported.

    Added -once to the READ command.  The command:

        read -once filename

    like the regular READ expect that it will ignore filename if
    is has been previously read.

    Improved the makefile.  One now can select the compiler type.  The
    make dependency lines are now simple foo.o: bar.h lines.  While
    this makes for a longer list, it is easier to maintain and will
    make future Makefile patches smaller.  Added special options for
    gcc version 1 & 2, and for cc on RS6000 systems.

    Calc compiles cleanly under the watchful eye of gcc version 2.4.5
    with the exception of warnings about 'aggregate has a partly
    bracketed initializer'.  (gcc v2 should allow you to disable
    this type of warning with using -Wall)

    Fixed a longjmp bug that clobbered a local variable in main().

    Fixed a number of cases where local variables or malloced storage was
    being used before being set.

    Fixed a number of fence post errors resulting in reads or writes
    just outside of malloced storage.

    A certain parallel processor optimizer would give up on
    code in cases where math_error() was called.  The obscure
    work-a-rounds involved initializing or making static, certain
    local variables.

    The cryrand.cal library has been improved.  Due to the way
    the initial quadratic residues are selected, the random numbers
    produced differ from previous versions.

    The printing of a leading '~' on rounded values is now a config
    option.  By default, tilde is still printed.  See help/config for
    details.

    The builtin function base() may be used to set the output mode or
    base.  Calling base(16) is a convenient shorthand for typing
    config("mode","hex").  See help/builtin.

    The printing of a leading tab is now a config option.  This does not
    alter the format of functions such as print or printf.  By default,
    a tab is printed.  See help/config for details.

    The value atan2(0,0) now returns 0 value in conformance with
    the 4.3BSD ANSI/IEEE 754-1985 math library.

    For all values of x, x^0 yields 1.  The major change here is
    that 0^0 yields 1 instead of an error.

    Fixed gcd() bug that caused gcd(2,3,1/2) to ignore the 1/2 arg.

    Fixed ltol() rounding so that exact results are returned, similar
    to the way sqrt() and hypot() round, when they exist.

    Fixed a bug involving ilog2().

    Fixed quomod(a,b,c,d) to give correct value for d when a is between
    0 and -b.

    Fixed hmean() to perform the necessary multiplication by the number of
    arguments.

    The file help/full is now being built.

    The man page is not installed by default.  One may install either
    the man page source or the cat (formatted man) page.  See the
    Makefile for details.

    Added a quit binding.  The file lib/bindings2 shows how this new
    binding may be used.

    One can now do a 'make check' to run the calc regression test
    within in the source tree.

    The regression test code is now more extensive.

    Updated the help/todo list.  A BUGS file was added.  Volunteers are
    welcome to send in patches!


The following are the changes from calc version 2.9.1 to 2.9.1:

    Fixed floor() for values -1 < x < 0.

    Fixed ceil() for values -1 < x < 0.

    Fixed frac() for values < 0 so that int(x) + frac(x) == x.

    Fixed wild fetch bug in zdiv, zquo and zmod code.

    Fixed bug which caused regression test #719 to fail on some machines.

    Added more regression test code.


The following are the changes from calc version 2.9.0 to 2.9.0:

    A major bug was fixed in subtracting two numbers when the first
    number was zero.  The problem caused wrong answers and core dumps.


The following are the changes from calc version 1.27.0 to 2.8.0:

    Full prototypes have been provided for all C functions, and are used
    if calc is compiled with an ANSI compiler.

    Newly defined variables are now initialized to the value of zero instead
    of to the null value.  The elements of new objects are also initialized
    to the value of zero instead of null.

    The gcd, lcm, and ismult functions now work for fractional values.

    A major bug in the // division for fractions with a negative divisor
    was fixed.

    A major bug in the calculation of ln for small values was fixed.

    A major bug in the calculation of the ln and power functions for complex
    numbers was fixed.

    A major lack of precision for sin and tan for small values was fixed.

    A major lack of precision for complex square roots was fixed.

    The "static" keyword has been implemented for variables.  So permanent
    variables can be defined to have either file scope or function scope.

    Initialization of variables during their declaration are now allowed.
    This is most convenient for the initialization of static variables.

    The matrix definition statement can now be used within a declaration
    statement, to immediately define a variable as a matrix.

    Initializations of the elements of matrices are now allowed.  One-
    dimensional matrices may have implicit bounds when initialization is
    used.

    The obj definition statement can now be used within a declaration
    statement, to immediately define a variable as an object.

    Object definitions can be repeated as long as they are exactly the same
    as the previous definition.  This allows the rereading of files which
    happen to define objects.

    The integer, rational, and complex routines have been made into a
    'libcalc.a' library so that they can be used in other programs besides
    the calculator.  The "math.h" include file has been split into three
    include files: "zmath.h", "qmath.h", and "cmath.h".

Following is a list of visible changes to calc from version 1.26.4 to 1.26.4:

    Added an assoc function to return a new type of value called an
    association.  Such values are indexed by one or more arbitrary values.
    They are stored in a hash table for quick access.

    Added a hash() function which accepts one or more values and returns
    a quickly calculated small non-negative hash value for those values.

Following is a list of visible changes to calc from version 1.26.2 to 1.26.4:

    Misc fixes to Makefiles.

    Misc lint fixes.

    Misc portability fixes.

    Misc typo and working fixes to comments, help files and the man page.

Following is a list of visible changes to calc from version 1.24.7 to 1.26.1:

    There is a new emacs-like command line editing and edit history
    feature.  The old history mechanism has been removed.  The key
    bindings for the new editing commands are slightly configurable
    since they are read in from an initialization file.  This file is
    usually called /usr/lib/calc/bindings, but can be changed by the
    CALCBINDINGS environment variable.  All editing code is
    self-contained in the new files hist.c and hist.h, which can be
    easily extracted and used in other programs.

    Two new library files have been added: chrem.cal and cryrand.cal.
    The first of these solves the Chinese remainder problem for a set
    of modulo's and remainders. The second of these implements several
    very good random number generators for large numbers.

    A small bug which allowed division by zero was fixed.

    A major bug in the mattrans function was fixed.

    A major bug in the acos function for negative arguments was fixed.

    A major bug in the strprintf function when objects were being printed
    was fixed.

    A small bug in the library file regress.cal was fixed.

## Copyright (C) 2001-2017,2021-2023  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.
##
## Under source code control:   1993/06/02 18:12:57
## File existed as early as:    1989
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/

*************
* contrib
*************

Calc is open source. Contributions of code are welcome.

In order to consider integrating your contributions, we need:

    * your changes applied agsinst the top of the calc master branch:

          https://github.com/lcn2/calc/

    * new help files or help file patches, if applicable (documentation)

    * Update CHANGES file (brief description of what it does)

    * regress.cal test patch as needed

If you add functionality to calc, please be sure to modify
Makefiles, help files, cal/regress.cal test code as well.
Regression test cases are vital to maintaining calc's level
of correctness and helps us avoid code bug regression.

The best way contribute to calc bug is to generate calc
GitHub pull request against the calc GitHub repo:

    https://github.com/lcn2/calc/pulls

Please be patient as we cannot always respond pull requests quickly.

=-=

IMPORTANT:

Your code needs to be contributed under either the 2.1 of the GNU
Lesser General Public License (LGPL 2.1) or under "The Unlicense":

    https://unlicense.org

=-=

See also the calc wishlist by running the calc command:

    ; help wishlist

=-=

## Copyright (C) 1999,2014,2021,2023  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.
##
## 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/

*************
* todo
*************

Calc Todo Items:

=-=

High priority items:

    * Improve the way that calc parses statements such as if, for, while
      and do so that when a C programmer does.  This works as expected:

            if (expr) {
                ...
            }

      However this WILL NOT WORK AS EXPECTED:

            if (expr)
            {
                ...
            }

      because calc will parse the if being terminated by
      an empty statement followed by a

            if (expr) ;
            {
                ...
            }

      See also "help statement", "help unexpected", "help todo", and
      "help bugs".

    * Consider using GNU autoconf / configure to build calc.

    * It is overkill to have nearly everything wind up in libcalc.
      Form a libcalcmath and a libcalclang so that an application
      that just wants to link with the calc math libs can use them
      without dragging in all of the other calc language, I/O,
      and builtin functions.

    * Fix any 'Known bugs' as noted in the BUGS file or as
      displayed by 'calc help bugs'.

=-=

Medium priority items:

    * Verify, complete or fix the 'SEE ALSO' help file sections.

    * Verify, complete or fix the 'LINK LIBRARY' help file sections.

    * Verify, complete or fix the 'LIMITS' help file sections.

    * Verify, complete or fix the 'SYNOPSIS' and 'TYPES' help file sections.

    * Perform a code coverage analysis of the 'make check' action
      and improve the coverage (within reason) of the regress.cal suite.

    * Address, if possible and reasonable, any Calc Mis-features
      as noted in the BUGS file or as displayed by 'calc help bugs'.

    * Internationalize calc by converting calc error messages and
      text strings (e.g., calc startup banner, show output, etc.)
      into calls to the GNU gettext internationalization facility.
      If somebody translated these strings into another language,
      setting $LANG would allow calc to produce error messages
      and text strings in that language.

=-=

Low priority items:

    * Complete the use of CONST where appropriate:

        CONST is beginning to be used with read-only tables and some
        function arguments.  This allows certain compilers to better
        optimize the code as well as alerts one to when some value
        is being changed inappropriately.  Use of CONST as in:

            int foo(CONST int curds, char *CONST whey)

        while legal C is not as useful because the caller is protected
        by the fact that args are passed by value.  However, the
        in the following:

            int bar(CONST char *fizbin, CONST HALF *data)

        is useful because it calls the compiler that the string pointed
        at by 'fizbin' and the HALF array pointer at by 'data' should be
        treated as read-only.

      One should make available a the fundamental math operations
      on ZVALUE, NUMBER and perhaps COMPLEX (without all of the
      other stuff) in a separate library.

    * Clean the source code and document it better.

    * Add a builtin function to access the 64 bit FNV hash which
      is currently being used internally in seed.c.

=-=

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

NOTE:   calc-bug-report Email address no longer in use

        NOTE: Remove spaces and replace 'at' with @, 'dot' with .

    This replaces the old calc-bugs Email address.

    To be sure we see your Email reporting a calc bug, please use the
    following phase in your Email Subject line:

        calc bug report

    That phrase in your subject line will help ensure your
    request will get past our anti-spam filters.  You may have
    additional words in your subject line.

    However, you may find it more helpful to simply subscribe
    to the calc-tester mailing list (see above) and then to
    send your report to that mailing list as a wider set calc
    testers may be able to help you.

=-=

The calc web site is located at:

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

    NOTE: The Email address uses 'asthe', while the web site uses 'isthe'.

## Copyright (C) 1999-2007,2014,2021  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.
##
## Under source code control:   1999/10/20 07:42:55
## File existed as early as:    1999
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/

*************
* wishlist
*************

Calc Enhancement Wish List:

    We welcome calc comments, suggestions, bug fixes, enhancements and
    interesting calc scripts that you would like you see included in
    future distributions.

=-=

Calc is open source. Contributions of code are welcome.

Please read CONTRIB-CODE or run the following calc command:

    ; help contrib

=-=

    *  In general use faster algorithms for large numbers when they
       become known.  In particular, look at better algorithms for
       very large numbers -- multiply, square and mod in particular.

    *  Correct typos in text and code comments.

    *  Implement an autoload feature.  Associate a calc resource filename
       with a function or global variable.  On the first reference of
       such item, perform an automatic load of that file.

    *  Add error handling statements, so that QUITs, errors from the
       'eval' function, division by zeroes, and so on can be caught.
       This should be done using syntax similar to:

                ONERROR statement DO statement;

       Something like signal isn't versatile enough.

    *  Add a debugging capability so that functions can be single stepped,
       breakpoints inserted, variables displayed, and so on.

    *  Figure out how to write all variables out to a file, including
       deeply nested arrays, lists, and objects.

       Add the ability to read and write a value in some binary form.
       Clearly this is easy for non-neg integers.  The question of
       everything else is worth pondering.

    *  Eliminate the need for the define keyword by doing smarter parsing.

    *  Allow results of a command (or all commands) to be re-directed to a
       file or piped into a command.

    *  Add some kind of #include and #define facility.  Perhaps use
       the C pre-processor itself?

    *  Support a more general input and output base mode other than
       just dec, hex or octal.

    *  Implement a form of symbolic algebra.  Work on this has already
       begun.  This will use backquotes to define expressions, and new
       functions will be able to act on expressions.  For example:

            x = `hello * strlen(mom)`;
            x = sub(x, `hello`, `hello + 1`);
            x = sub(x, `hello`, 10, `mom`, "curds");
            eval(x);

       prints 55.

    *  Place the results of previous commands into a parallel history list.
       Add a binding that returns the saved result of the command so
       that one does not need to re-execute a previous command simply
       to obtain its value.

       If you have a command that takes a very long time to execute,
       it would be nice if you could get at its result without having
       to spend the time to re-execute it.

    *  Add a binding to delete a value from the history list.

       One may need to remove a large value from the history list if
       it is very large.  Deleting the value would replace the history
       entry with a null value.

    *  Add a binding to delete a command from the history list.

       Since you can delete values, you might as well be able to
       delete commands.

    *  All one to alter the size of the history list thru config().

       In some cases, 256 values is too small, in others it is too large.

    *  Add a builtin that returns a value from the history list.
       As an example:

            histval(-10)

       returns the 10th value on the history value list, if such
       a value is in the history list (null otherwise).  And:

            histval(23)

       return the value of the 23rd command given to calc, if
       such a value is in the history list (null otherwise).

       It would be very helpful to use the history values in
       subsequent equations.

    *  Add a builtin that returns command as a string from the
       history list.  As an example:

            history(-10)

       returns a string containing the 10th command on the
       history list, if a such a value is in the history list
       (empty string otherwise).  And:

            history(23)

       return the string containing the 23rd command given to calc, if
       such a value is in the history list (empty string otherwise).

       One could use the eval() function to re-evaluate the command.

    *  Allow one to optionally restore the command number to calc
       prompts.  When going back in the history list, indicate the
       command number that is being examined.

       The command number was a useful item.  When one is scanning the
       history list, knowing where you are is hard without it.  It can
       get confusing when the history list wraps or when you use
       search bindings.  Command numbers would be useful in
       conjunction with positive args for the history() and histval()
       functions as suggested above.

    *  Add a builtin that returns the current command number.
       For example:

            cmdnum()

       returns the current command number.

       This would allow one to tag a value in the history list.  One
       could save the result of cmdnum() in a variable and later use
       it as an arg to the histval() or history() functions.

    *  Add a factoring builtin functions.  Provide functions that perform
       multiple polynomial quadratic sieves, elliptic curve, difference
       of two squares, N-1 factoring as so on.  Provide a easy general
       factoring builtin (say factor(foo)) that would attempt to apply
       whatever process was needed based on the value.

       Factoring builtins would return a matrix of factors.

       It would be handy to configure, via config(), the maximum time
       that one should try to factor a number.  By default the time
       should be infinite.  If one set the time limit to a finite
       value and the time limit was exceeded, the factoring builtin
       would return whatever if had found thus far, even if no new
       factors had been found.

       Another factoring configuration interface, via config(), that
       is needed would be to direct the factoring builtins to return
       as soon as a factor was found.

    *  Allow one to config calc break up long output lines.

       The command:  calc '2^100000'  will produce one very long
       line.  Many times this is reasonable.  Long output lines
       are a problem for some utilities.  It would be nice if one
       could configure, via config(), calc to fold long lines.

       By default, calc should continue to produce long lines.

       One option to config should be to specify the length to
       fold output.  Another option should be to append a trailing
       \ on folded lines (as some symbolic packages use).

    *  Allow one to use the READ and WRITE commands inside a function.

    *  Remove or increase limits on factor(), lfactor(), isprime(),
       nextprime(), and prevprime().  Currently these functions cannot
       search for factors > 2^32.

    *  Add read -once -try "filename" which would do nothing
       if "filename" was not a readable file.

=-=

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

NOTE:   calc-bug-report Email address no longer in use

        NOTE: Remove spaces and replace 'at' with @, 'dot' with .

    This replaces the old calc-bugs Email address.

    To be sure we see your Email reporting a calc bug, please use the
    following phase in your Email Subject line:

        calc bug report

    That phrase in your subject line will help ensure your
    request will get past our anti-spam filters.  You may have
    additional words in your subject line.

    However, you may find it more helpful to simply subscribe
    to the calc-tester mailing list (see above) and then to
    send your report to that mailing list as a wider set calc
    testers may be able to help you.

=-=

The calc web site is located at:

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

    NOTE: The Email address uses 'asthe', while the web site uses 'isthe'.

## Copyright (C) 1999,2014,2021  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.
##
## Under source code control:   1991/07/21 04:37:24
## 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/

*************
* credit
*************

Credits

    The majority of calc was written by David I. Bell.

    The Calc primary mirror, calc mailing list and calc bug report
    processing is performed by Landon Curt Noll.

    Landon Curt Noll maintains the master reference source, performs
    release control functions as well as other calc maintenance functions.

    Thanks for suggestions and encouragement from Peter Miller,
    Neil Justusson, Ernest W. Bowen and Landon Noll.

    Thanks to Stephen Rothwell for writing the original version of
    hist.c which is used to do the command line editing.

    Thanks to Ernest W. Bowen for supplying many improvements in
    accuracy and generality for some numeric functions.  Much of
    this was in terms of actual code which I gratefully accepted.
    Ernest also supplied the original text for many of the help files.

    Portions of this program are derived from an earlier set of
    public domain arbitrarily precision routines which was posted
    to the net around 1984.  By now, there is almost no recognizable
    code left from that original source.

    Most of this source and binary has one of the following copyrights:

        Copyright (C) year  David I. Bell
        Copyright (C) year  David I. Bell and Landon Curt Noll
        Copyright (C) year  David I. Bell and Ernest Bowen
        Copyright (C) year  David I. Bell, Landon Curt Noll and Ernest Bowen
        Copyright (C) year  Landon Curt Noll
        Copyright (C) year  Ernest Bowen and Landon Curt Noll
        Copyright (C) year  Ernest Bowen
        Copyright (C) year  Petteri Kettunen and Landon Curt Noll
        Copyright (C) year  Christoph Zurnieden
        Copyright (C) year  Landon Curt Noll and Thomas Jones-Low
        Copyright (C) year  Klaus Alexander Seistrup and Landon Curt Noll

    A few files in calc are covered under "The Unlicense".  For more
    information on this license, see:

            https://unlicense.org


Copying / Calc GNU Lesser General Public License

    Calc is open software, and is covered under version 2.1 of the GNU
    Lesser General Public License.  You are welcome to change it and/or
    distribute copies of it under certain conditions.  The calc commands:

        help copying
        help copying-lgpl

    should display the contents of the COPYING and COPYING-LGPL files.
    Those files contain information about the calc's GNU Lesser General
    Public License, and in particular the conditions under which you
    are allowed to change it and/or distribute copies of it.

    You should have received a copy of the version 2.1 GNU
    Lesser General Public License.  If you do not have these
    files, write to:

        Free Software Foundation, Inc.
        51 Franklin Street
        Fifth Floor
        Boston, MA  02110-1301
        USA

See also:

        help copyright
        help copying
        help copying-lgpl

## Copyright (C) 1999,2023  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.
##
## Under source code control:   1991/07/23 05:47:24
## 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/

*************
* COPYING
*************

                calc - arbitrary precision calculator

This file is Copyrighted
------------------------

    This file is not covered under version 2.1 of the GNU LGPL.
    This file is covered under the following Copyright:

        Copyright (C) 1999-2023  Landon Curt Noll
        All rights reserved.

        Everyone is permitted to copy and distribute verbatim copies
        of this license document, but changing it is not allowed.

-=-

Calc is covered by the GNU Lesser General Public License
--------------------------------------------------------

    Calc is open software; you can redistribute it and/or modify it under
    the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation version 2.1 of the License.

    Calc is several binary link libraries, several modules, associated
    interface definition files and scripts used to control its compilation
    and installation.

    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 the GNU Lesser General Public License is distributed with
    calc under the filename:

            COPYING-LGPL

    You may display this file by the calc command:      help copying

    You may display the GNU Lesser General
    Public License by the calc command:                 help copying-lgpl

    You should have received a copy of the version 2.1 GNU Lesser General
    Public License with calc; if not, write to the following address:

            Free Software Foundation, Inc.
            51 Franklin Street
            Fifth Floor
            Boston, MA  02110-1301
            USA

Calc's relationship to the GNU Lesser General Public License
------------------------------------------------------------

    In section 0 of the GNU Lesser General Public License, one finds
    the following definition:

        The "Library", below, refers to any such software library or
        work which has been distributed under these terms.

    Calc is distributed under the terms of the GNU Lesser
    General Public License.

    In the same section 0, one also find the following:

        For a library, complete source code means all the source code
        for all modules it contains, plus any associated interface
        definition files, plus the scripts used to control compilation
        and installation of the library.

    There are at least two calc binary link libraries found in calc:

        libcalc.a       libcustcalc.a

    Clearly all files that go into the creation of those binary link
    libraries are covered under the License.

    The "scripts used to control compilation and installation of the
    of the library" include:

        * Makefiles
        * source files created by the Makefiles
        * source code used in the creation of intermediate source files

     All of those files are covered under the License.

     The "associated interface definition files" are those files that:

        * show how the calc binary link libraries are used
        * test the validity of the binary link libraries
        * document routines found in the binary link libraries
        * show how one can interactively use the binary link libraries

     Calc provides an extensive set of files that perform the above
     functions.

        * files under the sample sub-directory
        * files under the help sub-directory
        * files under the lib sub-directory
        * the main calc.c file

     The "complete source code" includes ALL files shipped with calc,
     except for the exception files explicitly listed in the "Calc
     copyrights and exception files" section below.

-=-

Calc copyrights and exception files
-----------------------------------

    With the exception of the files listed below, Calc is covered under
    the following GNU Lesser General Public License Copyrights:

        Copyright (C) year  David I. Bell
        Copyright (C) year  David I. Bell and Landon Curt Noll
        Copyright (C) year  David I. Bell and Ernest Bowen
        Copyright (C) year  David I. Bell, Landon Curt Noll and Ernest Bowen
        Copyright (C) year  Landon Curt Noll
        Copyright (C) year  Ernest Bowen and Landon Curt Noll
        Copyright (C) year  Ernest Bowen
        Copyright (C) year  Petteri Kettunen and Landon Curt Noll
        Copyright (C) year  Christoph Zurnieden
        Copyright (C) year  Landon Curt Noll and Thomas Jones-Low
        Copyright (C) year  Klaus Alexander Seistrup and Landon Curt Noll

    These files are not covered under one of the Copyrights listed above:

            sha1.c              sha1.h          COPYING
            COPYING-LGPL        cal/screen.cal

    The file COPYING-LGPL, which contains a copy of the version 2.1
    GNU Lesser General Public License, is itself Copyrighted by the
    Free Software Foundation, Inc.  Please note that the Free Software
    Foundation, Inc. does NOT have a copyright over calc, only the
    COPYING-LGPL that is supplied with calc.

    This file, COPYING, is distributed under the Copyright found at the
    top of this file.  It is important to note that you may distribute
    verbatim copies of this file but you may not modify this file.

    These files are covered under "The Unlicense":

            sha1.c
            sha1.h
            cal/dotest.cal
            cal/screen.cal

    "The Unlicense" is as follows:

        This is free and unencumbered software released into the public domain.

        Anyone is free to copy, modify, publish, use, compile, sell, or
        distribute this software, either in source code form or as a compiled
        binary, for any purpose, commercial or non-commercial, and by any
        means.

        In jurisdictions that recognize copyright laws, the author or authors
        of this software dedicate any and all copyright interest in the
        software to the public domain. We make this dedication for the benefit
        of the public at large and to the detriment of our heirs and
        successors. We intend this dedication to be an overt act of
        relinquishment in perpetuity of all present and future rights to this
        software under copyright law.

        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
        ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
        OTHER DEALINGS IN THE SOFTWARE.

        For more information, please refer to <http://unlicense.org/>

    In all cases one may use and distribute these exception files freely.
    And because one may freely distribute the LGPL covered files, the
    entire calc source may be freely used and distributed.

-=-

General Copyleft and License info
---------------------------------

    For general information on Copylefts, see:

        http://www.gnu.org/copyleft/

    For information on GNU Lesser General Public Licenses, see:

        http://www.gnu.org/copyleft/lesser.html
        http://www.gnu.org/copyleft/lesser.txt

-=-

Why calc did not use the GNU General Public License
---------------------------------------------------

    It has been suggested that one should consider using the GNU General
    Public License instead of the GNU Lesser General Public License:

        http://www.gnu.org/philosophy/why-not-lgpl.html

    As you can read in the above URL, there are times where a library
    cannot give free software any particular advantage.  One of those
    times is when there is significantly similar versions available
    that are not covered under a Copyleft such as the GNU General Public
    License.

    The reason why calc was placed under the GNU Lesser General Public
    License is because for many years (1984 thru 1999), calc was offered
    without any form of Copyleft.  At the time calc was placed under
    the GNU Lesser General Public License, a number of systems and
    distributions distributed calc without a Copyleft.

*************
* COPYING-LGPL
*************

                  GNU LESSER GENERAL PUBLIC LICENSE
                       Version 2.1, February 1999

 Copyright (C) 1991, 1999 Free Software Foundation, Inc.
 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

[This is the first released version of the Lesser GPL.  It also counts
 as the successor of the GNU Library Public License, version 2, hence
 the version number 2.1.]

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.

  This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it.  You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.

  When we speak of free software, we are referring to freedom of use,
not price.  Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.

  To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights.  These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.

  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.

  We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.

  To protect each distributor, we want to make it very clear that
there is no warranty for the free library.  Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.

  Finally, software patents pose a constant threat to the existence of
any free program.  We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder.  Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.

  Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License.  This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License.  We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.

  When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library.  The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom.  The Lesser General
Public License permits more lax criteria for linking other code with
the library.

  We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License.  It also provides other free software developers Less
of an advantage over competing non-free programs.  These disadvantages
are the reason we use the ordinary General Public License for many
libraries.  However, the Lesser license provides advantages in certain
special circumstances.

  For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard.  To achieve this, non-free programs must be
allowed to use the library.  A more frequent case is that a free
library does the same job as widely used non-free libraries.  In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.

  In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software.  For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.

  Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.

  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.

                  GNU LESSER GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".

  A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.

  The "Library", below, refers to any such software library or work
which has been distributed under these terms.  A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term "modification".)

  "Source code" for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.

  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.

  1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.

  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.

  2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) The modified work must itself be a software library.

    b) You must cause the files modified to carry prominent notices
    stating that you changed the files and the date of any change.

    c) You must cause the whole of the work to be licensed at no
    charge to all third parties under the terms of this License.

    d) If a facility in the modified Library refers to a function or a
    table of data to be supplied by an application program that uses
    the facility, other than as an argument passed when the facility
    is invoked, then you must make a good faith effort to ensure that,
    in the event an application does not supply such function or
    table, the facility still operates, and performs whatever part of
    its purpose remains meaningful.

    (For example, a function in a library to compute square roots has
    a purpose that is entirely well-defined independent of the
    application.  Therefore, Subsection 2d requires that any
    application-supplied function or table used by this function must
    be optional: if the application does not supply it, the square
    root function must still compute square roots.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.

In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.

  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.

  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.

  4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.

  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.

  5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library".  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.

  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library".  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.

  When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.

  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)

  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.

  6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.

  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:

    a) Accompany the work with the complete corresponding
    machine-readable source code for the Library including whatever
    changes were used in the work (which must be distributed under
    Sections 1 and 2 above); and, if the work is an executable linked
    with the Library, with the complete machine-readable "work that
    uses the Library", as object code and/or source code, so that the
    user can modify the Library and then relink to produce a modified
    executable containing the modified Library.  (It is understood
    that the user who changes the contents of definitions files in the
    Library will not necessarily be able to recompile the application
    to use the modified definitions.)

    b) Use a suitable shared library mechanism for linking with the
    Library.  A suitable mechanism is one that (1) uses at run time a
    copy of the library already present on the user's computer system,
    rather than copying library functions into the executable, and (2)
    will operate properly with a modified version of the library, if
    the user installs one, as long as the modified version is
    interface-compatible with the version that the work was made with.

    c) Accompany the work with a written offer, valid for at
    least three years, to give the same user the materials
    specified in Subsection 6a, above, for a charge no more
    than the cost of performing this distribution.

    d) If distribution of the work is made by offering access to copy
    from a designated place, offer equivalent access to copy the above
    specified materials from the same place.

    e) Verify that the user has already received a copy of these
    materials or that you have already sent this user a copy.

  For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.

  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.

  7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:

    a) Accompany the combined library with a copy of the same work
    based on the Library, uncombined with any other library
    facilities.  This must be distributed under the terms of the
    Sections above.

    b) Give prominent notice with the combined library of the fact
    that part of it is a work based on the Library, and explaining
    where to find the accompanying uncombined form of the same work.

  8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.

  9. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.

  10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.

  11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded.  In such case, this License incorporates the limitation as if
written in the body of this License.

  13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.

  14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.

                            NO WARRANTY

  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.

                     END OF TERMS AND CONDITIONS

           How to Apply These Terms to Your New Libraries

  If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change.  You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).

  To apply these terms, attach the following notices to the library.  It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.

    <one line to give the library's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This library 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.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
    USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the
  library `Frob' (a library for tweaking knobs) written by James Random Hacker.

  <signature of Ty Coon>, 1 April 1990
  Ty Coon, President of Vice

That's all there is to it!

*************
* questions
*************

If you have a general question about calc, consider opening
a new Github discussion under:

        https://github.com/lcn2/calc/discussions

Look over the existing discussions to see of your question fits
under one of those exiting discussions.

You may wish to add your question as a comment to an existing discussion.
Otherwise click on:

    ((New discussion))

and ask your question in that new discussion.

Please limit your questions to general questions about calc.  We
cannot go into great detail in our answers, nor can we do your
homework, nor can we do much more than answer general questions
about calc.

Please be patient as we cannot always respond to discussion messages quickly.

=-=

## Copyright (C) 2021,2023  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.
##
## Under source code control:   2021/02/10 00:15:05
## File existed as early as:    2021
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/

*************
* releases
*************

On calc versions and releases

Calc version numbers have 4 levels.  For example:

         ++=== top 2 levels: calc builtin functions compatibility
         ||
        vvvv

        2.14.0.8
         \\\\\\
        ^  \\\\----> top 3 levels: calc important code base change
        |
        +--- top version level: internal representation compatibility

The top version level (e.g., 2) refers to the internal representation
of values.  Any library or hardware linked/built for calc 2 will be able
to use values from other 2.x.y.z versions.

The top 2 levels (e.g., 2.14) refers to a specific compatible set of
builtin functions.  Calc interpreted code (such as calc resource files)
written for, say calc 2.14, will be able to use the same set of builtin
functions for any other 2.14.y.z version.  Any new builtin functions or
significant changes to existing builtin functions would be introduced in
a later release such as version 2.15.y.z.  While calc scripts written for
2.14.y.z will highly likely be able to run under version 2.15.y.z, any
new builtin functions added in calc 2.15 may collide with an identically
named used defined function.

The top 3 levels (e.g., 2.14.0) change to reflect an important change to
the code base such as a bug fix or performance improvement.  There was
neither a change to the internal representation format (a top level
version change), nor were there new calc builtins introduced in such
a top 3 level release.


The file, "version.h" defines the 4 version levels:

    MAJOR_VER           /* level 1: major library version */
    MINOR_VER           /* level 2: minor library version */
    MAJOR_PATCH         /* level 3: major software version level */
    MINOR_PATCH         /* level 4: minor software version level */


The program "ver_calc" will print information about the compiled
calc version as defined "version.h" when "ver_calc" was compiled:

    usage: ./ver_calc [-h] [-V]

        -h      print this message and exit non-zero
        -V      print 3-level version (def: print 4-level version)

Also "calc -v" will print the calc version as defined "version.h" when
"calc" was compiled.

The master branch:

    The public repository of calc source code is:

        http://github.com/lcn2/calc

    On that GitHub site you may find released version of calc,
    "production", "tested" and "alpha".  All commits on the master
    branch that are not associated with a release are "alpha".

    Any "alpha" commit is likely future code for a future
    "tested" or "production" version of calc.

alpha           ==> untagged GitHub commit

        Any untagged commit to the GitHub master branch should be
        considered as alpha code that may make calc unstable.

        While we try to avoid breaking the calc code with commits,
        there is a risk that picking up such a change could
        negatively impact the code.

        NOTE: The calc version found in "version.h", and printed
              by both "ver_calc [-V]" and "calc -v" for an untagged
              commit is the previous "tested" or "production" version
              of calc.  Any "alpha" changes that remain are code
              for some future version of calc.

              At the last stage of the release process, "version.h"
              will be updated as well as the top level version range
              listed in "CHANGES".

tested          ==> tagged GitHub pre-release commit

        A new version of calc has been released and has recently passed
        regression testing on at least to different platforms and chip
        architectures.

        The "tested" class was historically called "untested",
        however this term was misleading as such releases ARE tested.
        Since 2.14.0.13 we have used the term "tested".

        All tested releases are tagged with a new version number.
        Such releases have GitHub assets such as a source tarball,
        zip file, source rpm, development rpm and binary rpm.  See the
        orange "Pre-release" GitHub releases under:

            https://github.com/lcn2/calc/releases

         At the bottom of a given release is a "> Assets" that may
         be opened to reveal down-loadable files.

production      ==> tagged GitHub release commit

        A new version of calc has been released and has undergone
        extensive testing over time over a number of platforms.
        Sometimes a "tested" release that is found work well over
        a period of time will be re-released with a new version
        number as a "production" release.

        The latest production GitHub release is marked with green
        "Latest" label under:

            https://github.com/lcn2/calc/releases

        A release that has neither an orange "Pre-release" nor
        a green "Latest" label is a prior production class release.

        At the bottom of a given release is a "> Assets" that may
        be opened to reveal down-loadable files.

        Production class code where stability is critical should use a
        "production" release.

A historical note and apology:

    In the past, some version number changes were made that did not
    fully reflect the above version number or change class.  Moreover
    older terms such as "stable" and "unstable" were misleading and
    did not properly reflect the nature of the change.  Sorry!  The
    purpose of this document is to try and bring a better level of
    conformity to source code updates, tagged releases and version numbers.

## Copyright (C) 2021,2023  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.
##
## Under source code control:   2021/12/12 19:36:26
## File existed as early as:    2021
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/

*************
* help
*************

For more information while running calc, type  help  followed by one of the
following topics:

    topic               description
    -----               -----------
    intro               introduction to calc
    overview            overview of calc
    calc                calc man page, how to invoke the calc command

    assoc               using associations
    builtin             builtin functions
    command             top level commands
    config              configuration parameters
    custom              information about the custom builtin interface
    define              how to define functions
    environment         how environment variables affect calc
    errorcodes          calc generated error codes
    expression          expression sequences
    file                using files
    history             command history
    interrupt           how interrupts are handled
    list                using lists
    mat                 using matrices
    obj                 user defined data types
    operator            math, relational, logic and variable access operators
    resource            standard calc resource files
    script              using calc shell scripts
    statement           flow control and declaration statements
    types               builtin data types
    unexpected          unexpected syntax/usage surprises for C programmers
    variable            variables and variable declarations

    bindings            input & history character bindings
    custom_cal          information about custom calc resource files
    libcalc             using the arbitrary precision routines in a C program
    new_custom          information about how to add new custom functions
    cscript             info on the calc shell scripts supplied with calc

    archive             where to get the latest versions of calc
    bugs                known bugs and mis-features
    changes             recent changes to calc
    contrib             how to contribute scripts, code or custom functions
    todo                list of priority action items for calc
    wishlist            wish list of future enhancements of calc

    credit              who wrote calc and who helped
    copyright           calc copyright and the GNU LGPL
    copying             details on the Calc GNU Lesser General Public License
    copying-lgpl        calc GNU Lesser General Public License text
    questions           how to ask simple general question about calc
    release             on calc versions and releases

    help                this file
    full                all of the above (in the above order)

For example:

    help usage

will print the calc command usage information.  One can obtain calc help
without invoking any startup code by running calc as follows:

    calc -q help topic

where 'topic' is one of the topics listed above.

You can also ask for help on a particular builtin function name.  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 //
    help #

If the -m mode disallows opening files for reading or execution of programs,
then the help facility will be disabled.  See:

    help usage

for details of the -m mode.

The help command is able to display installed help files for custom builtin
functions.  However, if the custom name is the same as a standard help
file, the standard help file will be displayed instead.  The custom help
builtin should be used to directly access the custom help file.

For example, the custom help builtin has the same name as the standard
help file.  That is:

    help help

will print this file only.  However the custom help builtin will print
only the custom builtin help file:

    custom("help", "help");

will by-pass a standard help file and look for the custom version directly.

As a hack, the following:

     help custhelp/anything

as the same effect as:

    custom("help", "anything");

The man command is an alias for the help command.  For example:

    man sin

Any help file that the help command is able to display may be
displayed by the man command.  The man command may only display
calc help files.

## Copyright (C) 1999-2007,2017,2021  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.
##
## Under source code control:   1991/07/21 04:37:20
## 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/
