(lispref.info)Arithmetic Operations

Next: Bitwise Operations Prev: Numeric Conversions Up: Numbers

Arithmetic Operations
=====================

Emacs Lisp provides the traditional four arithmetic operations:
addition, subtraction, multiplication, and division.  Remainder and
modulus functions supplement the division functions.  The functions to
add or subtract 1 are provided because they are traditional in Lisp and
commonly used.

All of these functions except `%' return a floating point value if
any argument is floating.

It is important to note that in GNU Emacs Lisp, arithmetic functions
do not check for overflow.  Thus `(1+ 8388607)' may equal -8388608,

- Function: 1+ NUMBER-OR-MARKER
This function returns NUMBER-OR-MARKER plus 1.  For example,

(setq foo 4)
=> 4
(1+ foo)
=> 5

This function is not analogous to the C operator `++'--it does not
increment a variable.  It just computes a sum.  Thus,

foo
=> 4

If you want to increment the variable, you must use `setq', like
this:

(setq foo (1+ foo))
=> 5

- Function: 1- NUMBER-OR-MARKER
This function returns NUMBER-OR-MARKER minus 1.

- Function: abs NUMBER
This returns the absolute value of NUMBER.

- Function: + &rest NUMBERS-OR-MARKERS
This function adds its arguments together.  When given no
arguments, `+' returns 0.  It does not check for overflow.

(+)
=> 0
(+ 1)
=> 1
(+ 1 2 3 4)
=> 10

- Function: - &optional NUMBER-OR-MARKER &rest OTHER-NUMBERS-OR-MARKERS
The `-' function serves two purposes: negation and subtraction.
When `-' has a single argument, the value is the negative of the
argument.  When there are multiple arguments, each of the
OTHER-NUMBERS-OR-MARKERS is subtracted from NUMBER-OR-MARKER,
cumulatively.  If there are no arguments, the result is 0.  This
function does not check for overflow.

(- 10 1 2 3 4)
=> 0
(- 10)
=> -10
(-)
=> 0

- Function: * &rest NUMBERS-OR-MARKERS
This function multiplies its arguments together, and returns the
product.  When given no arguments, `*' returns 1.  It does not
check for overflow.

(*)
=> 1
(* 1)
=> 1
(* 1 2 3 4)
=> 24

- Function: / DIVIDEND DIVISOR &rest DIVISORS
This function divides DIVIDEND by DIVISORS and returns the
quotient.  If there are additional arguments DIVISORS, then
DIVIDEND is divided by each divisor in turn.  Each argument may be
a number or a marker.

If all the arguments are integers, then the result is an integer
too.  This means the result has to be rounded.  On most machines,
the result is rounded towards zero after each division, but some
machines may round differently with negative arguments.  This is
because the Lisp function `/' is implemented using the C division
operator, which has the same possibility for machine-dependent
rounding.  As a practical matter, all known machines round in the
standard fashion.

If you divide by 0, an `arith-error' error is signaled.  (*Note
Errors::.)

(/ 6 2)
=> 3
(/ 5 2)
=> 2
(/ 25 3 2)
=> 4
(/ -17 6)
=> -2

Since the division operator in Emacs Lisp is implemented using the
division operator in C, the result of dividing negative numbers
may in principle vary from machine to machine, depending on how
they round the result.  Thus, the result of `(/ -17 6)' could be
-3 on some machines.  In practice, all known machines round the
quotient towards 0.

- Function: % DIVIDEND DIVISOR
This function returns the integer remainder after division of
DIVIDEND by DIVISOR.  The arguments must be integers or markers.

For negative arguments, the value is in principle machine-dependent
since the quotient is; but in practice, all known machines behave
alike.

An `arith-error' results if DIVISOR is 0.

(% 9 4)
=> 1
(% -9 4)
=> -1
(% 9 -4)
=> 1
(% -9 -4)
=> -1

For any two integers DIVIDEND and DIVISOR,

(+ (% DIVIDEND DIVISOR)
(* (/ DIVIDEND DIVISOR) DIVISOR))

always equals DIVIDEND.

- Function: mod DIVIDEND DIVISOR
This function returns the value of DIVIDEND modulo DIVISOR; in
other words, the remainder after division of DIVIDEND by DIVISOR,
but with the same sign as DIVISOR.  The arguments must be numbers
or markers.

Unlike `%', the result is well-defined for negative arguments.
Also, floating point arguments are permitted.

An `arith-error' results if DIVISOR is 0.

(mod 9 4)
=> 1
(mod -9 4)
=> 3
(mod 9 -4)
=> -3
(mod -9 -4)
=> -1

For any two numbers DIVIDEND and DIVISOR,

(+ (mod DIVIDEND DIVISOR)
(* (floor DIVIDEND DIVISOR) DIVISOR))

always equals DIVIDEND, subject to rounding error if either
argument is floating point.

automatically generated by info2www