
        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/
