Common Lisp the Language, 2nd Edition
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.
+ &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.
- 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.
* &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.
/ 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.
(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.
(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.
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).
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)))
(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
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
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)
(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.