When you find them, please let us know! See the above for details on how to report and were to EMail your bug reports and hopefully patches to fix them. =-= Problems that have known work-a-rounds: * There is a bug in gcc v4.1.0 that causes calc to fail the regression test. The work-a-round is to compile with gcc v4.1.1 or later. This problems was observed on Fedora 5. =-= mis-features in calc: Some problems are not bugs but rarther mis-features / things that could work better. The following is a list of mis-features that should be addressed and improved someday. * When statement is of the form { ... }, the leading { MUST BE ON THE SAME LINE as the if, for, while or do keyword. This works as expected: if (expr) { ... } However this WILL NOT WORK AS EXPECTED: if (expr) { ... } This needs to be changed. See also "help statement", "help unexpected", and "help todo". * The chi.cal resource file does not work well with odd degrees of freedom. Can someone improve this algorithm? * The intfile.cal resource file reads and writes big or little Endian integers to/from files the hard way. It does NOT use blkcpy. The following code: i = (ord("\n") << 16) | (ord("i") << 8) | ord("H") b = blk() copy(i, b) fd = fopen("file", "w") copy(b, fd); fclose(fd) will write an extra NUL octet to the file. Where as: read intfile i = (ord("\n") << 16) | (ord("i") << 8) | ord("H") be2file(i, "file2") will not. ## Copyright (C) 1999-2007 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: BUGS,v 30.1 2007/03/16 11:09:46 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/RCS/BUGS,v $ ## ## Under source code control: 1994/03/18 14:06:13 ## File existed as early as: 1994 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME det - determinant SYNOPSIS det(m) TYPES m square matrix with elements of suitable type return zero or value of type determined by types of elements DESCRIPTION The matrix m has to be square, i.e. of dimension 2 with: matmax(m,1) - matmin(m,1) == matmax(m,2) - matmin(m,2). If the elements of m are numbers (real or complex), det(m) returns the value of the determinant of m. If some or all of the elements of m are not numbers, the algorithm used to evaluate det(m) assumes the definitions of *, unary -, binary -, being zero or nonzero, are consistent with commutative ring structure, and if the m is larger than 2 x 2, division by nonzero elements is consistent with integral-domain structure. If m is a 2 x 2 matrix with elements a, b, c, d, where a tests as nonzero, det(m) is evaluated by det(m) = (a * d) - (c * b). If a tests as zero, det(m) = - ((c * b) - (a * d)) is used. If m is 3 * 3 with elements a, b, c, d, e, f, g, h, i, where a and a * e - d * b test as nonzero, det(m) is evaluated by det(m) = ((a * e - d * b) * (a * i - g * c) - (a * h - g * b) * (a * f - d * c))/a. EXAMPLE ; mat A[3,3] = {2, 3, 5, 7, 11, 13, 17, 19, 23} ; c = config("mode", "frac") ; print det(A), det(A^2), det(A^3), det(A^-1) -78 6084 -474552 -1/78 ; obj res {r} ; global md ; define res_test(a) = !ismult(a.r, md) ; define res_sub(a,b) {local obj res v = {(a.r - b.r) % md}; return v;} ; define res_mul(a,b) {local obj res v = {(a.r * b.r) % md}; return v;} ; define res_neg(a) {local obj res v = {(-a.r) % md}; return v;} ; define res(x) {local obj res v = {x % md}; return v;} ; md = 0 ; mat A[2,2] = {res(2), res(3), res(5), res(7)} ; md = 5 ; print det(A) obj res {4} ; md = 6 ; print det(A) obj res {5} Note that if A had been a 3 x 3 or larger matrix, res_div(a,b) for non-zero b would have had to be defined (assuming at least one division is necessary); for consistent results when md is composite, res_div(a,b) should be defined only when b and md are relatively prime; there is no problem when md is prime. LIMITS none LINK LIBRARY VALUE matdet(MATRIX *m) SEE ALSO matdim, matmax, matmin, inverse ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: det,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/det,v $ ## ## Under source code control: 1995/11/28 11:17:47 ## File existed as early as: 1995 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME rcpow - REDC powers SYNOPSIS rcpow(x, k, m) TYPES x integer k nonnegative integer m odd positive integer return integer v, 0 <= v < m. DESCRIPTION Let B be the base calc uses for representing integers internally (B = 2^16 for 32-bit machines, 2^32 for 64-bit machines) and N the number of words (base-B digits) in the representation of m. Then rcpow(x,k,m) returns the value of B^-N * (B^N * x)^k % m, w here the inverse implicit in B^-N is modulo m and the modulus operator % gives the least nonnegative residue. Note that rcpow(x,0,m) = rcin(1,m), rcpow(x,1,m) = x % m; rcpow(x,2,m) = rcsq(x,m). The normal use of rcpow() may be said to be that of finding the encoded value of the k-th power of an integer modulo m: rcin(x^k, m) = rcpow(rcin(x,m), k, m), from which one gets: x^k % m = rcout(rcpow(rcin(x,m), k, m), m). If x^k % m is to be evaluated for the same k and m and several values of x, it may be worth while to first evaluate: a = minv(rcpow(1, k, m), m); and use: x^k % m = a * rcpow(x, k, m) % m. RUNTIME If the value of m in rcpow(x,k,m) is being used for the first time in a REDC function, the information required for the REDC algorithms is calculated and stored for future use, possibly replacing an already stored valued, in a table covering up to 5 (i.e. MAXREDC) values of m. The runtime required for this is about two times that required for multiplying two N-word integers. Two algorithms are available for evaluating rcpow(x,k,m), the one which is usually faster for small N is used when N < config("redc2"); the other is usually faster for larger N. If config("redc2") is set at about 90 and 0 <= x < m, the runtime required for rcpow(x,k,m) is at most about f times the runtime required for ilog2(k) N-word by N-word multiplications, where f increases from about 1.3 for N = 1 to near 4 for N > 90. More runtime may be required if x has to be reduced modulo m. EXAMPLE Using a 64-bit machine with B = 2^32: ; m = 1234567; ; x = 15; ; print rcout(rcpow((rcin(x,m), m - 1, m), m), pmod(x, m-1, m) 783084 783084 LIMITS none LINK LIBRARY void zredcpower(REDC *rp, ZVALUE z1, ZVALUE z2, ZVALUE *res) SEE ALSO rcin, rcout, rcmul, rcsq ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: rcpow,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/rcpow,v $ ## ## Under source code control: 1996/02/25 02:22:21 ## File existed as early as: 1996 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME sin - trigonometric sine SYNOPSIS sin(x [,eps]) TYPES x number (real or complex) eps nonzero real, defaults to epsilon() return number DESCRIPTION Calculate the sine of x to a multiple of eps with error less in absolute value than .75 * eps. EXAMPLE ; print sin(1, 1e-5), sin(1, 1e-10), sin(1, 1e-15), sin(1, 1e-20) .84147 .8414709848 .841470984807896 .84147098480789650665 ; print sin(2 + 3i, 1e-5), sin(2 + 3i, 1e-10) 9.1545-4.16891i 9.1544991469-4.16890696i ; pi = pi(1e-20) ; print sin(pi/6, 1e-10), sin(pi/2, 1e-10), sin(pi, 1e-10) .5 1 0 LIMITS eps > 0 LINK LIBRARY NUMBER *qsin(NUMBER *x, NUMBER *eps) COMPLEX *c_sin(COMPLEX *x, NUMBER *eps) SEE ALSO cos, tan, sec, csc, cot, epsilon ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: sin,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/sin,v $ ## ## Under source code control: 1994/03/19 01:40:28 ## File existed as early as: 1994 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME fopen - open a file SYNOPSIS fopen(filename, mode) TYPES filename string mode string return file DESCRIPTION This function opens the file named filename. A file can be opened for either reading, writing, or appending. The mode is controlled by the mode flag as follows: allow allow file is positioned file(*) mode reading writing truncated at mode ---- ------- ------- --------- --------- ---- r Y N N beginning text rb Y N N beginning binary r+ Y N N beginning text r+b Y N N beginning binary rb+ Y N N beginning binary w N Y Y beginning text wb N Y Y beginning binary w+ Y Y Y beginning text w+b Y Y Y beginning binary wb+ Y Y Y beginning binary a N Y Y end text ab N Y Y end binary a+ Y Y Y end text a+b Y Y Y end binary ab+ Y Y Y end binary (*) NOTE on 'b' / binary/text mode: The 'b' or fopen binary mode has no effect on POSIX / Linux / Un*x-like systems. On those systems a text file is the same as a binary file (as it should be for any modern-day operating system). Adding 'b' to an fopen has no effect and is ignored. Some non-POSIX systems sucn as MS Windoz treat text files and binary files differently. In text mode MS Windoz consider "\r\n" and end-of-line character. On an Apple MAC, the text mode end-of-line character is "\r". Names of files are subject to ~ expansion just like the C or Korn shell. For example, the file name: ~/lib/gleet refers to the file 'gleet' under the directory lib located in your home directory. The file name: ~chongo/was_here refers to the a file 'was_here' under the home directory of the user 'chongo'. If the open is successful, a value of type 'file' will be returned. You can use the 'isfile' function to test the return value to see if the open succeeded. You should assign the return value of fopen to a variable for later use. File values can be copied to more than one variable, and using any of the variables with the same file value will produce the same results. Standard input, standard output and standard error are always opened and cannot be closed. The truth value of an opened file is TRUE. If the open is unsuccessful, the numeric value of errno is returned. You can the strerror() builtin to determine what the errno number means. EXAMPLE ; fd = fopen("/etc/motd", "r") ; print fd "/etc/motd" ; fd FILE 3 "/etc/motd" (reading, pos 0) ; outfile = fopen("~/tmp/output", "w") ; print outfile "~/tmp/output" ; outfile FILE 4 "~/tmp/output" (writing, pos 0) ; badfile = fopen("not_a_file", "r"); ; if (!isfile(badfile)) { ;; printf("error(%d): %s\n", errno(badfile), strerror(badfile)); ;; } error(2): No such file or directory LIMITS none LINK LIBRARY none SEE ALSO errno, fclose, feof, ferror, fflush, fgetc, fgetline, fgets, files, fopen, fprintf, fputc, fputs, fseek, fsize, ftell, isfile, printf, prompt, fpathopen, strerror ## Copyright (C) 1999-2006 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: fopen,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/fopen,v $ ## ## Under source code control: 1994/10/27 03:04:17 ## File existed as early as: 1994 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ Interrupts While a calculation is in progress, you can generate the SIGINT signal, and the calculator will catch it. At appropriate points within a calculation, the calculator will check that the signal has been given, and will abort the calculation cleanly. If the calculator is in the middle of a large calculation, it might be a while before the interrupt has an effect. You can generate the SIGINT signal multiple times if necessary, and each time the calculator will abort the calculation at a more risky place within the calculation. Each new interrupt prints a message of the form: [Abort level n] where n ranges from 1 to 3. For n equal to 1, the calculator will abort calculations at the next statement boundary specified by an ABORT opcode as described below. For n equal to 2, the calculator will abort calculations at the next opcode boundary. For n equal to 3, the calculator will abort calculations at the next attempt to allocate memory for the result of an integer arithmetic operation; this level may be appropriate for stopping a builtin operation like inversion of a large matrix. If a final interrupt is given when n is 3, the calculator will immediately abort the current calculation and longjmp back to the top level command level. Doing this may result in corrupted data structures and unpredictable future behavior, and so should only be done as a last resort. You are advised to quit the calculator after this has been done. ABORT opcodes If config("trace") & 2 is zero, ABORT opcodes are introduced at various places in the opcodes for evaluation of command lines and functions defined by "define ... { ... }" commands. In the following, config("trace") has been set equal to 8 so that opcodes are displayed when a function is defined. The function f(x) evaluates x + (x - 1) + (x - 2) + ... until a zero term is encountered. If f() is called with a negative or fractional x, the calculation is never completed and to stop it, an interruption (on many systems, by ctrl-C) will be necessary. ; config("trace", 8), ; define f(x) {local s; while (x) {s += x--} return s} 0: DEBUG line 2 2: PARAMADDR x 4: JUMPZ 19 6: DEBUG line 2 8: LOCALADDR s 10: DUPLICATE 11: PARAMADDR x 13: POSTDEC 14: POP 15: ADD 16: ASSIGNPOP 17: JUMP 2 19: DEBUG line 2 21: LOCALADDR s 23: RETURN f(x) defined (The line number following DEBUG refers to the line in the file from which the definition is read.) If an attempt is made to evaluate f(-1), the effect of the DEBUG at opcode 6 ensures that a single SIGINT will stop the calculation at a start of {s += x--} loop. In interactive mode, with ^C indicating input of ctrl-C, the displayed output is as in: ; f(-1) ^C [Abort level 1] "f": line 2: Calculation aborted at statement boundary The DEBUG opcodes are disabled by nonzero config("trace") & 2. Changing config("trace") to achieve this, and defining g(x) with the same definition as for f(x) gives: ; define g(x) {local s; while (x) {s += x--} return s} 0: PARAMADDR x 2: JUMPZ 15 4: LOCALADDR s 6: DUPLICATE 7: PARAMADDR x 9: POSTDEC 10: POP 11: ADD 12: ASSIGNPOP 13: JUMP 0 15: LOCALADDR s 17: RETURN g(x) defined If g(-1) is called, two interrupts are necessary, as in: ; g(-1) ^C [Abort level 1] ^C [Abort level 2] "g": Calculation aborted in opcode ## Copyright (C) 1999-2006 David I. Bell, Landon Curt Noll and Ernest Bowen ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: interrupt,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/interrupt,v $ ## ## Under source code control: 1991/07/21 04:37:21 ## File existed as early as: 1991 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ calc shell script examples -------------------------- These calc shell scripts are provided because they serve as examples of how use the calc language, and/or because the authors thought them to be useful! Please note that calc shell scripts must start with the line: #!/usr/bin/calc -q -f The above line MUST start in column 1 of the first line. The first line must also end in -f. The -q is optional, but is recommended to disable the processing of calc startup scripts. Also please note that single # shell line comments are not supported in calc. Comments must be /* c-like comment */ or start with a double ## symbol. This is the correct way to form a calc shell script: #!/usr/bin/calc -q -f /* a correct comment */ ## another correct comment ### two or more together is also a comment /* * another correct comment */ print "2+2 =", 2+2; ## yet another comment The first argument after the path to calc executable must be an -S. The next arguments are optional. The -q is often recommended because it will disable the processing of the startup scripts. For more informaton about calc command lines, see "help usage". This next example WRONG: #!/usr/bin/calc -q # This is not a calc calc comment because it has only a single # # You must to start comments with ## or /* # is is also wrong because the first line does not end in -f print "This example has invalid comments" ##### If you write something that you think is useful, please send it to: calc-contrib at asthe dot com [[ NOTE: Replace 'at' with @, 'dot' is with . and remove the spaces ]] [[ NOTE: The EMail address uses 'asthe' and the web site URL uses 'isthe' ]] For more info, see: help script help cscript =-= 4dsphere Determine if 6 points lie on the surface of a 4-dimensional sphere in R^4. 4dsphere x0 y0 z0 w0 x1 y1 z1 w1 ... x5 y5 z5 w5 x0 y0 z0 w0 point 0 in R^4 x1 y1 z1 w1 point 1 in R^4 ... ... x5 y5 z5 w5 point 5 in R^4 fproduct filename term ... Write the big Endian product of terms to a file. Use - for stdout. mersenne exp Print the value of 2^exp-1. piforever Print the value of pi forever, or as long as you cpu / memory allows. plus arg ... Print the sum of 1 or more arguments. powerterm [base_limit] value Print the value as a sum (or difference) of powers of integers up to and including powers <= base_limit. By default, base_limit is 10000. simple A trivial example of a calc shell script. ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: README.src,v 30.1 2007/03/16 11:12:11 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/cscript/RCS/README.src,v $ ## ## Under source code control: 1999/12/17 10:23:40 ## File existed as early as: 1999 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME runtime - CPU time used by the current process in both user and kernel modes SYNOPSIS runtime() TYPES return nonnegative real DESCRIPTION In POSIX based systems, this function will return the CPU seconds used by the current process in both user and kernel mode. Time spent in the kernel executing system calls and time spend executing user code (such as performing computation on behalf of calc) are both included. On non-POSIX based systems, this function will always return 0. In particular, most MS windows based systems do not have the required POSIX system call and so this function will always return 0. EXAMPLE The result for this example will depend on the speed of the CPU and precision of the operating CPU time accounting sub-system: ; t = runtime(); ; x = ptest(2^4253-1); ; runtime() - t; 1.288804 LIMITS On non-POSIX based systems, this function always returns 0. LINK LIBRARY none SEE ALSO config, ctime, systime, time, usertime ## Copyright (C) 1999-2006 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: runtime,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/runtime,v $ ## ## Under source code control: 1996/03/12 23:10:01 ## File existed as early as: 1996 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME sha1 - Secure Hash Algorithm (SHS-1 FIPS Pub 180-1) SYNOPSIS sha1([arg1 [, val ...]]) TYPES arg1 any val any return HASH or number DESCRIPTION The sha1() builtin implements the old Secure Hash Algorithm (SHA). The SHA is sometimes referenced as SHS. The SHA is a 160 bit hash. With no args, sha1() returns the default initial SHA-1 HASH state. If arg1 is a HASH state and no other val args are given, then the HASH state is finalized and the numeric value of the hash is given. If arg1 is a HASH state and one or more val args are given, then the val args are used to modify the arg1 HASH state. The new arg1 HASH state is returned. If arg1 is not a a HASH state, then the initial HASH is used and modifed by arg1 and any val args supplied. The return value is the new HASH state. The following table gives a summary of actions and return values. Here, assume that 'h' is a HASH state: sha1() HASH returns initial HASH state sha1(h) number h is put into final form and the numeric value of the hash state sha1(x) HASH modify the initial state by hashing 'x' sha1(sha1(), x) HASH the same as sha1(x) sha1(x, y) HASH the same as sha1(sha1(x), y) sha1(h, x, y) HASH modify state 'h' by 'x' and then 'y' sha1(sha1(h,x,y)) number numeric value of the above call EXAMPLE ; base(16) 0xa ; sha1() sha1 hash state ; sha1(sha1()) 0xda39a3ee5e6b4b0d3255bfef95601890afd80709 ; sha1("x", "y", "z") == sha1("xyz") 1 ; sha1("x", "y", "z") == sha1("xy") 0 ; sha1(sha1("this is", 7^19-8, "a composit", 3i+4.5, "hash")) 0xc3e1b562bf45b3bcfc055ac65b5b39cdeb6a6c55 ; x = sha1(list(1,2,3), "curds and whey", 2^21701-1, pi()) ; x sha1 hash state ; sha1(x) 0x988d2de4584b7536aa9a50a5749707a37affa1b5 ; y = sha1() ; y = sha1(y, list(1,2,3), "curds and whey") ; y = sha1(y, 2^21701-1) ; y = sha1(y, pi()) ; y sha1 hash state ; sha1(y) 0x988d2de4584b7536aa9a50a5749707a37affa1b5 LIMITS none LINK LIBRARY HASH* hash_init(int, HASH*); void hash_free(HASH*); HASH* hash_copy(HASH*); int hash_cmp(HASH*, HASH*); void hash_print(HASH*); ZVALUE hash_final(HASH*); HASH* hash_long(int, long, HASH*); HASH* hash_zvalue(int, ZVALUE, HASH*); HASH* hash_number(int, void*, HASH*); HASH* hash_complex(int, void*, HASH*); HASH* hash_str(int, char*, HASH*); HASH* hash_usb8(int, USB8*, int, HASH*); HASH* hash_value(int, void*, HASH*); SEE ALSO ishash, hash ## Copyright (C) 1999-20007 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.2 $ ## @(#) $Id: sha1,v 30.2 2007/07/05 17:37:41 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/sha1,v $ ## ## Under source code control: 1997/03/23 00:01:18 ## File existed as early as: 1997 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME base - set default output base SYNOPSIS base([mode]) TYPES mode real return real DESCRIPTION The base function allows one to specify how numbers should be printed. The base function provides a numeric shorthand to the config("mode") interface. With no args, base() will return the current mode. With 1 arg, base(val) will set the mode according to the arg and return the previous mode. The following convention is used to declare modes: base equivalent config("mode")'s 2 "binary" base 2 fractions "bin" 8 "octal" base 8 fractions "oct" 10 "real" base 10 floating point "float" "default" -10 "integer" base 10 integers "int" 16 "hexadecimal" base 16 fractions "hex" 1/3 "fraction" base 10 fractions "frac" 1e20 "scientific" base 10 scientific notation "sci" "exp" For convenience, any non-integer value is assumed to mean base 10 fractions and any integer >= 2^64 is assumed to mean base 10 scientific notation. These base() calls have the same meaning as config("mode", "fraction"): base(1/3) base(0.1415) base(16/37) These base() calls have the same meaning as config("mode", "scientific"): base(1e20) base(2^64) base(2^8191-1) However the base() function will only return one of the base values listed in the table above. EXAMPLE ; base() 10 ; base(8) 012 ; print 10 012 LIMITS none LINK LIBRARY int math_setmode(int newmode) NOTE: newmode must be one of MODE_DEFAULT, MODE_FRAC, MODE_INT, MODE_REAL, MODE_EXP, MODE_HEX, MODE_OCTAL, MODE_BINARY SEE ALSO base2, config, str ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: base,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/base,v $ ## ## Under source code control: 1994/09/30 00:09:39 ## File existed as early as: 1994 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME ln - logarithm function SYNOPSIS ln(x [,eps]) TYPES x nonzero real or complex eps nonzero real, defaults to epsilon() return real or complex DESCRIPTION Approximate the natural logarithm function of x by a multiple of epsilon, the error having absolute value less than 0.75 * eps. If n is a positive integer, ln(x, 10^-n) will usually be correct to the n-th decimal place. EXAMPLE ; print ln(10, 1e-5), ln(10, 1e-10), ln(10, 1e-15), ln(10, 1e-20) 2.30259 2.302585093 2.302585092994046 2.30258509299404568402 ; print ln(2+3i, 1e-5), ln(2+3i, 1e-10) 1.28247+.98279i 1.2824746787+.9827937232i LIMITS x != 0 eps > 0 LINK LIBRARY NUMBER *qln(NUMBER *x, NUMBER *eps) COMPLEX *c_ln(COMPLEX *x, NUMBER *eps) SEE ALSO exp, acosh, asinh, atanh, log ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: ln,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/ln,v $ ## ## Under source code control: 1995/10/11 04:41:26 ## File existed as early as: 1995 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME cmdbuf - print the command buffer SYNOPSIS cmdbuf() TYPES return str DESCRIPTION This function returns the command string that was formed by calc based on its command line arguments. If calc was invoked without arguments, this function will return an empty string. EXAMPLE % calc "print cmdbuf(); a = 3; print a^2;" print cmdbuf(); a = 3; print a^2; 9 % LIMITS none LINK LIBRARY none SEE ALSO argv, system ## Copyright (C) 1999-2006 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: cmdbuf,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/cmdbuf,v $ ## ## Under source code control: 1995/07/09 04:05:58 ## File existed as early as: 1995 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME trunc - truncate a value to a number of decimal places SYNOPSIS trunc(x [,j]) TYPES x real j int return real DESCRIPTION Truncate x to j decimal places. If j is omitted, 0 places is assumed. Specifying zero places makes the result identical to int(). Truncation of a non-integer prodcues values nearer to zero. EXAMPLE ; print trunc(pi()), trunc(pi(), 5) 3 3.14159 ; print trunc(3.333), trunc(3.789), trunc(3.333, 2), trunc(3.789, 2) 3 3 3.33 3.78 ; print trunc(-3.333), trunc(-3.789), trunc(-3.333, 2), trunc(-3.789, 2) -3 -3 -3.33 -3.78 LIMITS 0 <= j < 2^31 LINK LIBRARY NUMBER *qtrunc(NUMBER *x, *j) SEE ALSO bround, btrunc, int, round ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: trunc,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/trunc,v $ ## ## Under source code control: 1994/09/30 00:52:38 ## File existed as early as: 1994 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME fgetfield - read the next word from a file SYNOPSIS fgetfield(fs) TYPES fs file stream open for reading return string or null DESCRIPTION Starting at the current file position, any whitespace characters are skipped. If the reading reaches end-of-file, the null value is returned. Otherwise the function returns the empty string "" if the first non-white character is '\0', and in other cases, the string formed by the non-white-space characters read until '\0' or a white-space character or te end of the file is reached. In the cases where the reading is stopped by '\0' or white-space character, the file position will be that immediately after that character. EXAMPLE ; f = fopen("/tmp/junk", "w") ; fputs(f, " Alpha Beta \n") ; freopen(f, "r") ; fgetfield(f) "Alpha" ; fgetfield(f) "Beta" ; fgetfield(f) ; freopen(f, "w") ; fputstr(f, " Alpha ", "Beta") ; freopen(f, "r") ; fgetfield(f) "Alpha" ; fgetfield(f) "" ; fgetfield(f) "Beta" LIMITS none LINK LIBRARY none SEE ALSO fgetstr, fputstr, fgets, fputs, fopen, files, fprintf ## Copyright (C) 1999-2006 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: fgetfield,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/fgetfield,v $ ## ## Under source code control: 1996/04/30 03:05:17 ## File existed as early as: 1996 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME fgetc - read the next char from a file SYNOPSIS fgetc(fd) TYPES fd file return str or nil DESCRIPTION This function reads the next character from the open file associated with fd. If there is a next character, this function returns a 1 character string containing that character. In the case of EOF or error, nil is returned. EXAMPLE ; fd = fopen("/tmp/newfile", "w") ; fputs(fd, "chongo was here\n") ; fd2 = fopen("/tmp/newfile", "r") ; fgetc(fd2) "c" LIMITS fd must be associated with an open file LINK LIBRARY none SEE ALSO errno, fclose, feof, ferror, fflush, fgetc, fgetline, fgets, files, fopen, fprintf, fputc, fputs, fseek, fsize, ftell, isfile, printf, prompt ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: fgetc,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/fgetc,v $ ## ## Under source code control: 1995/03/04 11:33:19 ## File existed as early as: 1995 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME isqrt - integer part of square root SYNOPSIS isqrt(x) TYPES x nonnegative real return nonnegative real DESCRIPTION Return the greatest integer n for which n^2 <= x. EXAMPLE ; print isqrt(8.5), isqrt(200), isqrt(2e6), isqrt(2e56) 2 14 1414 14142135623730950488016887242 LIMITS x > 0 LINK LIBRARY NUMBER *qisqrt(NUMBER *x) SEE ALSO sqrt, iroot ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: isqrt,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/isqrt,v $ ## ## Under source code control: 1995/10/25 04:03:45 ## File existed as early as: 1995 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME = SYNOPSIS a = b a = {e_1, e_2, ...[ { ... } ] } TYPES a lvalue, current value a structure in { } case b expression e_0, e_1, ... expressions, blanks, or initializer lists return lvalue (a) DESCRIPTION Here an lvalue is either a simple variable specified by an identifier, or an element of an existing structure specified by one or more qualifiers following an identifier. An initializer list is a comma-separated list enclosed in braces as in {e_0, e_1, ... } where each e_i is an expression, blank or initializer list. a = b evaluates b, assigns its value to a, and returns a. a = {e_0, e_1, ... } where the e_i are expressions or blanks, requires the current value of a to be a matrix, list or object with at least as many elements as listed e_i. Each non-blank e_i is evaluated and its value is assigned to a[[i]]; elements a[[i]] corresponding to blank e_i are unchanged. If, in a = {e_0, e_1, ...}, e_i is an initializer list, as in {e_i_0, e_1_1, ...}, the corresponding a[[i]] is to be a matrix, list or object with at least as many elements as listed e_i_j. Depending on whether e_i_j is an expression, blank, or initializer list, one, no, or possibly more than one assignment, is made to a[[i]][[j]] or, if relevant and possible, its elements. In simple assignments, = associates from right to left so that, for example, a = b = c has the effect of a = (b = c) and results in assigning the value of c to both a and b. The expression (a = b) = c is acceptable, but has the effect of a = b; a = c; in which the first assignment is superseded by the second. In initializations, = { ...} associates from left to right so that, for example, a = {e_0, ... } = {v_0, ...} first assigns e_0, ... to the elements of a, and then assigns v_0, ... to the result. If there are side effects in the evaluations involved in executing a = b, it should be noted that the order of evaluations is: first the address for a, then the value of b, and finally the assignment. For example if A is a matrix and i = 0, then the assignment in A[i++] = A[i] is that of A[0] = A[1]. If, in execution of a = b, a is changed by the evaluation of b, the value of b may be stored in an unintended or inaccessible location. For example, mat A[2]= {1,2}; A[0] = (A = 3); results in the value 3 being stored not only as the new value for A but also at the now unnamed location earlier used for A[0]. EXAMPLE ; b = 3+1 ; a = b ; print a, b 4 4 ; obj point {x,y} ; mat A[3] = {1, list(2,3), obj point = {4,5}} ; A[1][[0]] = 6; A[2].x = 7 ; print A[1] list (2 elements, 2 nonzero): [[0]] = 6 [[1]] = 3 ; print A[2] obj point {7, 5} ; A = {A[2], , {9,10}} ; print A[0] obj point {7, 5} ; print A[2] obj point {9, 10} ; A = {, {2}} print A[1] list (2 elements, 2 nonzero): [[0]] = 2 [[1]] = 3 LIMITS none LINK LIBRARY none SEE ALSO swap, quomod ## Copyright (C) 1999 Landon Curt Noll ## ## Calc is open software; you can redistribute it and/or modify it under ## the terms of the version 2.1 of the GNU Lesser General Public License ## as published by the Free Software Foundation. ## ## Calc is distributed in the hope that it will be useful, but WITHOUT ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY ## or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General ## Public License for more details. ## ## A copy of version 2.1 of the GNU Lesser General Public License is ## distributed with calc under the filename COPYING-LGPL. You should have ## received a copy with calc; if not, write to Free Software Foundation, Inc. ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ## ## @(#) $Revision: 30.1 $ ## @(#) $Id: assign,v 30.1 2007/03/16 11:10:42 chongo Exp $ ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/assign,v $ ## ## Under source code control: 1995/05/11 21:03:23 ## File existed as early as: 1995 ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ NAME rand - subtractive 100 shuffle pseudo-random number generator SYNOPSIS rand([[min, ] beyond]) TYPES min integer beyond integer return integer DESCRIPTION Generate a pseudo-random number using an subtractive 100 shuffle generator. We return a pseudo-random number over the half closed interval: [min,beyond) ((min <= return < beyond)) By default, min is 0 and beyond is 2^64. The shuffle method is fast and serves as a fairly good standard pseudo-random generator. If you need a fast generator and do not need a cryptographically strong one, this generator is likely to do the job. Casual direct use of the shuffle generator may be acceptable. For a much higher quality cryptographically strong (but slower) generator use the Blum-Blum-Shub generator (see the random help page). Other arg forms: rand() Same as rand(0, 2^64) rand(beyond) Same as rand(0, beyond) The rand generator generates the highest order bit first. Thus: rand(256) will produce the save value as: (rand(8) << 5) + rand(32) when seeded with the same seed. The rand generator has two distinct parts, the subtractive 100 method and the shuffle method. The subtractive 100 method is described in: "The Art of Computer Programming - Seminumerical Algorithms", Vol 2, 3rd edition (1998), Section 3.6, page 186, formula (2). The "use only the first 100 our of every 1009" is described in Knuth's "The Art of Computer Programming - Seminumerical Algorithms", Vol 2, 3rd edition (1998), Section 3.6, page 188". The period and other properties of the subtractive 100 method make it very useful to 'seed' other generators. The shuffle method is feed values by the subtractive 100 method. The shuffle method is described in: "The Art of Computer Programming - Seminumerical Algorithms", Vol 2, 3rd edition (1998), Section 3.2.2, page 34, Algorithm B. The rand generator has a good period, and is fast. It is reasonable as generators go, though there are better ones available. The shuffle method has a very good period, and is fast. It is fairly good as generators go, particularly when it is feed reasonably random numbers. Because of this, we use feed values from the subtractive 100 method into the shuffle method. The rand generator uses two internal tables: additive table - 100 entries of 64 bits used by the subtractive 100 method shuffle table - 256 entries of 64 bits used by the shuffle method feed by the subtractive 100 method from the subtractive table The goals of this generator are: * all magic numbers are explained I (Landon Curt Noll) distrust systems with constants (magic numbers) and tables that have no justification (e.g., DES). I believe that I have done my best to justify all of the magic numbers used. * full documentation You have this source file, plus background publications, what more could you ask? * large selection of seeds Seeds are not limited to a small number of bits. A seed may be of any size. Most of the magic constants used by this generator ultimately are based on the Rand book of random numbers. The Rand book contains 10^6 decimal digits, generated by a physical process. This book, produced by the Rand corporation in the 1950's is considered a standard against which other generators may be measured. The Rand book of numbers was groups into groups of 20 digits. The first 100 groups < 2^64 were used to initialize the default additive table. The size of 20 digits was used because 2^64 is 20 digits long. The restriction of < 2^64 was used to prevent modulus biasing. The shuffle table size is longer than the 100 entries recommended by Knuth. We use a power of 2 shuffle table length so that the shuffle process can select a table entry from a new subtractive 100 value by extracting its low order bits. The value 256 is convenient in that it is the size of a byte which allows for easy extraction. We use the upper byte of the subtractive 100 value to select the shuffle table entry because it allows all of 64 bits to play a part in the entry selection. If we were to select a lower 8 bits in the 64 bit value, carries that propagate above our 8 bits would not impact the subtractive 100 generator output. It is 'nice' when a seed of "n" produces a 'significantly different' sequence than a seed of "n+1". Generators, by convention, assign special significance to the seed of '0'. It is an unfortunate that people often pick small seed values, particularly when large seed are of significance to the generators found in this file. An internal process called randreseed64 will effectively eliminate the human perceptions that are noted above. It should be noted that the purpose of randreseed64 is to scramble a seed ONLY. We do not care if these generators produce good random numbers. We only want to help eliminate the human factors & perceptions noted above. The randreseed64 process scrambles all 64 bit chunks of a seed, by mapping [0,2^64) into [0,2^64). This map is one-to-one and onto. Mapping is performed using a linear congruence generator of the form: X1 <-- (a*X0 + c) % m with the exception that: 0 ==> 0 (so that srand(0) acts as default) while maintaining a 1-to-1 and onto map. The randreseed64 constants 'a' and 'c' based on the linear congruential generators found in: "The Art of Computer Programming - Seminumerical Algorithms" by Knuth, Vol 2, 2nd edition (1981), Section 3.6, pages 170-171. We will select the randreseed64 multiplier 'a' such that: a mod 8 == 5 (based on note iii) 0.01*m < a < 0.99*m (based on note iv) 0.01*2^64 < a < 0.99*2^64 a is prime (help keep the generators independent) The choice of the randreseed64 adder 'c' is considered immaterial according (based in note v). Knuth suggests 'c==1' or 'c==a'. We elect to select 'c' using the same process as we used to select 'a'. The choice is 'immaterial' after all, and as long as: gcd(c, m) == 1 (based on note v) gcd(c, 2^64) == 1 gcd(a, c) == 1 (adders & multipliers will be more independent) The values 'a' and 'c for randreseed64 are taken from the Rand book of numbers. Because m=2^64 is 20 decimal digits long, we will search the Rand book of numbers 20 at a time. We will skip any of the 100 values that were used to initialize the subtractive 100 generators. The values obtained from the Rand book are: a = 6316878969928993981 c = 1363042948800878693 As we stated before, we must map 0 ==> 0 so that srand(0) does the default thing. The randreseed64 would normally map as follows: 0 ==> 1363042948800878693 (0 ==> c) To overcome this, and preserve the 1-to-1 and onto map, we force: 0 ==> 0 10239951819489363767 ==> 1363042948800878693 One might object to the complexity of the seed scramble/mapping via the randreseed64 process. But Calling srand(0) with the randreseed64 process would be the same as calling srand(10239951819489363767) without it. No extra security is gained or reduced by using the randreseed64 process. The meaning of seeds are exchanged, but not lost or favored (used by more than one input seed). The randreseed64 process does not reduce the security of the rand generator. Every seed is converted into a different unique seed. No seed is ignored or favored. The truly paranoid might suggest that my claims in the MAGIC NUMBERS section are a lie intended to entrap people. Well they are not, but if you that paranoid why would you use a non-cryprographically strong pseudo-random number generator in the first place? You would be better off using the random() builtin function. The two constants that were picked from the Rand Book of Random Numbers The random numbers from the Rand Book of Random Numbers can be verified by anyone who obtains the book. As these numbers were created before I (Landon Curt Noll) was born (you can look up my birth record if you want), I claim to have no possible influence on their generation. There is a very slight chance that the electronic copy of the Rand Book of Random Numbers that I was given access to differs from the printed text. I am willing to provide access to this electronic copy should anyone wants to compare it to the printed text. When using the s100 generator, one may select your own 100 subtractive values by calling: srand(mat100) and avoid using my magic numbers. The randreseed64 process is NOT applied to the matrix values. Of course, you must pick good subtractive 100 values yourself! EXAMPLE ; print srand(0), rand(), rand(), rand() RAND state 2298441576805697181 3498508396312845423 5031615567549397476 ; print rand(123), rand(123), rand(123), rand(123), rand(123), rand(123) 106 59 99 99 25 88 ; print rand(2,12), rand