This is Info file calc.info, produced by Makeinfo-1.55 from the input file calc.texinfo. This file documents Calc, the GNU Emacs calculator. Copyright (C) 1990, 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English. File: calc.info, Node: Predicates, Next: Computational Lisp Functions, Prev: Stack Lisp Functions, Up: Internals Predicates .......... The functions described here are predicates, that is, they return a true/false value where `nil' means false and anything else means true. These predicates are expanded by `defmath', for example, from `zerop' to `math-zerop'. In many cases they correspond to native Lisp functions by the same name, but are extended to cover the full range of Calc data types. - Function: zerop X Returns true if X is numerically zero, in any of the Calc data types. (Note that for some types, such as error forms and intervals, it never makes sense to return true.) In `defmath', the expression `(= x 0)' will automatically be converted to `(math-zerop x)', and `(/= x 0)' will be converted to `(not (math-zerop x))'. - Function: negp X Returns true if X is negative. This accepts negative real numbers of various types, negative HMS and date forms, and intervals in which all included values are negative. In `defmath', the expression `(< x 0)' will automatically be converted to `(math-negp x)', and `(>= x 0)' will be converted to `(not (math-negp x))'. - Function: posp X Returns true if X is positive (and non-zero). For complex numbers, none of these three predicates will return true. - Function: looks-negp X Returns true if X is "negative-looking." This returns true if X is a negative number, or a formula with a leading minus sign such as `-a/b'. In other words, this is an object which can be made simpler by calling `(- X)'. - Function: integerp X Returns true if X is an integer of any size. - Function: fixnump X Returns true if X is a native Lisp integer. - Function: natnump X Returns true if X is a nonnegative integer of any size. - Function: fixnatnump X Returns true if X is a nonnegative Lisp integer. - Function: num-integerp X Returns true if X is numerically an integer, i.e., either a true integer or a float with no significant digits to the right of the decimal point. - Function: messy-integerp X Returns true if X is numerically, but not literally, an integer. A value is `num-integerp' if it is `integerp' or `messy-integerp' (but it is never both at once). - Function: num-natnump X Returns true if X is numerically a nonnegative integer. - Function: evenp X Returns true if X is an even integer. - Function: looks-evenp X Returns true if X is an even integer, or a formula with a leading multiplicative coefficient which is an even integer. - Function: oddp X Returns true if X is an odd integer. - Function: ratp X Returns true if X is a rational number, i.e., an integer or a fraction. - Function: realp X Returns true if X is a real number, i.e., an integer, fraction, or floating-point number. - Function: anglep X Returns true if X is a real number or HMS form. - Function: floatp X Returns true if X is a float, or a complex number, error form, interval, date form, or modulo form in which at least one component is a float. - Function: complexp X Returns true if X is a rectangular or polar complex number (but not a real number). - Function: rect-complexp X Returns true if X is a rectangular complex number. - Function: polar-complexp X Returns true if X is a polar complex number. - Function: numberp X Returns true if X is a real number or a complex number. - Function: scalarp X Returns true if X is a real or complex number or an HMS form. - Function: vectorp X Returns true if X is a vector (this simply checks if its argument is a list whose first element is the symbol `vec'). - Function: numvecp X Returns true if X is a number or vector. - Function: matrixp X Returns true if X is a matrix, i.e., a vector of one or more vectors, all of the same size. - Function: square-matrixp X Returns true if X is a square matrix. - Function: objectp X Returns true if X is any numeric Calc object, including real and complex numbers, HMS forms, date forms, error forms, intervals, and modulo forms. (Note that error forms and intervals may include formulas as their components; see `constp' below.) - Function: objvecp X Returns true if X is an object or a vector. This also accepts incomplete objects, but it rejects variables and formulas (except as mentioned above for `objectp'). - Function: primp X Returns true if X is a "primitive" or "atomic" Calc object, i.e., one whose components cannot be regarded as sub-formulas. This includes variables, and all `objectp' types except error forms and intervals. - Function: constp X Returns true if X is constant, i.e., a real or complex number, HMS form, date form, or error form, interval, or vector all of whose components are `constp'. - Function: lessp X Y Returns true if X is numerically less than Y. Returns false if X is greater than or equal to Y, or if the order is undefined or cannot be determined. Generally speaking, this works by checking whether `X - Y' is `negp'. In `defmath', the expression `(< x y)' will automatically be converted to `(lessp x y)'; expressions involving `>', `<=', and `>=' are similarly converted in terms of `lessp'. - Function: beforep X Y Returns true if X comes before Y in a canonical ordering of Calc objects. If X and Y are both real numbers, this will be the same as `lessp'. But whereas `lessp' considers other types of objects to be unordered, `beforep' puts any two objects into a definite, consistent order. The `beforep' function is used by the `V S' vector-sorting command, and also by `a s' to put the terms of a product into canonical order: This allows `x y + y x' to be simplified easily to `2 x y'. - Function: equal X Y This is the standard Lisp `equal' predicate; it returns true if X and Y are structurally identical. This is the usual way to compare numbers for equality, but note that `equal' will treat 0 and 0.0 as different. - Function: math-equal X Y Returns true if X and Y are numerically equal, either because they are `equal', or because their difference is `zerop'. In `defmath', the expression `(= x y)' will automatically be converted to `(math-equal x y)'. - Function: equal-int X N Returns true if X and N are numerically equal, where N is a fixnum which is not a multiple of 10. This will automatically be used by `defmath' in place of the more general `math-equal' whenever possible. - Function: nearly-equal X Y Returns true if X and Y, as floating-point numbers, are equal except possibly in the last decimal place. For example, 314.159 and 314.166 are considered nearly equal if the current precision is 6 (since they differ by 7 units), but not if the current precision is 7 (since they differ by 70 units). Most functions which use series expansions use `with-extra-prec' to evaluate the series with 2 extra digits of precision, then use `nearly-equal' to decide when the series has converged; this guards against cumulative error in the series evaluation without doing extra work which would be lost when the result is rounded back down to the current precision. In `defmath', this can be written `(~= X Y)'. The X and Y can be numbers of any kind, including complex. - Function: nearly-zerop X Y Returns true if X is nearly zero, compared to Y. This checks whether X plus Y would by be `nearly-equal' to Y itself, to within the current precision, in other words, if adding X to Y would have a negligible effect on Y due to roundoff error. X may be a real or complex number, but Y must be real. - Function: is-true X Return true if the formula X represents a true value in Calc, not Lisp, terms. It tests if X is a non-zero number or a provably non-zero formula. - Function: reject-arg VAL PRED Abort the current function evaluation due to unacceptable argument values. This calls `(calc-record-why PRED VAL)', then signals a Lisp error which `normalize' will trap. The net effect is that the function call which led here will be left in symbolic form. - Function: inexact-value If Symbolic Mode is enabled, this will signal an error that causes `normalize' to leave the formula in symbolic form, with the message "Inexact result." (This function has no effect when not in Symbolic Mode.) Note that if your function calls `(sin 5)' in Symbolic Mode, the `sin' function will call `inexact-value', which will cause your function to be left unsimplified. You may instead wish to call `(normalize (list 'calcFunc-sin 5))', which in Symbolic Mode will return the formula `sin(5)' to your function. - Function: overflow This signals an error that will be reported as a floating-point overflow. - Function: underflow This signals a floating-point underflow. File: calc.info, Node: Computational Lisp Functions, Next: Vector Lisp Functions, Prev: Predicates, Up: Internals Computational Functions ....................... The functions described here do the actual computational work of the Calculator. In addition to these, note that any function described in the main body of this manual may be called from Lisp; for example, if the documentation refers to the `calc-sqrt' [`sqrt'] command, this means `calc-sqrt' is an interactive stack-based square-root command and `sqrt' (which `defmath' expands to `calcFunc-sqrt') is the actual Lisp function for taking square roots. The functions `math-add', `math-sub', `math-mul', `math-div', `math-mod', and `math-neg' are not included in this list, since `defmath' allows you to write native Lisp `+', `-', `*', `/', `%', and unary `-', respectively, instead. - Function: normalize VAL (Full form: `math-normalize'.) Reduce the value VAL to standard form. For example, if VAL is a fixnum, it will be converted to a bignum if it is too large, and if VAL is a bignum it will be normalized by clipping off trailing (i.e., most-significant) zero digits and converting to a fixnum if it is small. All the various data types are similarly converted to their standard forms. Variables are left alone, but function calls are actually evaluated in formulas. For example, normalizing `(+ 2 (calcFunc-abs -4))' will return 6. If a function call fails, because the function is void or has the wrong number of parameters, or because it returns `nil' or calls `reject-arg' or `inexact-result', `normalize' returns the formula still in symbolic form. If the current Simplification Mode is "none" or "numeric arguments only," `normalize' will act appropriately. However, the more powerful simplification modes (like algebraic simplification) are not handled by `normalize'. They are handled by `calc-normalize', which calls `normalize' and possibly some other routines, such as `simplify' or `simplify-units'. Programs generally will never call `calc-normalize' except when popping or pushing values on the stack. - Function: evaluate-expr EXPR Replace all variables in EXPR that have values with their values, then use `normalize' to simplify the result. This is what happens when you press the `=' key interactively. - Macro: with-extra-prec N BODY Evaluate the Lisp forms in BODY with precision increased by N digits. This is a macro which expands to (math-normalize (let ((calc-internal-prec (+ calc-internal-prec N))) BODY)) The surrounding call to `math-normalize' causes a floating-point result to be rounded down to the original precision afterwards. This is important because some arithmetic operations assume a number's mantissa contains no more digits than the current precision allows. - Function: make-frac N D Build a fraction `N:D'. This is equivalent to calling `(normalize (list 'frac N D))', but more efficient. - Function: make-float MANT EXP Build a floating-point value out of MANT and EXP, both of which are arbitrary integers. This function will return a properly normalized float value, or signal an overflow or underflow if EXP is out of range. - Function: make-sdev X SIGMA Build an error form out of X and the absolute value of SIGMA. If SIGMA is zero, the result is the number X directly. If SIGMA is negative or complex, its absolute value is used. If X or SIGMA is not a valid type of object for use in error forms, this calls `reject-arg'. - Function: make-intv MASK LO HI Build an interval form out of MASK (which is assumed to be an integer from 0 to 3), and the limits LO and HI. If LO is greater than HI, an empty interval form is returned. This calls `reject-arg' if LO or HI is unsuitable. - Function: sort-intv MASK LO HI Build an interval form, similar to `make-intv', except that if LO is less than HI they are simply exchanged, and the bits of MASK are swapped accordingly. - Function: make-mod N M Build a modulo form out of N and the modulus M. Since modulo forms do not allow formulas as their components, if N or M is not a real number or HMS form the result will be a formula which is a call to `makemod', the algebraic version of this function. - Function: float X Convert X to floating-point form. Integers and fractions are converted to numerically equivalent floats; components of complex numbers, vectors, HMS forms, date forms, error forms, intervals, and modulo forms are recursively floated. If the argument is a variable or formula, this calls `reject-arg'. - Function: compare X Y Compare the numbers X and Y, and return -1 if `(lessp X Y)', 1 if `(lessp Y X)', 0 if `(math-equal X Y)', or 2 if the order is undefined or cannot be determined. - Function: numdigs N Return the number of digits of integer N, effectively `ceil(log10(N))', but much more efficient. Zero is considered to have zero digits. - Function: scale-int X N Shift integer X left N decimal digits, or right -N digits with truncation toward zero. - Function: scale-rounding X N Like `scale-int', except that a right shift rounds to the nearest integer rather than truncating. - Function: fixnum N Return the integer N as a fixnum, i.e., a native Lisp integer. If N is outside the permissible range for Lisp integers (usually 24 binary bits) the result is undefined. - Function: sqr X Compute the square of X; short for `(* X X)'. - Function: quotient X Y Divide integer X by integer Y; return an integer quotient and discard the remainder. If X or Y is negative, the direction of rounding is undefined. - Function: idiv X Y Perform an integer division; if X and Y are both nonnegative integers, this uses the `quotient' function, otherwise it computes `floor(X/Y)'. Thus the result is well-defined but slower than for `quotient'. - Function: imod X Y Divide integer X by integer Y; return the integer remainder and discard the quotient. Like `quotient', this works only for integer arguments and is not well-defined for negative arguments. For a more well-defined result, use `(% X Y)'. - Function: idivmod X Y Divide integer X by integer Y; return a cons cell whose `car' is `(quotient X Y)' and whose `cdr' is `(imod X Y)'. - Function: pow X Y Compute X to the power Y. In `defmath' code, this can also be written `(^ X Y)' or `(expt X Y)'. - Function: abs-approx X Compute a fast approximation to the absolute value of X. For example, for a rectangular complex number the result is the sum of the absolute values of the components. - Function: pi The function `(pi)' computes `pi' to the current precision. Other related constant-generating functions are `two-pi', `pi-over-2', `pi-over-4', `pi-over-180', `sqrt-two-pi', `e', `sqrt-e', `ln-2', and `ln-10'. Each function returns a floating-point value in the current precision, and each uses caching so that all calls after the first are essentially free. - Macro: math-defcache FUNC INITIAL FORM This macro, usually used as a top-level call like `defun' or `defvar', defines a new cached constant analogous to `pi', etc. It defines a function `func' which returns the requested value; if INITIAL is non-`nil' it must be a `(float ...)' form which serves as an initial value for the cache. If FUNC is called when the cache is empty or does not have enough digits to satisfy the current precision, the Lisp expression FORM is evaluated with the current precision increased by four, and the result minus its two least significant digits is stored in the cache. For example, calling `(pi)' with a precision of 30 computes `pi' to 34 digits, rounds it down to 32 digits for future use, then rounds it again to 30 digits for use in the present request. - Function: full-circle SYMB If the current angular mode is Degrees or HMS, this function returns the integer 360. In Radians mode, this function returns either the corresponding value in radians to the current precision, or the formula `2*pi', depending on the Symbolic Mode. There are also similar function `half-circle' and `quarter-circle'. - Function: power-of-2 N Compute two to the integer power N, as a (potentially very large) integer. Powers of two are cached, so only the first call for a particular N is expensive. - Function: integer-log2 N Compute the base-2 logarithm of N, which must be an integer which is a power of two. If N is not a power of two, this function will return `nil'. - Function: div-mod A B M Divide A by B, modulo M. This returns `nil' if there is no solution, or if any of the arguments are not integers. - Function: pow-mod A B M Compute A to the power B, modulo M. If A, B, and M are integers, this uses an especially efficient algorithm. Otherwise, it simply computes `(% (^ a b) m)'. - Function: isqrt N Compute the integer square root of N. This is the square root of N rounded down toward zero, i.e., `floor(sqrt(N))'. If N is itself an integer, the computation is especially efficient. - Function: to-hms A ANG Convert the argument A into an HMS form. If ANG is specified, it is the angular mode in which to interpret A, either `deg' or `rad'. Otherwise, the current angular mode is used. If A is already an HMS form it is returned as-is. - Function: from-hms A ANG Convert the HMS form A into a real number. If ANG is specified, it is the angular mode in which to express the result, otherwise the current angular mode is used. If A is already a real number, it is returned as-is. - Function: to-radians A Convert the number or HMS form A to radians from the current angular mode. - Function: from-radians A Convert the number A from radians to the current angular mode. If A is a formula, this returns the formula `deg(A)'. - Function: to-radians-2 A Like `to-radians', except that in Symbolic Mode a degrees to radians conversion yields a formula like `A*pi/180'. - Function: from-radians-2 A Like `from-radians', except that in Symbolic Mode a radians to degrees conversion yields a formula like `A*180/pi'. - Function: random-digit Produce a random base-1000 digit in the range 0 to 999. - Function: random-digits N Produce a random N-digit integer; this will be an integer in the interval `[0, 10^N)'. - Function: random-float Produce a random float in the interval `[0, 1)'. - Function: prime-test N ITERS Determine whether the integer N is prime. Return a list which has one of these forms: `(nil F)' means the number is non-prime because it was found to be divisible by F; `(nil)' means it was found to be non-prime by table look-up (so no factors are known); `(nil unknown)' means it is definitely non-prime but no factors are known because N was large enough that Fermat's probabilistic test had to be used; `(t)' means the number is definitely prime; and `(maybe I P)' means that Fermat's test, after I iterations, is P percent sure that the number is prime. The ITERS parameter is the number of Fermat iterations to use, in the case that this is necessary. If `prime-test' returns "maybe," you can call it again with the same N to get a greater certainty; `prime-test' remembers where it left off. - Function: to-simple-fraction F If F is a floating-point number which can be represented exactly as a small rational number. return that number, else return F. For example, 0.75 would be converted to 3:4. This function is very fast. - Function: to-fraction F TOL Find a rational approximation to floating-point number F to within a specified tolerance TOL; this corresponds to the algebraic function `frac', and can be rather slow. - Function: quarter-integer N If N is an integer or integer-valued float, this function returns zero. If N is a half-integer (i.e., an integer plus 1:2 or 0.5), it returns 2. If N is a quarter-integer, it returns 1 or 3. If N is anything else, this function returns `nil'. File: calc.info, Node: Vector Lisp Functions, Next: Symbolic Lisp Functions, Prev: Computational Lisp Functions, Up: Internals Vector Functions ................ The functions described here perform various operations on vectors and matrices. - Function: math-concat X Y Do a vector concatenation; this operation is written `X | Y' in a symbolic formula. *Note Building Vectors::. - Function: vec-length V Return the length of vector V. If V is not a vector, the result is zero. If V is a matrix, this returns the number of rows in the matrix. - Function: mat-dimens M Determine the dimensions of vector or matrix M. If M is not a vector, the result is an empty list. If M is a plain vector but not a matrix, the result is a one-element list containing the length of the vector. If M is a matrix with R rows and C columns, the result is the list `(R C)'. Higher-order tensors produce lists of more than two dimensions. Note that the object `[[1, 2, 3], [4, 5]]' is a vector of vectors not all the same size, and is treated by this and other Calc routines as a plain vector of two elements. - Function: dimension-error Abort the current function with a message of "Dimension error." The Calculator will leave the function being evaluated in symbolic form; this is really just a special case of `reject-arg'. - Function: build-vector ARGS Return a Calc vector with the zero-or-more ARGS as elements. For example, `(build-vector 1 2 3)' returns the Calc vector `[1, 2, 3]', stored internally as the list `(vec 1 2 3)'. - Function: make-vec OBJ DIMS Return a Calc vector or matrix all of whose elements are equal to OBJ. For example, `(make-vec 27 3 4)' returns a 3x4 matrix filled with 27's. - Function: row-matrix V If V is a plain vector, convert it into a row matrix, i.e., a matrix whose single row is V. If V is already a matrix, leave it alone. - Function: col-matrix V If V is a plain vector, convert it into a column matrix, i.e., a matrix with each element of V as a separate row. If V is already a matrix, leave it alone. - Function: map-vec F V Map the Lisp function F over the Calc vector V. For example, `(map-vec 'math-floor v)' returns a vector of the floored components of vector V. - Function: map-vec-2 F A B Map the Lisp function F over the two vectors A and B. If A and B are vectors of equal length, the result is a vector of the results of calling `(F AI BI)' for each pair of elements AI and BI. If either A or B is a scalar, it is matched with each value of the other vector. For example, `(map-vec-2 'math-add v 1)' returns the vector V with each element increased by one. Note that using `'+' would not work here, since `defmath' does not expand function names everywhere, just where they are in the function position of a Lisp expression. - Function: reduce-vec F V Reduce the function F over the vector V. For example, if V is `[10, 20, 30, 40]', this calls `(f (f (f 10 20) 30) 40)'. If V is a matrix, this reduces over the rows of V. - Function: reduce-cols F M Reduce the function F over the columns of matrix M. For example, if M is `[[1, 2], [3, 4], [5, 6]]', the result is a vector of the two elements `(f (f 1 3) 5)' and `(f (f 2 4) 6)'. - Function: mat-row M N Return the Nth row of matrix M. This is equivalent to `(elt m n)'. For a slower but safer version, use `mrow'. (*Note Extracting Elements::.) - Function: mat-col M N Return the Nth column of matrix M, in the form of a vector. The arguments are not checked for correctness. - Function: mat-less-row M N Return a copy of matrix M with its Nth row deleted. The number N must be in range from 1 to the number of rows in M. - Function: mat-less-col M N Return a copy of matrix M with its Nth column deleted. - Function: transpose M Return the transpose of matrix M. - Function: flatten-vector V Flatten nested vector V into a vector of scalars. For example, if V is `[[1, 2, 3], [4, 5]]' the result is `[1, 2, 3, 4, 5]'. - Function: copy-matrix M If M is a matrix, return a copy of M. This maps `copy-sequence' over the rows of M; in Lisp terms, each element of the result matrix will be `eq' to the corresponding element of M, but none of the `cons' cells that make up the structure of the matrix will be `eq'. If M is a plain vector, this is the same as `copy-sequence'. - Function: swap-rows M R1 R2 Exchange rows R1 and R2 of matrix M in-place. In other words, unlike most of the other functions described here, this function changes M itself rather than building up a new result matrix. The return value is M, i.e., `(eq (swap-rows m 1 2) m)' is true, with the side effect of exchanging the first two rows of M.