GNU Info

(elisp)Arithmetic Operations

---

Next: Rounding Operations Prev: Numeric Conversions Up: Numbers

---

Enter node , (file) or (file)node

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 Emacs Lisp, arithmetic functions do
not check for overflow.  Thus `(1+ 134217727)' may evaluate to
-134217728, depending on your hardware.

 - 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, if we
     continue,

          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: + &rest numbers-or-markers
     This function adds its arguments together.  When given no
     arguments, `+' returns 0.

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

 - Function: - &optional number-or-marker &rest more-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, `-' subtracts each of
     the MORE-NUMBERS-OR-MARKERS from NUMBER-OR-MARKER, cumulatively.
     If there are no arguments, the result is 0.

          (- 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.

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

 - Function: / dividend divisor &rest divisors
     This function divides DIVIDEND by DIVISOR and returns the
     quotient.  If there are additional arguments DIVISORS, then it
     divides DIVIDEND 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 also permits machine-dependent rounding.  As a
     practical matter, all known machines round in the standard fashion.

     If you divide an integer by 0, an `arith-error' error is signaled.
     (Note: Errors.)  Floating point division by zero returns either
     infinity or a NaN if your machine supports IEEE floating point;
     otherwise, it signals an `arith-error' error.

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

     The result of `(/ -17 6)' could in principle be -3 on some
     machines.

 - 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 remainder 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 `%', `mod' returns a well-defined result for negative
     arguments.  It also permits floating point arguments; it rounds the
     quotient downward (towards minus infinity) to an integer, and uses
     that quotient to compute the remainder.

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

          (mod 9 4)
               => 1
          (mod -9 4)
               => 3
          (mod 9 -4)
               => -3
          (mod -9 -4)
               => -1
          (mod 5.5 2.5)
               => .5

     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.  For `floor', see Note: Numeric
     Conversions.