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]
+ &restnumbers

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&restmore-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]
* &restnumbers

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&restmore-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 (+x1).

(1-x) is the same as (-x1). 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]
incfplace[delta]
decfplace[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 (incfplacedelta) 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]
conjugatenumber

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 &restintegers

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]
lcminteger&restmore-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

AI.Repository@cs.cmu.edu