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
	    acos      1-2    arccosine of a within accuracy b
	    acosh     1-2    hyperbolic arccosine of a within accuracy b
	    append    2      append value to end of list
	    appr      1-2    approximate a with simpler fraction to within b
	    arg       1-2    argument (the angle) of complex number
	    asin      1-2    arcsine of a within accuracy b
	    asinh     1-2    hyperbolic arcsine of a within accuracy b
	    assoc     0      create new association array
	    atan      1-2    arctangent of a within accuracy b
	    atan2     2-3    angle to point (b,a) within accuracy c
	    atanh     1-2    hyperbolic arctangent of a within accuracy b
	    avg       1+     arithmetic mean of values
	    base      0-1    set default output base
	    bround    1-2    round value a to b number of binary places
	    btrunc    1-2    truncate a to b number of binary places
	    ceil      1      smallest integer greater than or equal to number
	    cfappr    1-2    approximate a within accuracy b using
				continued fractions
	    cfsim     1      simplify number using continued fractions
	    char      1      character corresponding to integer value
	    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
	    cos       1-2    cosine of value a within accuracy b
	    cosh      1-2    hyperbolic cosine of a within accuracy b
	    cp        2      cross product of two vectors
	    delete    2      delete element from list a at position b
	    den       1      denominator of fraction
	    det       1      determinant of matrix
	    digit     2      digit at specified decimal place of number
	    digits    1      number of digits in number
	    dp        2      dot product of two vectors
	    epsilon   0-1    set or read allowed error for real calculations
	    errno     1      system error message
	    eval      1      evaluate expression from string to value
	    exp       1-2    exponential of value a within accuracy b
	    factor    1-3    lowest prime factor < b of a, return c if error
	    fcnt      2      count of times one number divides another
	    fib       1      Fibonacci number F(n)
	    frem      2      number with all occurrences of factor removed
	    fact      1      factorial
	    fclose    1      close file
	    feof      1      whether EOF reached for file
	    ferror    1      whether error occurred for file
	    fflush    1      flush output to file
	    fgetc     1      read next char from file
	    fgetline  1      read next line from file, newline removed
	    fgets     1      read next line from file, newline is kept
	    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
	    fprintf   2+     print formatted output to opened file
	    fputc     2      write a character to a file
	    fputs     2      write a string to a file
	    fseek     2      seek to position b in file a
	    fsize     1      return the size of the file
	    ftell     1      return the file position
	    frac      1      fractional part of value
	    gcd       1+     greatest common divisor
	    gcdrem    2      a divided repeatedly by gcd with b
	    hash      1+     return non-negative hash value for one or
				more values
	    highbit   1      high bit number in base 2 representation
	    hmean     1+     harmonic mean of values
	    hypot     2-3    hypotenuse of right triangle within accuracy c
	    ilog      2      integral log of one number with another
	    ilog10    1      integral log of a number base 10
	    ilog2     1      integral log of a number base 2
	    im        1      imaginary part of complex number
	    insert    3      insert value 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
	    isassoc   1      whether a value is an association
	    iseven    1      whether a value is an even integer
	    isfile    1      whether a value is a file
	    isint     1      whether a value is an integer
	    islist    1      whether a value is a list
	    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
	    isodd     1      whether a value is an odd integer
	    isprime   1-2    whether a is a small prime, return b if error
	    isqrt     1      integer part of square root
	    isreal    1      whether a value is a real number
	    isrel     2      whether two numbers are relatively prime
	    isset     2      whether bit b of abs(a) (in base 2) is set
	    isstr     1      whether a value is a string
	    issimple  1      whether value is a simple type
	    issq      1      whether or not number is a square
	    istype    2      whether the type of a is same as the type of b
	    jacobi    2      -1 => a is not quadratic residue mod b
			      1 => b is composite, or a is quad residue of b
	    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
	    list      0+     create list of specified values
	    ln        1-2    natural logarithm of value a within accuracy b
	    lowbit    1      low bit number in base 2 representation
	    ltol      1-2    leg-to-leg of unit right triangle (sqrt(1 - a^2))
	    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
	    mattrans  1      transpose of matrix
	    max       1+     maximum value
	    meq       3      whether a and b are equal modulo c
	    min       1+     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
	    near      2-3    sign of (abs(a-b) - c)
	    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)!
	    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
	    pfact     1      product of primes up till number
	    pi        0-1    value of pi accurate to within epsilon
	    pix       1-2    number of primes <= a < 2^32, return b if error
	    places    1      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      2+     (a1,a2,...,an,x) = a1*x^n+a2*x^(n-1)+...+an
	    pop       1      pop value from front of list
	    power     2-3    value a raised to the power b within accuracy c
	    ptest     1-3    probabilistic primality test
	    printf    1+     print formatted output to stdout
	    prompt    1      prompt for input line using value a
	    push      2      push value onto front of list
	    quomod    4      set c and d to quotient and remainder of a
				divided by b
	    rand      0-2    additive 55 random number [0,2^64), [0,a), or [a,b)
	    randbit   1      additive 55 random number [0,2^a)
	    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
	    root      2-3    value a taken to the b'th root within accuracy c
	    round     1-2    round value a to b number of decimal places
	    rsearch   2-3    reverse search matrix or list for value b
				starting at index c
	    runtime   0      user mode cpu time in seconds
	    scale     2      scale value up or down by a power of two
	    search    2-3    search matrix or list for value b starting
				at index c
	    sgn       1      sign of value (-1, 0, 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
	    sqrt      1-2    square root of value a within accuracy b
	    srand     0-1    seed the rand() function
	    ssq       1+     sum of squares of values
	    str       1      simple value converted to string
	    strcat    1+     concatenate strings together
	    strlen    1      length of string
	    strprintf 1+     return formatted output as a string
	    substr    3      substring of a from position b for c chars
	    swap      2      swap values of variables a and b (can be dangerous)
	    tan       1-2    tangent of a within accuracy b
	    tanh      1-2    hyperbolic tangent of a within accuracy b
	    trunc     1-2    truncate a to b number of decimal places
	    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 isset 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
	isset(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 divisable 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
	printer.  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".
