Common Lisp the Language, 2nd Edition

Next: Arithmetic Operations Up: Numbers Previous: Predicates on Numbers

# 12.3. Comparisons on Numbers

Each of the functions in this section requires that its arguments all be numbers; to call one with a non-number is an error. Unless otherwise specified, each works on all types of numbers, automatically performing any required coercions when arguments are of different types.

[Function]
`= number &rest more-numbers
` `/= number &rest more-numbers
` `< number &rest more-numbers
` `> number &rest more-numbers
` `<= number &rest more-numbers
` `>= number &rest more-numbers`

These functions each take one or more arguments. If the sequence of arguments satisfies a certain condition:

    =            all the same
    /=           all different
    <            monotonically increasing
    >            monotonically decreasing
    <=           monotonically nondecreasing
    >=           monotonically nonincreasing

then the predicate is true, and otherwise is false. Complex numbers may be compared using `=` and `/=`, but the others require non-complex arguments. Two complex numbers are considered equal by `=` if their real parts are equal and their imaginary parts are equal according to `=`. A complex number may be compared with a non-complex number with `=` or `/=`. For example:

    (= 3 3) is true.		(/= 3 3) is false.
    (= 3 5) is false.		(/= 3 5) is true.
    (= 3 3 3 3) is true.		(/= 3 3 3 3) is false.
    (= 3 3 5 3) is false.		(/= 3 3 5 3) is false.
    (= 3 6 5 2) is false.		(/= 3 6 5 2) is true.
    (= 3 2 3) is false.		(/= 3 2 3) is false.
    (< 3 5) is true.		(<= 3 5) is true.
    (< 3 -5) is false.		(<= 3 -5) is false.
    (< 3 3) is false.		(<= 3 3) is true.
    (< 0 3 4 6 7) is true.		(<= 0 3 4 6 7) is true.
    (< 0 3 4 4 6) is false.		(<= 0 3 4 4 6) is true.
    (> 4 3) is true.		(>= 4 3) is true.
    (> 4 3 2 1 0) is true.		(>= 4 3 2 1 0) is true.
    (> 4 3 3 2 0) is false.		(>= 4 3 3 2 0) is true.
    (> 4 3 1 2 0) is false.		(>= 4 3 1 2 0) is false.
    (= 3) is true.			(/= 3) is true.
    (< 3) is true.			(<= 3) is true.
    (= 3.0 #C(3.0 0.0)) is true.	(/= 3.0 #C(3.0 1.0)) is true.
    (= 3 3.0) is true.		(= 3.0s0 3.0d0) is true.
    (= 0.0 -0.0) is true.		(= 5/2 2.5) is true.
    (> 0.0 -0.0) is false.		(= 0 -0.0) is true.

With two arguments, these functions perform the usual arithmetic comparison tests. With three or more arguments, they are useful for range checks, as shown in the following example:

    (<= 0 x 9)                      ;true if x is between 0 and 9, inclusive
    (< 0.0 x 1.0)                   ;true if x is between 0.0 and 1.0, exclusive
    (< -1 j (length s))             ;true if j is a valid index for s
    (<= 0 j k (- (length s) 1))     ;true if j and k are each valid
                                    ; indices for s and jk

Rationale: The ``unequality'' relation is called `/=` rather than `<>` (the name used in Pascal) for two reasons. First, `/=` of more than two arguments is not the same as the `or` of `<` and `>` of those same arguments. Second, unequality is meaningful for complex numbers even though `<` and `>` are not. For both reasons it would be misleading to associate unequality with the names of `<` and `>`.

Compatibility note: In Common Lisp, the comparison operations perform ``mixed-mode'' comparisons: `(= 3 3.0)` is true. In MacLisp, there must be exactly two arguments, and they must be either both fixnums or both floating-point numbers. To compare two numbers for numerical equality and type equality, use `eql`.

[Function]
`max number &rest more-numbers
``min number &rest more-numbers`

The arguments may be any non-complex numbers. `max` returns the argument that is greatest (closest to positive infinity). `min` returns the argument that is least (closest to negative infinity).

For `max`, if the arguments are a mixture of rationals and floating-point numbers, and the largest argument is a rational, then the implementation is free to produce either that rational or its floating-point approximation; if the largest argument is a floating-point number of a smaller format than the largest format of any floating-point argument, then the implementation is free to return the argument in its given format or expanded to the larger format. More concisely, the implementation has the choice of returning the largest argument as is or applying the rules of floating-point contagion, taking all the arguments into consideration for contagion purposes. Also, if two or more of the arguments are equal, then any one of them may be chosen as the value to return. Similar remarks apply to `min` (replacing ``largest argument'' by ``smallest argument'').

    (max 6 12) => 12		(min 6 12) => 6
    (max -6 -12) => -6		(min -6 -12) => -12
    (max 1 3 2 -7) => 3		(min 1 3 2 -7) => -7
    (max -2 3 0 7) => 7		(min -2 3 0 7) => -2
    (max 3) => 3			(min 3) => 3
    (max 5.0 2) => 5.0		(min 5.0 2) => 2 or 2.0
    (max 3.0 7 1) => 7 or 7.0	(min 3.0 7 1) => 1 or 1.0
    (max 1.0s0 7.0d0) => 7.0d0
    (min 1.0s0 7.0d0) => 1.0s0 or 1.0d0
    (max 3 1 1.0s0 1.0d0) => 3 or 3.0d0
    (min 3 1 1.0s0 1.0d0) => 1 or 1.0s0 or 1.0d0

Next: Arithmetic Operations Up: Numbers Previous: Predicates on Numbers