Common Lisp the Language, 2nd Edition

Next: Irrational and Transcendental Up: Numbers Previous: Comparisons on Numbers

# 12.4. Arithmetic Operations

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]
`+ &rest numbers`

This returns the sum of the arguments. If there are no arguments, the result is `0`, which is an identity for this operation.

Compatibility note: While `+` is compatible with its use in Lisp Machine Lisp, it is incompatible with MacLisp, which uses `+` for fixnum-only addition.

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

The function `-`, when given one argument, returns the negative of that argument.

The function `-`, when given more than one argument, successively subtracts from the first argument all the others, and returns the result. For example, `(- 3 4 5)` => `-6`.

Compatibility note: While `-` is compatible with its use in Lisp Machine Lisp, it is incompatible with MacLisp, which uses `-` for fixnum-only subtraction. Also, `-` differs from `difference` as used in most Lisp systems in the case of one argument.

[Function]
`* &rest numbers`

This returns the product of the arguments. If there are no arguments, the result is `1`, which is an identity for this operation.

Compatibility note: While `*` is compatible with its use in Lisp Machine Lisp, it is incompatible with MacLisp, which uses `*` for fixnum-only multiplication.

[Function]
`/ number &rest more-numbers`

The function `/`, when given more than one argument, successively divides the first argument by all the others and returns the result.

It is generally accepted that it is an error for any argument other than the first to be zero.

With one argument, `/` reciprocates the argument.

It is generally accepted that it is an error in this case for the argument to be zero.

`/` will produce a ratio if the mathematical quotient of two integers is not an exact integer. For example:

    (/ 12 4) => 3
    (/ 13 4) => 13/4
    (/ -8) => -1/8
    (/ 3 4 5) => 3/20

To divide one integer by another producing an integer result, use one of the functions `floor`, `ceiling`, `truncate`, or `round`.

If any argument is a floating-point number, then the rules of floating-point contagion apply.

Compatibility note: What `/` does is totally unlike what the usual `//` or `quotient` operator does. In most Lisp systems, `quotient` behaves like `/` except when dividing integers, in which case it behaves like `truncate` of two arguments; this behavior is mathematically intractable, leading to such anomalies as

    (quotient 1.0 2.0) => 0.5   but   (quotient 1 2) => 0

In contrast, the Common Lisp function `/` produces these results:

    (/ 1.0 2.0) => 0.5          and   (/ 1 2) => 1/2

In practice `quotient` is used only when one is sure that both arguments are integers, or when one is sure that at least one argument is a floating-point number. `/` is tractable for its purpose and works for any numbers.

[Function]
`1+ number
``1- number`

`(1+ x)` is the same as `(+ x 1)`.

`(1- x)` is the same as `(- x 1)`. Note that the short name may be confusing: `(1- x)` does not mean 1-x; rather, it means x-1.

Rationale: These are included primarily for compatibility with MacLisp and Lisp Machine Lisp. Some programmers prefer always to write `(+ x 1)` and `(- x 1)` instead of `(1+ x)` and `(1- x)`.

Implementation note: Compiler writers are very strongly encouraged to ensure that `(1+ x)` and `(+ x 1)` compile into identical code, and similarly for `(1- x)` and `(- x 1)`, to avoid pressure on a Lisp programmer to write possibly less clear code for the sake of efficiency. This can easily be done as a source-language transformation.

[Macro]
`incf place [delta]
``decf place [delta]`

The number produced by the form delta is added to (`incf`) or subtracted from (`decf`) the number in the generalized variable named by place, and the sum is stored back into place and returned. The form place may be any form acceptable as a generalized variable to `setf`. If delta is not supplied, then the number in place is changed by `1`. For example:

    (setq n 0)
    (incf n) => 1                   and now n => 1
    (decf n 3) => -2                and now n => -2
    (decf n -5) => 3                and now n => 3
    (decf n) => 2                   and now n => 2

The effect of `(incf place delta)` is roughly equivalent to

    (setf place (+ place delta))

except that the latter would evaluate any subforms of place twice, whereas `incf` takes care to evaluate them only once. Moreover, for certain place forms `incf` may be significantly more efficient than the `setf` version.

X3J13 voted in March 1988 (PUSH-EVALUATION-ORDER) to clarify order of evaluation (see section 7.2).

[Function]
`conjugate number`

This returns the complex conjugate of number. The conjugate of a non-complex number is itself. For a complex number `z`,

    (conjugate z) == (complex (realpart z) (- (imagpart z)))

For example:

    (conjugate #C(3/5 4/5)) => #C(3/5 -4/5)
    (conjugate #C(0.0D0 -1.0D0)) => #C(0.0D0 1.0D0)
    (conjugate 3.7) => 3.7

[Function]
`gcd &rest integers`

This returns the greatest common divisor of all the arguments, which must be integers. The result of `gcd` is always a non-negative integer. If one argument is given, its absolute value is returned. If no arguments are given, `gcd` returns `0`, which is an identity for this operation. For three or more arguments,

    (gcd a b c ... z) == (gcd (gcd a b) c ... z)

Here are some examples of the use of `gcd`:

    (gcd 91 -49) => 7
    (gcd 63 -42 35) => 7
    (gcd 5) => 5
    (gcd -4) => 4
    (gcd) => 0

[Function]
`lcm integer &rest more-integers`

This returns the least common multiple of its arguments, which must be integers. The result of `lcm` is always a non-negative integer. For two arguments that are not both zero,

    (lcm a b) == (/ (abs (* a b)) (gcd a b))

If one or both arguments are zero,

    (lcm a 0) == (lcm 0 a) == 0

For one argument, `lcm` returns the absolute value of that argument. For three or more arguments,

    (lcm a b c ... z) == (lcm (lcm a b) c ... z)

Some examples:

    (lcm 14 35) => 70
    (lcm 0 5) => 0
    (lcm 1 2 3 4 5 6) => 60

Mathematically, `(lcm)` should return infinity. Because Common Lisp does not have a representation for infinity, `lcm`, unlike `gcd`, always requires at least one argument.

X3J13 voted in January 1989 (LCM-NO-ARGUMENTS) to specify that `(lcm) => 1`.

This is one of my biggest boners. The identity for `lcm` is of course 1, not infinity, and so `(lcm)` ought to have been defined to return 1. Sorry about that, though in point of fact very few users have complained to me that this mistake in the first edition has cramped their programming style.

Next: Irrational and Transcendental Up: Numbers Previous: Comparisons on Numbers