.\" -*-nroff-*- .\" ==================================================================== .\" @Troff-man-file{ .\" author = "Nelson H. F. Beebe", .\" version = "7.0.0.beta", .\" date = "27 December 2001", .\" time = "12:45:27 MST", .\" filename = "hoc.1", .\" address = "Center for Scientific Computing .\" University of Utah .\" Department of Mathematics, 322 INSCC .\" 155 S 1400 E RM 233 .\" Salt Lake City, UT 84112-0090 .\" USA", .\" telephone = "+1 801 581 5254", .\" FAX = "+1 801 585 1640, +1 801 581 4148", .\" URL = "http://www.math.utah.edu/~beebe", .\" checksum = "48588 3825 14466 94804", .\" email = "beebe@math.utah.edu, beebe@acm.org, .\" beebe@computer.org, beebe@ieee.org .\" (Internet)", .\" codetable = "ISO/ASCII", .\" keywords = "calculator; floating-point arithmetic; hoc .\" programming language; IEEE 754; software .\" internationalization", .\" supported = "yes", .\" docstring = "This file is the UNIX nroff/troff manual page .\" documentation for hoc, the extended .\" high-order calculator. .\" .\" The checksum field above contains a CRC-16 .\" checksum as the first value, followed by the .\" equivalent of the standard UNIX wc (word .\" count) utility output of lines, words, and .\" characters. This is produced by Robert .\" Solovay's checksum utility.", .\" } .\" ==================================================================== .TH HOC 1 "@PACKAGE_DATE@" "@PACKAGE_VERSION@" .\" .CT 1 numbers .\" ---------------------------------------------- .SH NAME hoc \(em (high-order calculator) [interactive floating-point language] .\" ---------------------------------------------- .SH SYNOPSIS .B hoc [ .B \-author ] [ .B \-copyright ] [ .B \-? ] [ .B \-help ] .if n .ti +\w'\fBhoc\fP 'u [ .B \-no-banner ] [ .B \-no-help-file ] [ .B \-no-load ] .if n .ti +\w'\fBhoc\fP 'u .if t .ti +\w'\fBhoc\fP 'u [ .B \-no-logfile ] [ .B \-no-readline ] [ .B \-no-save ] .if n .ti +\w'\fBhoc\fP 'u [ .B \-no-site-file ] [ .B \-no-translation-file ] .if n .ti +\w'\fBhoc\fP 'u [ .B \-no-user-file ] .if t .ti +\w'\fBhoc\fP 'u [ .B \-quick ] [ .B \-silent ] [ .B \-version ] .if n .ti +\w'\fBhoc\fP 'u [ .I "file .\|.\|." ] .\" ---------------------------------------------- .SH OPTIONS .B hoc options can be prefixed with either one or two hyphens, and can be abbreviated to any unique prefix. Thus, .BR \-a , .BR \-author , and .B \-\-auth are equivalent. .PP To avoid confusion with options, if a filename begins with a hyphen, it must be disguised by a leading absolute or relative directory path, e.g., .I /tmp/-foo.hoc or .IR ./-foo.hoc . .\"----------------------------------------------- .TP \w'\-no-translation-file'u+3n .B \-author Display an author credit, and software distribution information, on the standard error unit, .IR stderr , and then terminate with a success return code. Sometimes an executable program is separated from its documentation and source code; this option provides a way to recover from that. .\"----------------------------------------------- .TP .B \-copyright Display copyright information on the standard error unit, .IR stderr , and then terminate with a success return code. .\"----------------------------------------------- .TP .BR \-help " or " \-? Display a help message on .IR stderr , giving a brief usage description, and then terminate with a success return code. .\"----------------------------------------------- .TP .B \-no-banner Suppress any welcome banners normally printed by dynamically-loaded library code. .IP This option can also be set via the .B hoc system variable .BR _\|_BANNER_\|_ , but it must be set in an initialization file before code in that file to print the welcome banner is reached. .\"----------------------------------------------- .TP .B \-no-help-file Suppress loading of system-wide .B hoc help files at startup. .\"----------------------------------------------- .TP .B \-no-load Disable the .B load(\|) function. It will continue to be recognized, but when invoked, will simply print a warning that it has been disabled. .IP This option is a security feature: it takes effect only after all initialization files have been processed. .\"----------------------------------------------- .TP .B \-no-logfile Disable the .BR logfile(\|) , .BR logon(\|) , and .B logoff(\|) functions. They will continue to be recognized, but when invoked, will simply print a warning that they have been disabled. .IP This option is a security feature: it takes effect only after all initialization files have been processed. .\"----------------------------------------------- .TP .B \-no-readline Suppress use of the GNU .I readline library: command completion, editing and recall are then not available. .IP On some systems, it may be necessary to use this option when .B hoc is used in international mode (see the .B INTERNATIONALIZATION section below) in order to get accented letters displayed properly. .\"----------------------------------------------- .TP .B \-no-save Disable the .B save(\|) function. It will continue to be recognized, but when invoked, will simply print a warning that it has been disabled. .IP This option is a security feature: it takes effect only after all initialization files have been processed. .\"----------------------------------------------- .TP .B \-no-site-file Suppress loading of the system-wide non-help startup files. .\"----------------------------------------------- .TP .B \-no-translation-file Suppress loading of the system-wide message translation files. .\"----------------------------------------------- .TP .B \-no-user-file Suppress loading of the user-specific startup file. .\"----------------------------------------------- .TP .B \-quick Suppress loading of all startup files: this option is equivalent to .B \-no-help-file .B \-no-site-file .B \-no-translation-file .BR \-no-user-file . .\"----------------------------------------------- .TP .B \-silent Suppress printing of prompts for interactive input. .B hoc never prompts when it is reading noninteractive files. .IP The .B hoc system variable .B _\|_VERBOSE_\|_ can also be set to zero at run time to turn off prompts; setting it to nonzero turns them back on. .IP The .B hoc system variable .B _\|_PROMPT_\|_ contains the prompt string: it can be redefined at any time. .\"----------------------------------------------- .TP .B \-version Display the program version number and release date on .IR stderr , and then terminate with a success return code. .\" ---------------------------------------------- .SH DESCRIPTION .B hoc interprets a simple language for floating-point arithmetic, at about the level of Basic, with C-like syntax and functions. However, unlike Basic, .B hoc has particularly rich support for floating-point arithmetic, and its facilities are certainly better than that standardly provided by most programming languages, such as C, C++, and Fortran. .PP To get a flavor of what typical .B hoc code looks like, visit the \&\fC*.hoc\fP and \&\fC*.rc\fP files in the .B hoc installation directory tree: see the .B "INITIALIZATION FILES" section below for their location. .PP The named .IR file s are read and interpreted in order. If no .I file is given or if .I file is .IR \- , .B hoc interprets the standard input. .PP .B hoc input consists of .I expressions and .IR statements . Expressions are evaluated and their results printed. Statements, typically assignments and function or procedure definitions, produce no output unless they explicitly call .BR print . .\" .............................................. .SS "Word completion" When .B hoc has been built with the GNU .I readline library, word completion can be used to save typing effort. It is normally requested by an ESCape character following a prefix of a word in .BR hoc 's symbol table: .B hoc will respond with an audible beep, and a list of words that match that prefix, or if only one word matches, it will silently complete the word: .RS .nf \&\fC\fBhoc>\fP c cbrt ceil copysign cos cosd cosh \fBhoc>\fP co copysign cos cosd cosh \fBhoc>\fP cop \fBhoc>\fP copysign\fP .fi .RE .\" groff bug: bold mode continues into next line, .\" so explicitly reset the font: \&\fRThe character used to request completion can be changed: see the\fP .B "INITIALIZATION FILES" section below. .\" .............................................. .SS "Command history and editing" When .B hoc has been built with the GNU .I readline library, convenient command history and editing support is available, much like it is in the UNIX .BR bash (1), .BR ksh (1) and .BR tcsh (1) shells, and in a few GNU programs, like the .BR bc (1) and .BR genius (1) calculators. The default history and editing mode is .BR emacs (1)-style; you can also get .BR vi (1)-style by suitable customizations: see the .B "INITIALIZATION FILES" section below. .PP In the default mode, .I C-p (hold the Control key down while typing p) moves up in the history list, .I C-n moves down, .I C-b moves backward in the current line, .I C-f moves forward, .I C-d deletes forward, .I DELete deletes backward, .I C-a moves to the beginning of the line, .I C-e moves to the end of the line, .I C-l repaints the screen, reprinting the current line at the top, and .I RETurn resubmits the line for execution. .PP For more details, consult the .I "GNU Readline Library" manual, available online in the .I info system. In .BR emacs (1); type .I "C-h i mreadline" to get there. .\" .............................................. .SS Numbers All numbers in .B hoc are stored as double-precision floating-point values. .PP On systems with IEEE 754 arithmetic, such numbers are capable of representing integers of up to 53 bits exactly, excluding the sign bit. This is an integer range of \-(2^53) .\|.\|. 2^53, or \-9,007,199,254,740,992 \&.\|.\|. 9,007,199,254,740,992. .PP Numbers may be signed, and may optionally contain a decimal point, and a power-of-ten exponent, which consists of the letter \fBe\fP (or \fBE\fP) followed by an optionally-signed integer. No other exponent letters are recognized. .PP A hexadecimal floating-point number format, introduced in the latest ISO C Standard, .IR "ISO/IEC 9899:1999 (E) Programming languages \(em C" , usually known by its short name, .IR C99 , is also supported, and implemented by portable private code in .BR hoc . This format consists of an optional sign, then .I 0x or .IR 0X , followed by one or more hexadecimal digits .RI ( "0\(mi9 A\(miF a\(mif" ) containing at most one hexadecimal point, optionally followed by a binary (power-of-two) exponent consisting of .I p or .I P followed by an optionally-signed decimal integer. Thus, .IR \-0x1.00000p8 , .IR \-0x100 , .IR \-0x100000p-12 , .IR \-0x10p+4 , .IR \-0x1p+8 , .IR \-0x1p00008 , and .I \-0x1p8 all represent the decimal number .IR \-256 . .PP The hexadecimal format, while awkward for humans, has the advantage of guaranteeing exact input/output conversions on all platforms, and .B hoc consequently uses this format in files created by the .B save(\|) command. .\" .............................................. .SS Strings String constants are delimited by quotation marks (\fC".\|.\|."\fP), and may not span multiple lines, unless the embedded line breaks are each prefixed with a backslash, which is removed, leaving the newline in the string. .PP All characters in 1 .\|.\|. 255 are representable in strings; as in C and C++, character 0 (ASCII NUL) is reserved as a string terminator. .PP In string constants, nonprintable characters may be represented by the usual escape sequences defined in Standard C and Standard C++, plus one extension (\fB\eE\fP): .RS .TP \w'\fB\eo\ \eoo\ \eooo\fP'u+2n .B \e\e backslash: ASCII decimal 92. .TP .B \e" quotation mark: ASCII decimal 34. .TP .B \ea alert or bell (ASCII BEL: decimal 7). .TP .B \eb backspace (ASCII BS: decimal 8). .TP .B \eE escape (ASCII ESC: decimal 27). .TP .B \ef formfeed (ASCII FF or NP: decimal 12). .TP .B \en newline (ASCII LF or NL: decimal 10). .TP .B \er carriage return (ASCII CR: decimal 13). .TP .B \et horizontal tab (ASCII HT: decimal 9). .TP .B \ev vertical tab (ASCII VT: decimal 11). .TP .B "\eo \eoo \eooo" octal character number (\fBo\fP = \fI0\(mi7\fP) in one to three digits. .TP .B \exh.\|.\|. hexadecimal character (\fBh\fP = \&\fI0\(mi9A\(miF\fP or \fI0\(mi9a\(mif\fP) in one or more digits. .RE Backslash followed by any other character than those listed is simply discarded: \fB\eW\fP reduces to \fBW\fP. .\" .............................................. .SS Variables Variable names consist of an initial letter or underscore, followed by any number of letters, underscores, or digits. Lettercase is .IR significant . Letters are considered to be .IR A\(miZ , .IR a\(miz , and any characters in the range 160 \&.\|.\|. 255 of an 8-bit character set. Use of characters in the latter range is normally not recommended, because they are often difficult, or impossible, to generate on some computer keyboards. Nevertheless, it does permit non-English words to be spelled correctly; see the .B INTERNATIONALIZATION section below. .PP Underscore .RI "(\|" _ "\|)" by itself is a reserved variable containing the value of the last .I numeric expression evaluated. Double underscore .RI "(\|" _\|_ "\|)" is a reserved variable containing the value of the last .I string expression evaluated. They cannot be assigned to by user code. .\" .............................................. .SS "Predefined numeric constants and variables" Certain immutable named constants are already initialized: .RS .\"----------------------------------------------- .TP \w'\fBINF\fP\ or\ \fBInf\fP\ or\ \fBInfinity\fP'u+3n .B CATALAN .na Catalan's constant: sum((\-1)^i/(2*i+1)^2, i = 0..infinity) = .if n .br approximately 0.915965594177219015054603514932.\|.\|. .ad .\"----------------------------------------------- .TP .B DEG 180/PI, degrees per radian .\"----------------------------------------------- .TP .B E base of natural logarithms .\"----------------------------------------------- .TP .B GAMMA Euler's constant: .br .na limit(sum(1/i,i=1.\|.\|.n) \(mi\& ln(n), n \(-> infinity) = approximately 0.577215664901532860606512090082.\|.\|. .ad .\"----------------------------------------------- .TP .BR INF " or " Inf " or " Infinity IEEE-754 floating-point infinity .\"----------------------------------------------- .TP .B MAXNORMAL Largest finite normalized floating-point number. .\"----------------------------------------------- .TP .B MINNORMAL Smallest (in absolute value) nonzero normalized floating-point number. .\"----------------------------------------------- .TP .B MINSUBNORMAL Smallest (in absolute value) subnormal floating-point number. If your computer system does not support subnormal numbers, this is identical to .BR MINNORMAL . .\"----------------------------------------------- .TP .BR NAN " or " NaN IEEE-754 floating-point not-a-number .\"----------------------------------------------- .TP .B PHI .na golden ratio: .if n .br (1 + sqrt(5))/2 = .if n .br approximately 1.61803398874989484820458683436.\|.\|. .ad .\"----------------------------------------------- .TP .B PI .na ratio of the circumference of a circle to its diameter, approximately 3.14159265358979323846264338327.\|.\|. .ad .\"----------------------------------------------- .TP .B PREC maximum number of significant digits in output, initially 17 on most systems (the precise value is computed dynamically, from Matula's 1968 result: .IR "ceil(N/log_b(10) + 1)" , for a host floating-point system with .I N .RI base- b digits). .B "PREC = 0" gives shortest `exact' values. .\"----------------------------------------------- .TP .BR QNAN " or " QNaN IEEE-754 floating-point quiet not-a-number .\"----------------------------------------------- .TP .BR SNAN " or " SNaN IEEE-754 floating-point signaling not-a-number .\"----------------------------------------------- .RE .PP More information on the floating-point constants is available in the .B "FLOATING-POINT ARITHMETIC" section below. .\" .............................................. .SS "Predefined system constants and variables" .B hoc also provides a number of system constants and variables, adopting the C/C++ convention that names beginning with two underscores are reserved for the implementation: .RS .\"----------------------------------------------- .TP \w'_\|_PACKAGE_BUGREPORT_\|_'u+3n .B _\|_BANNER_\|_ [reassignable number] Nonzero (true) if printing of welcome banners is permitted. It can be changed by the .B \-no-banner option. .\"----------------------------------------------- .TP .B _\|_DATE_\|_ [constant string] Date of the start of job execution, in the form \&\fC"Dec 16 2001"\fP. The day number has a leading space if only one digit is needed, so that the string always has constant width. .\"----------------------------------------------- .TP .B _\|_FILE_\|_ [constant string] Name of the current input file. This is \&\fC"/dev/stdin"\fP when .B hoc is reading from the standard input. .\"----------------------------------------------- .TP .BI _\|_FILE_\|_[ n ] [constant string] Name of the .IR n -th input file in the current job. This provides a history of exactly what files have been read. Because .B hoc does not yet support arrays, the only way to display these is with the .B who(\|) function. .\"----------------------------------------------- .TP .B _\|_IEEE_754_\|_ [constant number] Nonzero (true) if the host system supports IEEE 754 arithmetic. .\"----------------------------------------------- .TP .B _\|_LINENO_\|_ [constant number] Number of the current input line in the file named by .BR _\|_FILE_\|_ . .\"----------------------------------------------- .TP .B _\|_PACKAGE_BUGREPORT_\|_ [constant string] Where to report bugs. .\"----------------------------------------------- .TP .B _\|_PACKAGE_DATE_\|_ [constant string] Date of last modification of the software. .\" TO DO: _\|_DATE_\|_ is "Dec 16 2001", while .\" _\|_PACKAGE_DATE_\|_ is "15-Dec-2001". Perhaps .\" they should be made consistent? .\"----------------------------------------------- .TP .B _\|_PACKAGE_NAME_\|_ [constant string] Program name. .\"----------------------------------------------- .TP .B _\|_PACKAGE_STRING_\|_ [constant string] Program name and version number. .\"----------------------------------------------- .TP .B _\|_PACKAGE_VERSION_\|_ [constant string] Program version number. .\"----------------------------------------------- .TP .B _\|_PROMPT_\|_ [reassignable string] Current prompt string. Prompting is controlled by the setting of .B _\|_VERBOSE_\|_ (see below). .IP For example, .RS \&\fC _\|_PROMPT_\|_ = "\en\eE[7mInput:\eE[0m "\fP .RE .IP will produce a blank line followed by a prompt in inverse video in terminal emulators, such as .BR xterm (1) and DEC VT100, that follow the ANSI X3.64-1979 or ISO 6429-1983 terminal standards. .IP If .B _\|_PROMPT_\|_ contains the two-character format string %d, that string will be replaced by the prompt count: for example, this silly setting .RS \&\fC _\|_PROMPT_\|_="\eE[4;5;34;43m[%d]\eE[0m:\ "\fP .RE .IP will display the count digits in blue, and underlined, on a yellow background, in an .BR xterm (1) window that supports text color attributes. [Run \&\fCdircolors -p\fP for more information on color settings.] .\"----------------------------------------------- .TP .B _\|_READLINE_\|_ [constant number] Nonzero (true) if the GNU .I readline library is in use. .\"----------------------------------------------- .TP .B _\|_TIME_\|_ [constant string] Local time-of-day (24-hour clock) of the start of job execution, in the usual hours, minutes, seconds form \&\fC"14:57:23"\fP. .\"----------------------------------------------- .TP .B _\|_VERBOSE_\|_ [reassignable number] Nonzero (true) if .B hoc should prompt for input from interactive files. The actual prompt string is controlled by the .B _\|_PROMPT_\|_ variable. .IP [NB: A bug in the GNU .I readline library (version 4.2a) makes this variable ineffective; it works correctly with the .B \-no-readline option. The bug has been reported to the .I readline maintainers.] .\"----------------------------------------------- .RE .\" .............................................. .SS "Numeric expressions" Numeric expressions are formed with these C-like operators, listed by decreasing precedence. .RS .\"----------------------------------------------- .TP \w'\fB"=\ \ +=\ \ -=\ \ *=\ \ /=\ \ %=\ \ :="\fP'u+3n .B ^ Exponentiation. .\"----------------------------------------------- .TP .B "! - ++ --" Logical negation, arithmetic negation, increment-by-one, decrement-by-one. As in C and C++, the latter two may be applied .I before a variable (acting first before taking the value), or .I after (taking the current value first, then acting). .\"----------------------------------------------- .TP .B "* / %" Multiply, divide, modulus. .\"----------------------------------------------- .TP .B "+ -" Add, subtract. .\"----------------------------------------------- .TP .B "> >= < <= == !=" Greater than, greater than or equal to, less than, less than or equal to, equal to, not equal to. .\"----------------------------------------------- .TP .B && Logical and. Both operands are .I always evaluated, unlike in C and C++, where the second is evaluated only if the first is nonzero (true). .\"----------------------------------------------- .TP .B || Logical or. Both operands are .I always evaluated, unlike in C and C++, where the second is evaluated only if the first is zero (false). .\"----------------------------------------------- .TP .B "= += -= *= /= %= :=" Assignment, assign the left-hand side the (sum, difference, product, dividend, or modulus) of its current value and the right-hand side, permanent assignment. The operator .B := is a .I one-time-only assignment operator, used for defining permanent constants that cannot be redefined in the same .B hoc session. .IP As in C and C++, assignment is a right-associative expression whose value is the left-hand side. This means that \&\fCx = y = z = 3\fP is interpreted as \&\fCx = (y = (z = 3))\fP. That is, \&\fC3\fP is assigned to \&\fCz\fP, then that result is assigned to \&\fCy\fP, and finally, that result is assigned to \&\fCx\fP, so all three variables are assigned the value \&\fC3\fP. Similarly, \&\fCsqrt(x = 4)\fP assigns the value \&\fC4\fP to \fCx\fP before computing and returning its square root. .\"----------------------------------------------- .RE .PP Expression lists in .BR print -like statements, and in argument lists, are evaluated in strict .I left-to-right order. Thus, the output of expressions with side effects, such as .RS .nf \&\fCn = 3 print ++n, n++\fP .fi .RE is predictable: that example prints .RS \&\fC4 4\fP .RE .\" .............................................. .SS "String expressions" String expressions support only the relational operators (\&\fB>\ \ >=\ \ <\ \ <=\ \ ==\ \ !=\fP) and the simple assignment operators (\&\fB=\ \ :=\fP), plus concatenation, which is indicated by two successive string expressions, without any specific operator, following the practice in C, C++, and .BR awk (1). These two assignments are equivalent: .RS .nf \&\fCs = "hello" ", " "wor" "ld" s = "hello, world"\fP .fi .RE Numbers in string expressions are converted to strings according to the current precision variable, \fBPREC\fP. .RS .nf \&\fCk = 123 PREC = 4 s = "abc" k "def" PI println s abc123def3.142\fP .fi .RE Several string functions listed below augment string expressions. .\" .............................................. .SS "Built-in functions and procedures" Longer documentation of the built-in functions and procedures is relegated to the later section, .BR "DESCRIPTIONS OF BUILT-IN FUNCTIONS AND PROCEDURES" . .PP These numeric built-in functions take zero arguments: .BR rand , .BR second , and .BR systime . .PP These numeric built-in functions take one numeric argument: .BR abs , .BR acos , .BR acosh , .BR asin , .BR asinh , .BR atan , .BR atanh , .BR cbrt , .BR ceil , .BR cos , .BR cosd , .BR cosh , .BR erf , .BR erfc , .BR exp , .BR expm1 , .BR exponent , .BR factorial , .BR floor , .BR gamma , .BR ilogb , .BR int , .BR isfinite , .BR isinf , .BR isnan , .BR isnormal , .BR isqnan , .BR issnan , .BR issubnormal , .BR J0 , .BR J1 , .BR lgamma , .BR ln , .BR log , .BR log10 , .BR log1p , .BR log2 , .BR macheps , .BR nint , .BR number , .BR randl , .BR rint , .BR rsqrt , .BR setrand , .BR significand , .BR sin , .BR sind , .BR sinh , .BR sqrt , .BR tan , .BR tand , .BR tanh , .BR trunc , .BR Y0 , and .BR Y1 . .PP These numeric built-in functions take two numeric arguments: .BR copysign , .BR errbits , .BR fmod , .BR gcd , .BR hypot , .BR Jn , .BR lcm , .BR ldexp , .BR logb , .BR max , .BR min , .BR randint , .BR nearest , .BR nextafter , .BR remainder , .BR scalb , and .BR Yn . .PP These string built-in functions take zero arguments: .BR logoff , .BR logon , and .BR now . .PP These string built-in functions take one argument: .BR eval , .BR getenv , .BR length , .BR hexfp , .BR hexint , .BR load , .BR logfile , .BR printenv , .BR string , .BR tolower , .BR toupper , and .BR who . .PP These string built-in functions take two arguments: .BR index , .BR putenv , .BR save , and .BR strftime . .PP This string built-in function takes three arguments: .BR substr . .PP These startup file procedures take no arguments: .BR author , .BR help , .BR help_xxx , and .BR news . .PP The help system (described later) documents each of these functions, and any additional ones provided by startup files. Most have the same names as they do in C, C++, and Fortran, so many will already be familiar to users who have learned any of those programming languages. .PP Built-in functions and procedures are .IR immutable : they cannot be redefined by the user in .B hoc code. User-defined variables, functions, and procedures can be redefined at any time to objects of the same type. Variables can be redefined to be functions or procedures. However, the reverse does not hold: once a name has been used as a function or procedure, it can only be redefined to be a new function or procedure. .PP The procedure .B abort(message) prints .BR message , immediately terminates evaluation, and returns to the top-level interpreter, discarding and clearing the function/procedure call stack. It is equivalent to a similar internal function that .B hoc uses to recover from catastrophic errors. Use it sparingly! .PP The function .B read(x) reads a value into the variable .BR x . The value must be either a number, or a quoted string, or an existing variable or named constant. The return value is 1 on success, or 0 on end-of-file; the function aborts for any other error condition. .PP The statement .B print prints a list of expressions that may include string constants such as .BR \fC\&\&\&"hello\en"\fP . It does .I not print a final newline: the last expression must end with one if a newline is required. .PP The statement .B println works like .BR print , but always supplies a following newline. .PP .\" TO DO: Update this paragraph! There is an incompletely implemented .B printf statement: it will not be further documented until it is fully working. .PP The function .B who(prefix) produces a lengthy report of all of the named constants and variables with their current values, plus the names of all built-in functions and procedures, and all user-defined functions and procedures. Only those names whose initial letters match the argument string, .BR prefix , are included. To print all symbols, use an empty prefix: .BR who("") . The return value is always an empty string. .PP Symbols with three or more leading underscores are for internal use by .BR hoc , and are thus considered .IR hidden . They can only be shown by a suitable .B prefix argument to .BR who(\|) . Hidden symbols are used for locale translations of embedded strings. See the .B INTERNATIONALIZATION section below for further details. .\" .............................................. .SS Statements Control flow statements are .BR if \(mi else , .BR while , and .BR for , with braces for grouping. Newline or semicolon ends a statement. Backslash-newline is equivalent to a space. .PP Functions and procedures are introduced by the words .B func and .BR proc ; .B return is used to return with a value from a function. Within a function or procedure, arguments are referred to as .BR $1 , .BR $2 , etc.; all other variables are global. .\" ---------------------------------------------- .SH "FLOATING-POINT ARITHMETIC" All arithmetic in .B hoc is done in double-precision floating point (C/C++ type .BR double ) . .PP On most modern systems, this arithmetic conforms closely (or loosely) to the 1985 .IR "IEEE 754 Standard for Binary Floating-Point Arithmetic" . This arithmetic system has numerous advantages over older designs, and has helped enormously to improve the environment for, and portability and reliability of, numerical software. .\" .............................................. .SS "How floating-point numbers are represented" In IEEE 754 arithmetic, double-precision numbers are represented as 64-bit values, consisting of a sign bit, an 11-bit biased exponent, and a 53-bit significand. That is a total of 65 bits: the first significand bit is called a .I hidden bit, and is not actually stored. The binary point lies between the hidden bit and the stored fraction, so that for normal numbers, the significand is at least one, but less than two. .PP Biased, rather than explicitly signed, exponents are conventional in floating-point architectures. For IEEE 754 64-bit arithmetic, the exponent bias is 1023; that is, the true exponent is 1023 less than the stored biased value. .PP The smallest biased exponent (0), and the largest biased exponent (2^11 - 1 = 2047), are given special interpretation, described below for subnormals, and Infinity and NaN, respectively. .\" .............................................. .SS "Large normal numbers" With the IEEE 754 format, the number range is approximately \-1.80e+308 .\|. +1.80e+308, with a precision of about 15 decimal figures. The exact value of the largest floating-point number is .BR "(1 \(mi 2^(\-53)) * 2^1024" . .\" .............................................. .SS "Small normal numbers" The smallest .I normalized number that can be represented is about 2.23e-308, or more precisely, .BR "2^(\-1022)" , and its reciprocal is also representable, being almost exactly a quarter of the largest representable number. .\" .............................................. .SS "Smaller subnormal numbers" The IEEE 754 Standard defines a numerically useful feature called .I "gradual underflow" that, when the biased exponent reaches its smallest value (0), relaxes the normalization requirement and drops the hidden bit, permitting small numbers to decrease further down to about 4.94e-324, or more precisely, .BR "2^(\-1074)" , but with loss of precision. Such numbers are called .I subnormal (formerly, .IR denormalized ). Not all systems support such numbers: the .B hoc function .B issubnormal(x) can be used to test whether .B x is subnormal. The reciprocal of the largest floating-point number is nonzero only if subnormal numbers are supported. Thus, you could define this .B hoc function to find out whether your system has subnormals; it returns 1 (true) if that is the case: .RS .nf \&\fCfunc hassubnormals(\|) \e return (issubnormal(1/(((1 - 2^(-53)) * 2^1023) * 2)))\fP .fi .RE With a predefined constant, this can also be written as .RS .nf \&\fCfunc hassubnormals(\|) return (issubnormal(1/MAXNORMAL))\fP .fi .RE .\" .............................................. .SS Underflow Numbers below the smallest normalized, or when supported, the smallest subnormal, values quietly .I underflow to zero. .\" .............................................. .SS "Machine epsilon" Another significant quantity in .I any floating-point system is known as the .IR "machine epsilon" . This is the smallest positive number that can be added to one, and produce a sum still different from one. .B hoc provides a generalization of this, with .B x replacing .B one in the last sentence: .BR "macheps(x)" . .PP In IEEE 754 arithmetic, .B macheps(1) is about 2.22e-16, or more precisely, .BR 2^(\-\&52) . The negative of its base-10 logarithm is the number of decimal digits that can be represented. An error of .B macheps(x) is called an .I ULP .RI ( U "nit in the " L "ast " P lace). If .B y is an approximation to .BR x , then with the definition .RS .nf \&\fCfunc errbits(\|) \e { if ($1 == $2) \e return (0) \e else \e return (ceil(log2(abs(($1 - $2)/max($1,$2))/macheps($1)))) }\fP .fi .RE .B errbits(x,y) is the number of bits that are in error in .BR y : that is, the base-2 logarithm of the relative error in ULPs, rounded up to the nearest integer. Incidentally, this function behaves as expected if either of its arguments are NaN (described below), or Infinity of opposite signs, even though there are no tests for those values: the result is a NaN. .PP One might reasonably argue for .B errbits(x,y) that the case of two Infinity arguments of like sign should also return a NaN. The current implementation does not include such a test, but doing so would require just one additional statement: \fCif (isinf($1) && isinf($2)) return (NAN)\fP. .PP .B macheps(0) is the smallest representable floating-point number, either normalized, or subnormal if supported. Thus, the test function above can be written more simply and portably (since it also works for non-IEEE 754 systems) as .RS .nf \&\fCfunc hassubnormals(\|) return issubnormal(macheps(0))\fP .fi .RE but it will run somewhat more slowly, since the current portable implementation of .B macheps(x) involves a loop. Another simple implementation of this function uses predefined constants: .RS .nf \&\fCfunc hassubnormals(\|) return (MINNORMAL > MINSUBNORMAL)\fP .fi .RE .\" .............................................. .SS "Special values: Infinity and NaN" IEEE 754 also defines two special values: Infinity, and NaN (not-a-number). The latter are expected to be available in two flavors: quiet and signaling, but some architectures provide only one kind. The distinction between the two NaNs is rarely significant: the Standard's intent was that quiet NaNs should be generated in numerical operations, while signaling NaNs could be used to initialize numeric variables, so that their use before assignment of a normal value could then be trapped. .PP Both Infinity and NaN are signed, but the sign of a NaN is usually irrelevant, and may not reflect how it was computed: some architectures only generate negative NaNs, others generate only positive ones, and a few may preserve the expected sign in the NaN produced. .\" .............................................. .SS "Signed zero" IEEE 754 has both positive and negative zero, but they compare equal. A positive zero is represented by all zero bits. A negative zero has a leading one-bit, followed by 63 zero bits. .PP Negative zero is generated from .RS .nf .B "0 / \-\&Infinity" .B "sqrt(\-\&0)" .fi .RE .PP In principle, you should be able to get a negative zero in any programming language by simply writing .BR "\-\&0" , but many compilers will convert this to positive zero. You then have to introduce a variable, assign it a zero, and negate the variable, possibly hiding the negation in an external function that simply returns its value, to foil optimizers. In .BR hoc , however, .B "\-\&0" works correctly. .\" .............................................. .SS "Signs of numbers" In .BR hoc , you can extract the sign of any value, .BR x , including negative zero, Infinity, and NaN, like this: .RS .nf .B "copysign(1,x)" .fi .RE The result will be either +1 or \-\&1. .\" .............................................. .SS "Nonstop computing" Infinity and NaN are intended to provide .I "nonstop computing" behavior. In contrast, older architectures tended to abruptly terminate a job that computed a number too large to be stored (an .IR overflow ), or divided by zero. IEEE 754 arithmetic produces Infinity or NaN for these two cases, according to well-defined, and obvious, rules discussed below. .PP On these older systems, .B hoc tries to prevent generation of exceptional values that might otherwise terminate the job: it aborts such computations with an error message, and returns you to top level, ready for more input. On IEEE 754 systems, computation in .B hoc simply proceeds as the Standard intended. .PP The IEEE 754 nonstop property is exceedingly important in modern heavily-pipelined, or parallel, or superscalar, or vector, architectures, all of which have multiple operations underway at once. An interrupt to handle a floating-point exception in software is extremely costly in performance. .\" .............................................. .SS "Properties of Infinity and NaN" Both Infinity and NaN propagate in computations, so that if they occur in intermediate results, they will usually be visible in the final results too, and alert the user to a potential problem. .PP Infinity behaves somewhat like a mathematical infinity: .RS .nf .B "finite / Infinity \(-> 0" .B "Infinity * Infinity \(-> Infinity" .B "Infinity^(finite or Infinity) \(-> Infinity" .fi .RE .PP NaN is produced whenever one or more operands of an arithmetic expression is a NaN, or from most numerical functions with NaN arguments, or from expressions where a limiting value cannot be determined: .RS .nf .B "Infinity \(mi Infinity \(-> NaN" .B "Infinity / Infinity \(-> NaN" .B "0 / 0 \(-> NaN" .fi .RE .PP NaN has a unique property not shared by any other floating-point values, including Infinity: it is not equal to anything, even itself! This should be usable as a completely portable test for a NaN, even on older systems that do not have IEEE 754 arithmetic: .RS .B "(x != x)" is true if, and only if, .B x is a NaN. .RE .PP Regrettably, compiler writers on several systems have failed to grasp this important point, and they incorrectly optimize this test to false. Thus, portable code needs to use a test function, and .B hoc provides three of them: .BR isnan(x) , .BR isqnan(x) , and .BR issnan(x) , which return true if .B x is a NaN (of any flavor, or quiet, or signaling, respectively). .\" .............................................. .SS "What NaNs mean for programmers" The presence of NaNs in the arithmetic system has an extremely important implication for numerical software: comparisons now have .I three outcomes, not two. The expression .B "(x < y)" will be true or false if neither .B x nor .B y is a NaN, but it is called .I unordered if either, or both, is a NaN. In particular, this means that it is almost always .I wrong to use a computer programming language two-branch .B "if \(mi else" statement with a numerical test. Instead, there need to be additional initial tests to check for NaNs. Thus, instead of the .B hoc statement .RS .nf \&\fCif (x > y) \e print "x is greater than y\en" \e else \e print "x is less than or equal to y\en"\fP .fi .RE you should instead write .RS .nf \&\fCif (isnan(x)) \e print "x is a NaN\en" \e else if (isnan(y)) \e print "y is a NaN\en" \e else if (x > y) \e print "x is greater than y\en" \e else \e print "x is less than or equal to y\en"\fP .fi .RE .PP Since .B "if \(mi else" statements are very common in software, but most programmers, and computer textbook authors, are not sufficiently familiar with IEEE 754 arithmetic, you should expect that most existing software, and textbook examples, will fail to behave consistently, or correctly, when dealing with NaN, and possibly also Infinity. .PP There have been some major disasters, such as the failure of the Ariane satellite launch in West Africa, the failure of Patriot missiles in the Gulf War, and a U.S. nuclear aircraft carrier sitting dead in the water for six hours, all attributed to computer programmers who lacked sufficiently understanding of computer arithmetic. Arithmetic really does matter! .PP Numerical software often contains convergence tests of the form .RS .nf .B "while (tolerance is not reached)" .B " reduce the tolerance" .fi .RE If a NaN ever appears in the .B while expression, the test will never be satisfied, and the program will be in an infinite loop. Even famous libraries like EISPACK and LINPACK have routines that will never return because of loops caused by NaNs. [In fairness, both of those libraries were developed before IEEE 754 arithmetic existed, but CDC and Cray machines of that era had special values similar to Infinity and NaN, so even then, there were systems where the code could endlessly loop.] .PP Vendor-provided floating-point systems and run-time libraries are not always entirely reliable in their handling of signed zero, Infinity, and NaN, and portable programs like .B hoc can help to ferret out implementation differences, and errors that should be reported to the vendors. As noted earlier, signed zero is often botched by compiler writers, and two functions commonly available in most programming languages, .B max(x,y) and .BR min(x,y) , in particular are badly done. Their simple implementations use a two-branch conditional like this one for .BR max(x,y) : \fCif (x > y) return x else return y\fP. If either argument is a NaN, then the test will fail, and the second argument will be returned, leading to inconsistent nonsense like .B "max(1,NaN) \(-> NaN" but .BR "max(NaN,1) \(-> 1" . The C and C++ languages lack such functions (users are expected to write them as macros), but Fortran and many other languages have them. In the fall of 2001, tests of 61 Fortran compilers on 15 different UNIX platforms showed that .I all fail to behave consistently for .B max(x,y) and .BR min(x,y) . .\" .............................................. .SS "Unsupported IEEE 754 features" Finally, there are two additional features of IEEE 754 arithmetic that are not yet supported by this version of .BR hoc , but will be in future releases: .RS .\"----------------------------------------------- .TP \w'(1)'u+1n (1) access to floating-point status flags, so that you can tell after the fact whether a computation encountered any exceptional conditions, and .\"----------------------------------------------- .TP (2) access to rounding control, which determines whether rounding is to minus Infinity, zero, nearest, or plus Infinity. The default is always round-to-nearest. .\"----------------------------------------------- .RE .PP Once rounding control is available, .B hoc could, in principle, be extended to support interval arithmetic, in which each numeric operation produces upper and lower bounds for the result. Of course, a proper implementation would also require such support in all of the mathematical functions in the C/C++ run-time library, and such support is lacking almost everywhere. .\" ---------------------------------------------- .SH "HELP SYSTEM" One of the files that .B hoc normally loads on startup contains an extensive help system. Each named constant, variable, function and procedure has an associated function, .BR help_NAME(\|) , where .B NAME is the object name. Help is also available on each of the .B hoc language statements, and on related topics. For an introduction, run .BR help(\|) , and for a detailed list of what help functions are available, invoke .BR help_help(\|) . To display the entire help system, invoke .BR help_all(\|) . .PP Users are encouraged to follow these help convention with their own .B hoc code. .PP The entire help corpus is intentionally .I external to .B hoc itself, to facilitate modification, partial replacement, and internationalization, as discussed in the next section. .\" ---------------------------------------------- .SH INTERNATIONALIZATION The .B hoc help system can be readily extended to support documentation in languages other than English, and early releases contain limited prototype text in several languages. .PP Changing the language alters only documentation and program messages: the basic .B hoc language remains unchanged, and English-centric, just as do virtually all computer programming languages. .\" .............................................. .SS "Selecting a language" An alternate language is selected at run-time by defining any one of three environment variables: .BR LC_ALL , .BR LC_MESSAGES , or .BR LANG , just as described for other programming languages in .BR locale (1). These variables take values of a locale code, the values of which you can list by .RS .nf .B "\fClocale -a | sort -f\fP" .fi .RE You could thus launch a German version of .B hoc like this: .RS .nf .B "\fCenv LANG=de hoc\fP" .fi .RE Environment variables, rather than command-line options, control the locale selection, because it is likely that most individuals will want to choose a fixed locale, and that can be done once and for all in user login files, and also because several UNIX library functions access the locale environment variables to guide their behavior. UNIX users could also create convenient shell aliases, e.g., in .BR csh (1)/ .BR tcsh (1) syntax, .RS .nf \&\fCalias hoc-da 'env LANG=da hoc \e!*'\fP \&\fCalias hoc-de 'env LANG=de hoc \e!*'\fP \&\fCalias hoc-fr 'env LANG=fr hoc \e!*'\fP \&\fC.\|.\|.\fP .fi .RE .\" .............................................. .SS "What if you have no locale support?" Virtually all UNIX vendors today provide locale support, but they usually require installation of one or more additional software packages that your system manager may have omitted, but is probably willing to install on request. .PP Locale support is usually present in one of these directories; besides using the .BR locale (1) command as shown in the previous subsection, you can run .BR ls (1) on the appropriate one of them to see what locales are installed on your system: .RS .TP \w'\&\fI/usr/lib/nls/loc/locales\fP'u+2n \&\fI/usr/share/locale\fP Apple Darwin (MacOS X), FreeBSD, GNU/Linux (all architectures) .TP \&\fI/usr/lib/nls/loc\fP Compaq/DEC Alpha, IBM AIX .TP \&\fI/usr/share/i18n/locales\fP GNU/Linux (all architectures) .TP \&\fI/usr/lib/nls/loc/locales\fP Hewlett-Packard HP-UX .TP \&\fI/usr/lib/locale\fP SGI IRIX, Sun Solaris .RE .\" .............................................. .SS "What the locale affects" Normally, changing the locale affects more than just text: dates, monetary formats, numbers, and sort order all change. However, for now, in the interests of simplicity, and cross-platform and cross-locale consistency, .B hoc sets the locale categories for .BR LC_COLLATE , .BR LC_CTYPE , .BR LC_MESSAGES , .BR LC_MONETARY , .BR LC_NUMERIC , and .B LC_TIME to their traditional (English/American) values. Changes will be needed in future versions of .B hoc to support other values of these categories; some of that support is already available, as shown in the next subsection. .\" .............................................. .SS "Changing the locale inside \fBhoc\fP programs" Locale categories can be set in the environment from .I inside .B hoc programs to control calendar date and time formatting by the .B strftime(\|) function: .RS .nf \&\fC# Show time in the default locale: hoc> strftime("%c",systime()) Fri Dec 21 15:18:14 2001 # Switch to Portuguese: ISO8859-1 (Latin-1) encoding: hoc> old_lc_time = putenv("LC_TIME", "pt") hoc> strftime("%c",systime()) sex 21 dez 2001 03:17:29 PM MST # Restore the original locale: hoc> ignore = putenv("LC_TIME", old_lc_time)\fP .fi .RE The current locale setting can be saved and restored as shown. Less desirably, the value \&\fC"C"\fP resets it to the C/C++ default of English. .PP The locale code is interpreted as the name of a subdirectory in which to find a localized version of any system file that .B hoc loads at startup time. For example, in a Danish locale, it will load the English file, \&\fChelp.hoc\fP, and then the Danish file, \&\fCda/help.hoc\fP, from the .B hoc system installation directory, provided that the localized file exists. Otherwise, .B hoc is silent about its absence. .\" .............................................. .SS "Changing the language of internal messages" The .B hoc program contains a number of messages that are hard-coded in English. Any, or all, of these can be replaced at run time by assignments to special variables named with the reserved seven-character prefix .BR _\|_\|_msg_ (yes, there are .I three leading underscores) used to identify translation variables. .PP These variables are normally only set in the .I @SYSHOCXLTBASE@ files in the .B hoc system directory tree, but they can also be set by user programs as well, unless they have been defined as permanent constants. .PP See the comments in those files for further documentation. Except for translation work, it should never be necessary for ordinary users to reference or modify these variables. .\" .............................................. .SS "Character set constraints" The significant constraint is that characters must be representable in 8-bit character sets, such as the dozen or so .RI ISO8859- n sets that supply characters needed for European languages, or the Unicode (also known as ISO10646-1) UTF-8 variable-byte-count encoding of potentially two million or so symbols used in the world's writing systems. In addition, the .B hoc user must be running the program in an environment capable of such display. .\" .............................................. .SS "Changing screen display fonts" In a UNIX system, you might first scan the voluminous output of .BR xlsfonts (1) to find out what fonts are available for your window system, and then launch a terminal window like this: .RS .nf \&\fCxterm -fn \e -adobe-courier-medium-r-normal--14-100-100-100-m-90-iso8859-1 &\fP .fi .RE to get a 14pt font with all of the characters needed for ISO8859-1 (Latin 1, handling most of the languages of Western Europe, and many others, such as Hawaiian, Indonesian, and Swahili). .PP Your system manager may be able to tell you about additional window system fonts that may also be available, but are not loaded by default. For example, at the maintainer's site, there is a large collection of Asian and European fonts installed in the .BR emacs (1) editor tree. To add, say, the European collection, in a shell window type .RS .nf \&\fCxset fp+ /usr/local/share/emacs/fonts/European xset fp rehash\fP .fi .RE The new fonts will then be available, and will be listable by .BR xlsfonts (1). You can make those additions permanent by adding those two commands to your .I $HOME/.xinitrc or .I $HOME/.xsession file; the name is platform-dependent, so the best choice is to make them identical, with one a symbolic link to the other. .PP Use .RS .nf \&\fCxset q\fP .fi .RE to find out what font directories are currently in the font search path. .PP Each X Window System font directory has a \&\fCfonts.dir\fP text file that maps short file names to long font names. There is sometimes also a \&\fCfonts.alias\fP text file to provide short aliases for the otherwise rather long font names used in the X Window System. You can scan those files to see what is available. .PP Recent versions of .BR xterm (1) have a special option, .BR \-u8 , to handle UTF-8 multibyte encoding, but you then need to use a font with the corresponding character repertoire: .RS .nf \&\fCxterm -u8 -fn \e -misc-fixed-medium-r-normal--20-200-75-75-c-100-iso10646-1 &\fP .fi .RE .\" .............................................. .SS "Documentation for \fBhoc\fP in other languages" Internationalized documentation will usually augment, rather than replace, the English documentation. That way, translations can be developed incrementally. Thus, in a French environment, .B help(\|) responds in English, while output from .B aide(\|) is in French. On startup, .B hoc will then usually display a greeting in two languages: English, and the local one. Here is what this looks like in the French locale: .PP .RS .nf \&\fC% env LANG=fr hoc -------------------------------------------------------------- Welcome to the extensible high-order calculator, hoc. This is hoc version 7.0.0.beta [15-Dec-2001]. Type help() for help, news() for news, and author() for author information. This system supports IEEE 754 floating-point arithmetic. -------------------------------------------------------------- -------------------------------------------------------------- Bienvenue à la calculatrice, hoc. C'est la version 7.0 du 15 décembre 2001. Taper aide() pour de l'assistance, nouvelles() pour des nouvelles, et auteur() pour des renseignements sur les auteurs. Cet ordinateur supporte l'arithmétique en virgule flottante du standard IEEE 754. --------------------------------------------------------------\fP .fi .RE .PP The maintainer will be grateful for contributions of additional translations of .B hoc help files and internal messages! .\" ---------------------------------------------- .SH "HOC SUPPORT IN GNU EMACS" When .B hoc is installed properly, it adds a new library, .IR hoc.el , to the .I emacs/site-lisp directory, which should always be included in the .BR emacs (1) .I load-path variable (in an editor session, type \fCC-h vload-path\fP to display it). .PP By suitable manual edits to the .I site-init.el file in that directory, your system manager could make .B hoc-mode support automatically available, but the .B hoc installation process cannot safely do that automatically. .PP You can test whether this has been done at your site by visiting a new file with extension .IR .hoc ; if the .BR emacs (1) mode line shows \fC(hoc .\|.\|.)\fP, instead of something else, like \fC(fundamental .\|.\|.)\fP, then you need do nothing more: .B hoc-mode is already fully installed. .PP Otherwise, in order to avoid the need for tedious manual loading of the .B hoc support in .BR emacs (1), add this snippet of Emacs Lisp code at the end of your .I $HOME/.emacs initialization file: .RS .nf \&\fC(if (string-lessp (substring emacs-version 0 2) "19") ; earlier than 19.x (progn (setq auto-mode-alist (cons (cons "\\.hoc$" 'hoc-mode) auto-mode-alist)) (autoload 'hoc-mode "hoc" "Enter hoc mode." t nil)) (progn (if (not (assoc "\\.hoc$" auto-mode-alist)) (setq auto-mode-alist (cons (cons "\\.hoc$" 'hoc-mode) auto-mode-alist))) (autoload 'hoc-mode "hoc" "Enter hoc (high-order calculator) mode." t nil)))\fP .fi .RE There are two sections in this code, one for (now very old) .BR emacs (1) versions before 19.x, and the other for all newer versions. They add a binding between files with extension .I .hoc and .B hoc-mode in .BR emacs (1), and arrange for the .I hoc.el library to be loaded the first time that it is required. .\" ---------------------------------------------- .SH "DESCRIPTIONS OF BUILT-IN FUNCTIONS AND PROCEDURES" These descriptions are taken from the output of the corresponding .B help_xxx(\|) functions, and, apart from font differences, are intended to be identical to them. The .B help_xxx(\|) functions are considered to be the definitive documentation of each function. .PP In the following descriptions, square brackets on number ranges indicate that the endpoint is .IR included ; parentheses indicate that the endpoint is .IR excluded . .\" ---------------------------------------------- .TP \w'\fBstrftime(format,time)\fP'u+2n .B abort(message) .B abort(message) prints .BR message , then aborts evaluation of the current expression, returning to top-level without further processing of the remainder of the current statement or function/procedure call chain. The message should include the name of the function calling .BR abort() , since there is currently no function call traceback, and end with a newline. .\" ---------------------------------------------- .TP .B abs(x) .B abs(x) returns the absolute value of .BR x . .\" ---------------------------------------------- .TP .B acos(x) .B acos(x) returns the arc cosine of .BR x . .B x must be in [\-1.\|.\|.+1]. .\" ---------------------------------------------- .TP .B acos(x) .B acos(x) returns the arc cosine of .BR x . .B x must be in [\-1.\|.\|.+1]. .\" ---------------------------------------------- .TP .B acosh(x) .B acosh(x) returns the inverse hyperbolic cosine of .BR x . .B x must be outside the interval (\-1.\|.\|.+1). .\" ---------------------------------------------- .TP .B asinh(x) .B asinh(x) returns the inverse hyperbolic sine of .BR x . .\" ---------------------------------------------- .TP .B atan(x) .B atan(x) returns the arc tangent of .BR x . .\" ---------------------------------------------- .TP .B atanh(x) .B atanh(x) returns the inverse hyperbolic tangent of .BR x . .\" ---------------------------------------------- .TP .B author() .B author() prints information about the program authors. .\" ---------------------------------------------- .TP .B cbrt(x) .B cbrt(x) returns the cube root of .BR x . .\" ---------------------------------------------- .TP .B ceil(x) .B ceil(x) returns the smallest integer greater than or equal to .BR x . .\" ---------------------------------------------- .TP .B copysign(x,y) .B copysign(x,y) returns a value with the magnitude of .BR x , and the sign of .BR y . .\" ---------------------------------------------- .TP .B cos(x) .B cos(x) returns the cosine of .B x .RB ( x in radians). Expect severe accuracy loss for large .BR |x| . .\" ---------------------------------------------- .TP .B cosd(x) .B cosd(x) returns the cosine of .B x .RB ( x in degrees). Expect severe accuracy loss for large .BR |x| . .\" ---------------------------------------------- .TP .B cosh(x) .B cosh(x) returns the hyperbolic cosine of .BR x . .\" ---------------------------------------------- .TP .B cpulimit(t) .B cpulimit(t) sets the CPU time limit from now to an additional .B t seconds, sets the system variable .B __CPU_LIMIT__ to .BR t , and returns the current CPU time limit, which is always measured from the .I start of the job. .IP If the limit is exceeded, execution of the current expression is aborted, control returns to the top-level interpreter, and the time limit is incremented by the current value of .BR __CPU_LIMIT__ . .IP Although .B t may be fractional, on most operating systems, the time limit is an integer, so .B t will be rounded up internally to the nearest integer before setting the time limit. .IP If resource usage and limits are not supported on the current platform, this function has no effect, other than setting .BR __CPU_LIMIT__ , and returning Infinity. .IP By default, there is no time limit for the job (although some operating systems may impose such limits). .IP Negative, zero, and NaN arguments are treated like Infinity. .IP NB: This function is .IR experimental , and may be withdrawn in future versions. .\" ---------------------------------------------- .TP .B erf(x) .B erf(x) returns the error function of .BR x . .\" ---------------------------------------------- .TP .B erfc(x) .B erfc(x) returns the complementary error function of .BR x . .\" ---------------------------------------------- .TP .B errbits(x,y) .BR errbits(x,y) , with .B y an approximation to .BR x , returns the number of bits that .B y is in error by. .\" ---------------------------------------------- .TP .B eval(string) .B eval(string) pushes its argument string, which must contain valid .B hoc code, onto the input stack so that it will be evaluated next. .IP This function makes it possible for .B hoc programs to construct new .B hoc code on-the-fly and then run it. .IP There is a limit, set by the compiled-in dimension of the input pushback buffer, on the size of the expression that can be evaluated, but it is fairly large: it should be at least 10K characters in all .B hoc implementations. In this implementation, it is set to .IR nnn . [Print the value of .B _\|_MAX_PUSHBACK_\|_ in your implementation.] .\" ---------------------------------------------- .TP .B exp(x) .B exp(x) returns the exponential function of .BR x , .BR E^x . .\" ---------------------------------------------- .TP .B expm1(x) .B expm1(x) returns the exponential function of .BR x , less 1: .BR "E^x \(mi 1" . .IP For small .BR x , .B exp(x) is approximately 1, so there is serious subtraction loss in directly using .BR "exp(x) \(mi 1" ; .B expm1(x) avoids this loss. .IP From Sun Solaris documentation: .RI `` The .B expm1(\|) .I and .B log1p(\|) .I "functions are useful for financial calculations of" .BR "((1 + x)^n \(mi 1) / x" , .I namely: .IP .RS .RS .B "expm1(n * log1p(x))/x" .RE .RE .IP .I when .B x .I "is very small (for example, when performing" .I "calculations with a small daily interest" .I "rate). These functions also simplify writing" .IR "accurate inverse hyperbolic functions." '' .\" ---------------------------------------------- .TP .B exponent(x) .B exponent(x) returns the base-2 exponent of .BR x , such that .IP .RS .RS .B "x == significand(x) * 2^exponent(x)" .RE .RE .IP where .B |significand(x)| is in [1...2). .IP For IEEE 754 arithmetic, normal numbers have .B exponent(x) in [-1022...1023] and subnormal numbers, if supported, have .B exponent(x) in [-1074...1023]. .IP .IR WARNING : The power .B 2^exponent(x) will underflow to zero for IEEE 754 subnormal numbers, so for such numbers, the right-hand side must be computed with suitable scaling, like this: .IP .RS .RS .B "(significand(x) * 2^(exponent(x) + 52)) * 2^(-52)" .RE .RE .\" ---------------------------------------------- .TP .B factorial(n) .B factorial(n) returns .BR "n! = n*(n\(mi1)*(n\(mi2)*.\|.\|.*1" , where .BR "1! == 0! == 1" , by definition. Negative arguments generate a call to .BR abort(\|) . .\" ---------------------------------------------- .TP .B floor(x) .B floor(x) returns the greatest integer less than or equal to .BR x . .\" ---------------------------------------------- .TP .B fmod(x,y) .B fmod(x,y) returns the remainder of the division of .B x by .BR y . .\" ---------------------------------------------- .TP .B gamma(x) .B gamma(x) returns the Gamma (generalized factorial) function of .BR x . .\" ---------------------------------------------- .TP .B gcd(x,y) .B gcd(x,y) returns the greatest common divisor of .B x and .BR y . .\" ---------------------------------------------- .TP .B getenv(envvar) .B getenv(envvar) returns the string value of the environment variable .BR envvar , or an empty string if it is not defined. .\" ---------------------------------------------- .TP .B hexfp(x) .B hexfp(x) returns a string containing the hexadecimal floating-point representation of .BR x , in the form .IP .RS .RS "+0x1.hhhhh...p+ddddd" .RE .RE .IP Trailing zeros in the fraction, and leading zeros in the exponent, are dropped, and the sign is always included. .IP See also .BR help_hexint() , .BR help_number() , and .BR help_string() . .\" ---------------------------------------------- .TP .B hexint(x) .B hexint(x) returns a string containing the hexadecimal integer representation of .BR x , if that is possible, in the form .IP .RS .RS "+0xhhhhh..." .RE .RE .IP Leading zeros are dropped, and the sign is always included. .IP If .B x is too big to represent as an exact integer, then the floating-point representation, .BR hexfp(x) , is returned instead. .IP See also .BR help_hexfp() , .BR help_number() , and .BR help_string() . .\" ---------------------------------------------- .TP .B hypot(x,y) .B hypot(x,y) function computes the length of the hypotenuse of a right-angled triangle, .BR "sqrt(x^2 + y^2)" , but without accuracy loss or range limitation from premature overflow or underflow. .IP This function has possibly unexpected behavior for exceptional arguments: when either argument is Infinity, then the result is Infinity, .I "even if" the other argument is a NaN! The explanation is found on the 4.3BSD manual page: .RS .RS \&.\|.\|. programmers on machines other than a VAX (it has no infinity) might be surprised at first to discover that .BR "hypot(+infinity,NaN) = +infinity" . This is intentional; it happens because .B "hypot(infinity,v) = +infinity" for all .BR v , finite or infinite. Hence .B hypot(infinity,v) is independent of .BR v . Unlike the reserved operand on a VAX, the IEEE NaN is designed to disappear when it turns out to be irrelevant, as it does in .BR hypot(infinity,NaN) . \&.\|.\|. .RE .RE .\" ---------------------------------------------- .TP .B ilogb(x) .B ilogb(x) returns the exponent part of .BR x , that is, .BR "int(log2(x))" . .\" ---------------------------------------------- .TP .B index(s,t) .B index(s,t) returns the index of string .B t in string .BR s , counting from 1, or 0 if .B t is not found in .BR s . .\" ---------------------------------------------- .TP .B int(x) .B int(x) returns the integer part (truncated toward zero) of .BR x . .\" ---------------------------------------------- .TP .B isfinite(x) .B isfinite(x) returns 1 (true) if .B x is finite and otherwise, 0 (false). .\" ---------------------------------------------- .TP .B isinf(x) .B isinf(x) returns 1 (true) if .B x is Infinite, and otherwise, 0 (false). .\" ---------------------------------------------- .TP .B isnan(x) .B isnan(x) returns 1 (true) if .B x is a NaN, and otherwise, 0 (false). .\" ---------------------------------------------- .TP .B isnormal(x) .B isnormal(x) returns 1 (true) if .B x is finite and normalized and not subnormal, and otherwise, 0 (false). .\" ---------------------------------------------- .TP .B isqnan(x) .B isqnan(x) returns 1 (true) if .B x is a quiet NaN, and otherwise, 0 (false). .IP On some architectures (e.g., Intel x86 and MIPS), there is only one type of NaN. .B isqnan(x) is then defined to return .BR isnan(x) . .\" ---------------------------------------------- .TP .B issnan(x) .B issnan(x) returns 1 (true) if .B x is a signaling NaN, and otherwise, 0 (false). .IP On some architectures (e.g., Intel x86 and MIPS), there is only one type of NaN. .B issnan(x) is then defined to return .BR isnan(x) . .IP You can test whether your system has both quiet and signaling NaNs like this: .BR issnan(NaN) . The result is 0 (false) if distinct NaN types are available, and 1 (true) if not. .\" ---------------------------------------------- .TP .B issubnormal(x) .B issubnormal(x) returns 1 (true) if .B x is subnormal (formerly, denormalized), and otherwise, 0 (false). .\" ---------------------------------------------- .TP .B J0(x) .B J0(x) returns the Bessel function of the first kind of order 0 of .BR x . .\" ---------------------------------------------- .TP .B J1(x) .B J1(x) returns the Bessel function of the first kind of order 1 of .BR x . .\" ---------------------------------------------- .TP .B Jn(n,x) .B Jn(n,x) returns the Bessel function of the first kind of integral order .B n of .BR x . .\" ---------------------------------------------- .TP .B lcm(x,y) .B lcm(x,y) returns the least common multiple of .B int(x) and .BR int(y) . .\" ---------------------------------------------- .TP .B ldexp(x,y) .B ldexp(x,y) returns .BR "x * 2^(int(y))" . .\" ---------------------------------------------- .TP .B lgamma(x) .B lgamma(x) returns the natural logarithm of .BR gamma(x) . .IP Because .BR gamma(x) has poles at zero and at negative integer values, and grows factorially with increasing .BR x , it reaches the floating-point overflow limit fairly quickly. For 64-bit IEEE 754 arithmetic, this happens at approximately .BR "x = 206.779" . However, .B lgamma(x) is representable almost to the overflow limit. In 64-bit IEEE 754 arithmetic, this happens at approximately .BR "x = 2.55e+306" (the overflow limit is 1.80e+308). .IP Unfortunately, there is mathematically-unavoidable accuracy loss when .B gamma(x) is computed from .BR exp(lgamma(x)) , so you should avoid the logarithmic form unless you really need large arguments that would cause overflow. .\" ---------------------------------------------- .TP .B ln(x) .B ln(x) returns the natural (base-E) logarithm of .BR x . .\" ---------------------------------------------- .TP .B load(filename) .B load(filename) reads input from the specified file. The file can be prepared by hand, or by the .B save(\|) command. .IP Loaded files can themselves contain .B load(\|) commands, with nesting up to some unknown limit imposed by the host operating system on the maximum number of simultaneously-open files for a process, user, or the entire system. .IP This command can be disabled for security reasons by the command-line .B \-no-load option. .IP The return value is an empty string on success, and otherwise, an error message. .\" ---------------------------------------------- .TP .B log(x) .B log(x) returns the natural (base-E) logarithm of .BR x . .\" ---------------------------------------------- .TP .B log10(x) .B log10(x) returns the logarithm to the base 10 of .BR x . .\" ---------------------------------------------- .TP .B log1p(x) .B log1p(x) returns .BR "log(1 + x)" , but without accuracy loss for small .BR |x| . .B x must be in (\-1.\|.\|.infinity]. .\" ---------------------------------------------- .TP .B log2(x) .B log2(x) returns the logarithm to the base 2 of .BR x . .\" ---------------------------------------------- .TP .B logfile(filename) .B logfile(filename) logs the session on the specified file, which, for security reasons, .I must be a new file. It is a normal text which you can edit, print, and view. .IP Input is recorded verbatim. Output is recorded in comments. This permits the logfile to be read by .B hoc later, allowing a session to be replayed. .IP If a logfile is already opened, it is closed before opening the new one. .IP Logging may be turned on and off with .B logon(\|) and .BR logoff(\|) , and can be entirely disabled for security reasons by the command-line .B \-no-logfile option. .IP The return value is an empty string on success, and otherwise, an error message. .\" ---------------------------------------------- .TP .B logoff(\|) .B logoff(\|) suspends logging to any open log file. It is .I not an error if there is no current log file. .\" ---------------------------------------------- .TP .B logon(\|) .B logon(\|) restores logging to any open log file. It is .I not an error if there is no current log file. .\" ---------------------------------------------- .TP .B macheps(x) .B macheps(x) returns the generalized machine epsilon of .BR x , the smallest number which, when added to .BR x , produces a sum that still differs from .BR x : .BR "(x + macheps(x)) != x" . .IP .B macheps(1) is the normal machine epsilon. .IP .B macheps(\-\&x) is .BR macheps(x)/base , or equivalently, the smallest number that can be subtracted from .B x with the result still different from .BR x . .IP .B macheps(0) is the smallest representable floating-point number. Depending on the host system, it may be a normal number, or a subnormal number (invoke .B help_subnormal(\|) for details). .\" ---------------------------------------------- .TP .B max(x,y) .B max(x,y) returns the larger of .B x and .BR y . .IP If .I either argument is a NaN, the result is a NaN. .\" ---------------------------------------------- .TP .B maxnormal(\|) .B maxnormal(\|) returns the maximum positive normal number. .\" ---------------------------------------------- .TP .B min(x,y) .B min(x,y) returns the smaller of .B x and .BR y. .IP If .I either argument is a NaN, the result is a NaN. .\" ---------------------------------------------- .TP .B minnormal(\|) .B minnormal(\|) returns the minimum positive normal number. .\" ---------------------------------------------- .TP .B minsubnormal(\|) .B minsubnormal(\|) returns the minimum positive subnormal number. If subnormals are not supported, then it returns the minimum normal number instead. .\" ---------------------------------------------- .TP .B nearest(x,y) .B nearest(x,y) returns the next different machine number nearest .BR x , in the direction of the infinity with the same sign as .BR y. .\" ---------------------------------------------- .TP .B nextafter(x,y) .B nextafter(x,y) returns the nearest machine number nearest .BR x , in the direction of the infinity with the same sign as .BR y . .\" ---------------------------------------------- .TP .B nint(x) .B nint(x) returns the nearest integer to .BR x , rounding away from zero in case of a tie. .\" ---------------------------------------------- .TP .B now(\|) .B now(\|) .\" NB: TWO spaces before 8 in this date! returns the current date, in the form "Dec 8 2001". If the month day has only one digit, then it is preceded by an extra space, so that the format is uniformly "MMM DD YYYY". .\" ---------------------------------------------- .TP .B number(s) .B number(s) converts the string .B s to a number and returns it. .IP .B s should contain either a hexadecimal floating-point number, a hexadecimal integer, a decimal floating-point number, a decimal integer, or a representation of NaN or Infinity. .IP If .B s contains a number followed by unrecognizable text, the number is converted and returned, and the following text is silently ignored. Otherwise, the return value is 0, and the text is silently ignored. Thus, .B number("123abc") returns 123, and .B number("abc") returns 0. .IP This function is an inverse of .BR hexfp() , .BR hexint() , and .BR string() : .IP .RS .RS .nf .BR "number(hexfp(x)) == x" " [for all numeric " x "]" .BR "number(hexint(x)) == x" " [for all numeric " x "]" .BR "number(string(x)) == x" " [for all numeric " x "]" .fi .RE .RE .IP See also .BR help_hexint() , .BR help_hexfp() , and .BR help_string() . .\" ---------------------------------------------- .TP .B printenv(prefix) .B printenv(prefix) prints the names and values of all environment variables whose names match that .BR prefix . Use .B printenv("") to match all names. .\" ---------------------------------------------- .TP .B putenv(envvar,newval) .B putenv(envvar,newval) replaces the current string value of the environment variable .B envvar with .BR newval , and returns its old value. .IP This affects subsequent calls to .BR getenv() , but does .I not affect the environment of the parent process. .IP You can use this function to set locale environment variables that control the output of dates and times, in order to get internationalized output from .BR strftime() . .\" ---------------------------------------------- .TP .B rand(\|) .B rand(\|) returns a pseudo-random number uniformly distributed on (0.\|.\|.1). Unless the seed is changed (see .BR help_setrand(\|) ), successive runs of the same program will generate the same sequence of pseudo-random numbers. .IP See .B help_randint(\|) for uniformly-distributed integers in an interval, and .B help_randl(\|) for logarithmically-distributed pseudo-random numbers. .IP The pseudo-random generator algorithm is platform-independent, allowing reproduction of the same number sequence on any computer architecture. .\" ---------------------------------------------- .TP .B randint(x,y) .B randint(x,y) returns a pseudo-random integer uniformly distributed on .BR [int(x).\|.\|.int(y)] . Unless the seed is changed (see .BR help_setrand(\|) ), successive runs of the same program will generate the same sequence of pseudo-random numbers. .IP The pseudo-random generator algorithm is platform-independent, allowing reproduction of the same number sequence on any computer architecture. .\" ---------------------------------------------- .TP .B randl(x) .B randl(x) returns a pseudo-random number logarithmically distributed on .BR (1,exp(x)) . Unless the seed is changed (see .BR help_setrand(\|) ), successive runs of the same program will generate the same sequence of pseudo-random numbers. .IP This function can be used to generate logarithmic distributions on any interval: .B a*randl(ln(b/a)) is logarithmically distributed on .BR (a.\|.\|.b) . .IP The pseudo-random generator algorithm is platform-independent, allowing reproduction of the same number sequence on any computer architecture. .\" ---------------------------------------------- .TP .B remainder(x,y) .B remainder(x,y) returns the remainder .BR "r = x \(mi n*y" , where .B n is the integral value nearest the exact value .BR x/y . When .BR "|n \(mi x/y| = 1/2" , the value of .B n is chosen to be even. .\" ---------------------------------------------- .TP .B rint(x) .B rint(x) returns the integral value nearest .B x in the direction of the current IEEE 754 rounding mode. .\" ---------------------------------------------- .TP .B rsqrt(x) .B rsqrt(x) returns the reciprocal square root, .BR 1/sqrt(x) . .\" ---------------------------------------------- .TP .B save(filename,prefix) .B save(filename,prefix) saves the state of the current session in the specified file, which, for security reasons, .I must be a new file. .IP If the prefix string is not empty, then only symbols whose initial characters match the prefix string are saved. .IP Symbols are output in strict alphabetical order .IP Reserved symbol names (those beginning with two or more underscores) are not saved. Predefined immutable names are also excluded. .IP The saved file is a normal text file that can be later read by .B hoc on any platform. .IP [NB: A temporary implementation restriction also excludes user-defined immutable names, and all functions and procedures.] .IP This command can be disabled for security reasons by the command-line .B \-no-save option. .IP The return value is an empty string on success, and otherwise, an error message. .\" ---------------------------------------------- .TP .B scalb(x,y) .B scalb(x,y) returns .BR "x * 2^(int(y))" . .\" ---------------------------------------------- .TP .B second(\|) .B second(\|) returns the CPU time in job seconds since some fixed time in the past. Take the difference of two bracketing calls to get the elapsed CPU time for a block of code. For example, .IP .RS .nf \&\fCPREC = 3 x = 1 t = second(\|) for (k = 1; k < 1000000; ++k) x *= 1 second(\|) - t 4.73\fP .fi .RE .\" ---------------------------------------------- .TP .B setrand(x) .BR setrand(x) , where .B x should be a large integer, sets the seed of the pseudo-random number generator to .BR x , and returns the old seed. .IP As a special case, when .B x is zero, .B x is ignored, and a new seed is constructed from a random number multiplied by either the calendar time (if available), or the process number (if available), or the next pseudo-random number. .IP If .B setrand(x) is never called, then .BR rand(\|) , .BR randint(\|) , and .B randl(x) will each return the same sequence of pseudo-random numbers: see .BR help_rand(\|) , .BR help_randint(\|) , and .BR help_randl(\|) . .IP The pseudo-random generator algorithm is platform-independent, allowing reproduction of the same number sequence on any computer architecture. .\" ---------------------------------------------- .TP .B significand(x) .B significand(x) returns the significand of .BR x , .BR s, such that .BR "x = s * 2^n" , with .B s in [1,2), and .B n an integer. .IP See .B help_exponent() for how to extract the exponent, .BR n . .\" ---------------------------------------------- .TP .B sin(x) .B sin(x) returns the sin of .B x .RB ( x in radians). Expect severe accuracy loss for large .BR |x| . .\" ---------------------------------------------- .TP .B sind(x) .B sind(x) returns the sin of .B x .RB ( x in degrees). Expect severe accuracy loss for large .BR |x| . .\" ---------------------------------------------- .TP .B sinh(x) .B sinh(x) returns the hyperbolic sin of .BR x . .\" ---------------------------------------------- .TP .B sqrt(x) .B sqrt(x) returns the square root of .BR x . .B x must be in [\-0.\|.\|.Infinity]. .IP Special case: .BR "sqrt(\-0) \(-> \-0" . .\" ---------------------------------------------- .TP .B strftime(format,time) .B strftime(format,time) converts a numeric time measured in seconds since the epoch (usually obtained from .BR systime(\|) ) to a formatted string determined by one or more of these format items: .RS .RS .\" - - - - - - - - - - - - - - - - - - - - - - - .TP \w'\fB%M\fP'u+2n .B %A the locale's full weekday name. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %a the locale's abbreviated weekday name. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %B the locale's full month name. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %b the locale's abbreviated month name. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %c the locale's appropriate date and time representation. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %d the day of the month as a decimal number (01\(mi31). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %H the hour (24-hour clock) as a decimal number (00\(mi23). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %I the hour (12-hour clock) as a decimal number (01\(mi12). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %j the day of the year as a decimal number (001\(mi366). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %M the minute as a decimal number (00\(mi59). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %m the month as a decimal number (01\(mi12). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %p the locale's equivalent of either ``AM'' or ``PM''. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %S the second as a decimal number (00\(mi60). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %U the week number of the year (Sunday as the first day of the week) as a decimal number (00\(mi53). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %W the week number of the year (Monday as the first day of the week) as a decimal number (00\(mi53). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %w the weekday (Sunday as the first day of the week) as a decimal number (0\(mi6). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %X the locale's appropriate time representation. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %x the locale's appropriate date representation. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %Y the year with century as a decimal number. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %y the year without century as a decimal number (00\(mi99). .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %Z the time zone name. .\" - - - - - - - - - - - - - - - - - - - - - - - .TP .B %% is replaced by `%'. .RE .RE .\" ---------------------------------------------- .TP .B string(x) .B string(x) returns a string containing the decimal representation of .BR x , either in integer form (if .B x is exactly representable that way), or in floating-point form. .IP See also .BR help_hexfp() , .BR help_hexint() , and .BR help_number() . .\" ---------------------------------------------- .TP .B substr(s,start,len) .B substr(s,start,len) returns a substring of string .B s beginning at character .B start (counting from 1), of length at most .BR len . If .B start is outside the string, it is moved to the nearest endpoint, .I without adjusting .BR len . Fewer than .B len characters will be returned if the substring extends outside the original string. .\" ---------------------------------------------- .TP .B systime(\|) .B systime(\|) returns the calendar time in seconds since the epoch. On UNIX systems, the epoch starts on January 1, 1970 00:00:00 UTC. Other operating systems make different choices. It can be converted to a formatted time string with .BR strftime(\|) . .\" ---------------------------------------------- .TP .B tan(x) .B tan(x) returns the tangent of .B x .RB ( x in radians). Expect severe accuracy loss for large .BR |x| . .\" ---------------------------------------------- .TP .B tand(x) .B tand(x) returns the tangent of .B x .RB ( x in degrees). Expect severe accuracy loss for large .BR |x| . .\" ---------------------------------------------- .TP .B tanh(x) .B tanh(x) returns the hyperbolic tangent of .BR x . .\" ---------------------------------------------- .TP .B tolower(s) .B tolower(s) returns a copy of string .B s with uppercase letters converted to lowercase, and all other characters unchanged. .IP Which characters are considered uppercase depends on the locale. On UNIX, this is determined by the .B LC_CTYPE environment variable. .\" ---------------------------------------------- .TP .B toupper(s) .B toupper(s) returns a copy of string .B s with lowercase letters converted to uppercase, and all other characters unchanged. .IP Which characters are considered lowercase depends on the locale. On UNIX, this is determined by the .B LC_CTYPE environment variable. .\" ---------------------------------------------- .TP .B trunc(x) .B trunc(x) returns the integer part of .BR x , with the fractional part discarded. .\" ---------------------------------------------- .TP .B who(prefix) .B who(prefix) prints all symbols whose initial characters match the .B prefix string, grouped by category. To print all symbols, use an empty prefix: .BR who("") . .\" ---------------------------------------------- .TP .B Y0(x) .B Y0(x) returns the Bessel function of the second kind of order 0 of .BR x , for .BR "x >= 0" . This function is also called .IR "Weber's function" . .\" ---------------------------------------------- .TP .B Y1(x) .B Y1(x) returns the Bessel function of the second kind of order 1 of .BR x , for .BR "x >= 0" . This function is also called .IR "Weber's function" . .\" ---------------------------------------------- .TP .B Yn(n,x) .B Yn(n,x) returns the Bessel function of the second kind of integral order .B n of .BR x , for .BR "x >= 0" . This function is also called .IR "Weber's function" . .\" ---------------------------------------------- .SH "IMPLEMENTATION LIMITS" .B hoc has a few compile-time dimensions that limit the size of certain objects. Their current values are available in these predefined immutable constants: .RS .TP \w'\fB_\|_MAX_PUSHBACK_\|_\fP'u+2n .B _\|_MAX_NAME_\|_ Longest identifier name. .TP .B _\|_MAX_PUSHBACK_\|_ Input pushback buffer size, and thus, also the limit on the length of the string argument that the .B eval(\|) function can handle. .TP .B _\|_MAX_STRING_\|_ Longest character string constant. .TP .B _\|_MAX_TOKEN_\|_ Longest numeric token. .RE .PP The function .B help_limits() can be conveniently used to display their current values. .PP A design goal for future versions of .B hoc is to eliminate these limits entirely, making them subject only to available memory. .\" ---------------------------------------------- .SH EXAMPLES .nf \&\fCfunc gcd(\|) { ## gcd(i,j) returns the greatest common denominator of i and j temp = abs($1) % abs($2) if(temp == 0) return abs($2) return gcd($2, temp) }\fP .PP \&\fCfor(i=1; i<12; i++) print gcd(i,12) print "\en" 1 2 3 4 1 6 1 4 3 2 1\fP .PP \&\fC### Print a table of the representable negative powers of 2 k = 0 x = 1 while (x > 0) \e { print "2^(", k, ") = ", x, "\en" k-- x /= 2 } 2^(0 ) = 1 2^(-1 ) = 0.5 2^(-2 ) = 0.25 2^(-3 ) = 0.125 \&\|.\|.\|. 2^(-1072 ) = 1.9762625833649862e-323 2^(-1073 ) = 9.8813129168249309e-324 2^(-1074 ) = 4.9406564584124654e-324\fP .fi .\" ---------------------------------------------- .SH "INITIALIZATION FILES" On startup, after processing any command-line options that suppress initialization files, .B hoc checks for the existence of local system-wide initialization files, .RS .\"----------------------------------------------- .TP \w'\(bu'u+2n \(bu .BR \fC@SYSHOCRC@\fP , .\"----------------------------------------------- .TP \(bu .BR \fC@SYSHOCDIR@/LN/@SYSHOCRCBASE@\fP , .\"----------------------------------------------- .TP \(bu .BR \fC@SYSHOCHLP@\fP , .\"----------------------------------------------- .TP \(bu .BR \fC@SYSHOCDIR@/LN/@SYSHOCHLPBASE@\fP , .\"----------------------------------------------- .TP \(bu .BR \fC@SYSHOCXLT@\fP , .\"----------------------------------------------- .TP \(bu .BR \fC@SYSHOCDIR@/LN/@SYSHOCXLTBASE@\fP , .\"----------------------------------------------- .RE (LN is replaced by the locale name (see the .B INTERNATIONALIZATION section above), if one is defined, and otherwise, that file is omitted), and a private initialization file, .RS .\"----------------------------------------------- .TP \w'\(bu'u+2n \(bu .BR \fC$HOME/.hocrc\fP , .\"----------------------------------------------- .RE in that order. Any that exist are automatically processed before the remaining command-line options are handled. .PP This feature allows for local customization of .BR hoc , usually for additional constants and functions, as well as for locale-specific translations of output strings. .PP In initialization files, the .BR load(\|) , .BR logfile(\|) , and .B save(\|) commands are .I always available, even if command-line options disable them from use later in the job. .PP If GNU .I readline library support is available in .BR hoc , then its initialization file, \&\fC$HOME/.inputrc\fP, (overriddable by setting an alternate filename in the value of the .B INPUTRC environment variable), can be used for customization of key bindings for command completion, editing, and recall. To restrict any such bindings to .BR hoc , put them in a conditional like this: .RS .nf \&\fC$if @PACKAGE_NAME@ \& .\|.\|. $endif\fP .fi .RE .\" ---------------------------------------------- .SH "SEE ALSO" .BR awk (1), .BR bc (1), .BR dc (1), .BR dircolors (1), .BR emacs (1), .BR expr (1), .BR genius (1), .BR locale (1), .BR vi (1), .BR xlsfonts (1), .BR xterm (1). .br Brian W. Kernighan and Rob Pike, .IR "The UNIX Programming Environment" , Prentice-Hall, 1984, .br ISBN 0-13-937699-2 (hardcover), 0-13-937681-X (paperback), .br LCCN: QA76.76.O63 K48 1984. .\" ---------------------------------------------- .SH BUGS All components of a .B for statement must be non-empty. .PP Error recovery is imperfect within function and procedure definitions. .PP The treatment of newlines is not exactly user-friendly. .PP Arguments \fC$1\fP, etc., are not really variables and thus won't work in constructs like, for instance, \&\fC$1++\fP. .PP Functions and procedures typically have to be declared before use, which makes mutual recursion at first sight impossible. The workaround is to first define a dummy version of one of them. For example, here is an unusual implementation of a pair of functions, each of which returns the factorial of its argument: .RS .nf \&\fCfunc foo() return 0 func bar() {if ($1 > 0) return $1 * foo($1-1) else return 1} func foo() {if ($1 > 0) return $1 * bar($1-1) else return 1}\fP .fi .RE .\" ---------------------------------------------- .SH AVAILABILITY .B hoc is highly portable, and vastly smaller than a compiler for a major programming language, so it should be usable on all computing platforms. When a C or C++ compiler is available, .B hoc can be easily built, validated, and installed using the distribution source code from its master archive: .RS .nf \&\fCftp://ftp.math.utah.edu/pub/hoc http://www.math.utah.edu/pub/hoc/\fP .fi .RE For platforms where suitable compilers are often not installed, there may be binary distributions available at those locations. .PP .\" ---------------------------------------------- .SH COPYRIGHT .nf .\" This copyright notice is extracted verbatim .\" from the README file, and set in a fixed-width .\" font to be distinctive. \&\fCCopyright (C) AT&T 1995 All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and this permission notice and warranty disclaimer appear in supporting documentation, and that the name of AT&T or any of its entities not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. AT&T DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL AT&T OR ANY OF ITS ENTITIES BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\fP .fi .\" ---------------------------------------------- .SH ACKNOWLEDGEMENTS The .B hoc version 7 developer and maintainer (Nelson H. F. Beebe \&\fC\fP) thanks the AT&T/Lucent Bell Labs people (current and former), notably Ken Thompson, Dennis Ritchie, Brian Kernighan, Rob Pike, John Bentley, Bill Plauger, Stu Feldman, David Gay, Norm Schryer, and Bjarne Stroustrup for developing the wonderful UNIX and C/C++ programming environment, and being a constant source of inspiration for software development and superb book authoring. .PP He also thanks the many people at the Free Software Foundation, for enriching UNIX with GNUware, and most notably, Richard Stallman for .BR emacs (1) and .BR gcc (1), for founding the FSF and the GNU Project, and for vigorous campaigning to keep software freely distributable. .PP Finally, he thanks friends and colleagues on the .B hoc help facility translation team for assistance in internationalization: Hugo Bertete-Aguirre (Portuguese), Andrej Cherkaev (Russian), Tanya Damjanovic (Serbian), Michel Debar (French), Miguel Dumett (Spanish), Henryk Hecht (Polish), Michael Hohn (German), Ismail Küçük (Turkish), Young Seon Lee (Korean), Dragan Milicic (Croatian), and Jingyi Zhu (Chinese). [The English and Danish, and part of the French, help facilities were written by the maintainer.] .\"===================================================================== .\" This is for GNU Emacs file-specific customization: .\" Local Variables: .\" fill-column: 50 .\" End: