config

Calc Software Package for Number Calc

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 transcendentals.
	    "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 '~'
	    "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
	    "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 .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("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 or exponential 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"

    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)

    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)

    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.