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.