Basic Math

The basic arithmetic operations—addition, subtraction, multiplication, and division—are supported for all the different kinds of Lisp numbers with the functions **+**, **-**, *****, and **/**. Calling any of these functions with more than two arguments is equivalent to calling the same function on the first two arguments and then calling it again on the resulting value and the rest of the arguments. For example, (+ 1 2 3) is equivalent to (+ (+ 1 2) 3). With only one argument, **+** and ***** return the value; **-** returns its negation and **/** its reciprocal.9

  1. (+ 1 2)              ==> 3
  2. (+ 1 2 3)            ==> 6
  3. (+ 10.0 3.0)         ==> 13.0
  4. (+ #c(1 2) #c(3 4))  ==> #c(4 6)
  5. (- 5 4)              ==> 1
  6. (- 2)                ==> -2
  7. (- 10 3 5)           ==> 2
  8. (* 2 3)              ==> 6
  9. (* 2 3 4)            ==> 24
  10. (/ 10 5)             ==> 2
  11. (/ 10 5 2)           ==> 1
  12. (/ 2 3)              ==> 2/3
  13. (/ 4)                ==> 1/4

If all the arguments are the same type of number (rational, floating point, or complex), the result will be the same type except in the case where the result of an operation on complex numbers with rational components yields a number with a zero imaginary part, in which case the result will be a rational. However, floating-point and complex numbers are contagious--if all the arguments are reals but one or more are floating-point numbers, the other arguments are converted to the nearest floating-point value in a “largest” floating-point representation of the actual floating-point arguments. Floating-point numbers in a “smaller” representation are also converted to the larger representation. Similarly, if any of the arguments are complex, any real arguments are converted to the complex equivalents.

  1. (+ 1 2.0)             ==> 3.0
  2. (/ 2 3.0)             ==> 0.6666667
  3. (+ #c(1 2) 3)         ==> #c(4 2)
  4. (+ #c(1 2) 3/2)       ==> #c(5/2 2)
  5. (+ #c(1 1) #c(2 -1))  ==> 3

Because **/** doesn’t truncate, Common Lisp provides four flavors of truncating and rounding for converting a real number (rational or floating point) to an integer: **FLOOR** truncates toward negative infinity, returning the largest integer less than or equal to the argument. **CEILING** truncates toward positive infinity, returning the smallest integer greater than or equal to the argument. **TRUNCATE** truncates toward zero, making it equivalent to **FLOOR** for positive arguments and to **CEILING** for negative arguments. And **ROUND** rounds to the nearest integer. If the argument is exactly halfway between two integers, it rounds to the nearest even integer.

Two related functions are **MOD** and **REM**, which return the modulus and remainder of a truncating division on real numbers. These two functions are related to the **FLOOR** and **TRUNCATE** functions as follows:

  1. (+ (* (floor    (/ x y)) y) (mod x y)) === x
  2. (+ (* (truncate (/ x y)) y) (rem x y)) === x

Thus, for positive quotients they’re equivalent, but for negative quotients they produce different results.10

The functions **1+** and **1-** provide a shorthand way to express adding and subtracting one from a number. Note that these are different from the macros **INCF** and **DECF**. **1+** and **1-** are just functions that return a new value, but **INCF** and **DECF** modify a place. The following equivalences show the relation between **INCF**/**DECF**, **1+**/**1-**, and **+**/**-**:

  1. (incf x)    === (setf x (1+ x)) === (setf x (+ x 1))
  2. (decf x)    === (setf x (1- x)) === (setf x (- x 1))
  3. (incf x 10) === (setf x (+ x 10))
  4. (decf x 10) === (setf x (- x 10))