2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/numbers
6 @node Numbers, Strings and Characters, Lisp Data Types, Top
11 GNU Emacs supports two numeric data types: @dfn{integers} and
12 @dfn{floating point numbers}. Integers are whole numbers such as
13 @minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
14 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
15 2.71828. They can also be expressed in exponential notation: 1.5e2
16 equals 150; in this example, @samp{e2} stands for ten to the second
17 power, and that is multiplied by 1.5. Floating point values are not
18 exact; they have a fixed, limited amount of precision.
21 * Integer Basics:: Representation and range of integers.
22 * Float Basics:: Representation and range of floating point.
23 * Predicates on Numbers:: Testing for numbers.
24 * Comparison of Numbers:: Equality and inequality predicates.
25 * Numeric Conversions:: Converting float to integer and vice versa.
26 * Arithmetic Operations:: How to add, subtract, multiply and divide.
27 * Rounding Operations:: Explicitly rounding floating point numbers.
28 * Bitwise Operations:: Logical and, or, not, shifting.
29 * Math Functions:: Trig, exponential and logarithmic functions.
30 * Random Numbers:: Obtaining random integers, predictable or not.
34 @comment node-name, next, previous, up
35 @section Integer Basics
37 The range of values for an integer depends on the machine. The
38 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
52 but some machines may provide a wider range. Many examples in this
53 chapter assume an integer has 28 bits.
56 The Lisp reader reads an integer as a sequence of digits with optional
57 initial sign and optional final period.
60 1 ; @r{The integer 1.}
61 1. ; @r{The integer 1.}
62 +1 ; @r{Also the integer 1.}
63 -1 ; @r{The integer @minus{}1.}
64 268435457 ; @r{Also the integer 1, due to overflow.}
65 0 ; @r{The integer 0.}
66 -0 ; @r{The integer 0.}
69 To understand how various functions work on integers, especially the
70 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
71 view the numbers in their binary form.
73 In 28-bit binary, the decimal integer 5 looks like this:
76 0000 0000 0000 0000 0000 0000 0101
80 (We have inserted spaces between groups of 4 bits, and two spaces
81 between groups of 8 bits, to make the binary integer easier to read.)
83 The integer @minus{}1 looks like this:
86 1111 1111 1111 1111 1111 1111 1111
90 @cindex two's complement
91 @minus{}1 is represented as 28 ones. (This is called @dfn{two's
92 complement} notation.)
94 The negative integer, @minus{}5, is creating by subtracting 4 from
95 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
96 @minus{}5 looks like this:
99 1111 1111 1111 1111 1111 1111 1011
102 In this implementation, the largest 28-bit binary integer value is
103 134,217,727 in decimal. In binary, it looks like this:
106 0111 1111 1111 1111 1111 1111 1111
109 Since the arithmetic functions do not check whether integers go
110 outside their range, when you add 1 to 134,217,727, the value is the
111 negative integer @minus{}134,217,728:
116 @result{} 1000 0000 0000 0000 0000 0000 0000
119 Many of the functions described in this chapter accept markers for
120 arguments in place of numbers. (@xref{Markers}.) Since the actual
121 arguments to such functions may be either numbers or markers, we often
122 give these arguments the name @var{number-or-marker}. When the argument
123 value is a marker, its position value is used and its buffer is ignored.
126 @section Floating Point Basics
128 Floating point numbers are useful for representing numbers that are
129 not integral. The precise range of floating point numbers is
130 machine-specific; it is the same as the range of the C data type
131 @code{double} on the machine you are using.
133 The read-syntax for floating point numbers requires either a decimal
134 point (with at least one digit following), an exponent, or both. For
135 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
136 @samp{.15e4} are five ways of writing a floating point number whose
137 value is 1500. They are all equivalent. You can also use a minus sign
138 to write negative floating point numbers, as in @samp{-1.0}.
140 @cindex IEEE floating point
141 @cindex positive infinity
142 @cindex negative infinity
145 Most modern computers support the IEEE floating point standard, which
146 provides for positive infinity and negative infinity as floating point
147 values. It also provides for a class of values called NaN or
148 ``not-a-number''; numerical functions return such values in cases where
149 there is no correct answer. For example, @code{(sqrt -1.0)} returns a
150 NaN. For practical purposes, there's no significant difference between
151 different NaN values in Emacs Lisp, and there's no rule for precisely
152 which NaN value should be used in a particular case, so Emacs Lisp
153 doesn't try to distinguish them. Here are the read syntaxes for
154 these special floating point values:
157 @item positive infinity
159 @item negative infinity
165 In addition, the value @code{-0.0} is distinguishable from ordinary
166 zero in IEEE floating point (although @code{equal} and @code{=} consider
169 You can use @code{logb} to extract the binary exponent of a floating
170 point number (or estimate the logarithm of an integer):
173 This function returns the binary exponent of @var{number}. More
174 precisely, the value is the logarithm of @var{number} base 2, rounded
185 @node Predicates on Numbers
186 @section Type Predicates for Numbers
188 The functions in this section test whether the argument is a number or
189 whether it is a certain sort of number. The functions @code{integerp}
190 and @code{floatp} can take any type of Lisp object as argument (the
191 predicates would not be of much use otherwise); but the @code{zerop}
192 predicate requires a number as its argument. See also
193 @code{integer-or-marker-p} and @code{number-or-marker-p}, in
194 @ref{Predicates on Markers}.
197 This predicate tests whether its argument is a floating point
198 number and returns @code{t} if so, @code{nil} otherwise.
200 @code{floatp} does not exist in Emacs versions 18 and earlier.
203 @defun integerp object
204 This predicate tests whether its argument is an integer, and returns
205 @code{t} if so, @code{nil} otherwise.
208 @defun numberp object
209 This predicate tests whether its argument is a number (either integer or
210 floating point), and returns @code{t} if so, @code{nil} otherwise.
213 @defun wholenump object
214 @cindex natural numbers
215 The @code{wholenump} predicate (whose name comes from the phrase
216 ``whole-number-p'') tests to see whether its argument is a nonnegative
217 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
218 considered non-negative.
221 @code{natnump} is an obsolete synonym for @code{wholenump}.
225 This predicate tests whether its argument is zero, and returns @code{t}
226 if so, @code{nil} otherwise. The argument must be a number.
228 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
231 @node Comparison of Numbers
232 @section Comparison of Numbers
233 @cindex number equality
235 To test numbers for numerical equality, you should normally use
236 @code{=}, not @code{eq}. There can be many distinct floating point
237 number objects with the same numeric value. If you use @code{eq} to
238 compare them, then you test whether two values are the same
239 @emph{object}. By contrast, @code{=} compares only the numeric values
242 At present, each integer value has a unique Lisp object in Emacs Lisp.
243 Therefore, @code{eq} is equivalent to @code{=} where integers are
244 concerned. It is sometimes convenient to use @code{eq} for comparing an
245 unknown value with an integer, because @code{eq} does not report an
246 error if the unknown value is not a number---it accepts arguments of any
247 type. By contrast, @code{=} signals an error if the arguments are not
248 numbers or markers. However, it is a good idea to use @code{=} if you
249 can, even for comparing integers, just in case we change the
250 representation of integers in a future Emacs version.
252 Sometimes it is useful to compare numbers with @code{equal}; it treats
253 two numbers as equal if they have the same data type (both integers, or
254 both floating point) and the same value. By contrast, @code{=} can
255 treat an integer and a floating point number as equal.
257 There is another wrinkle: because floating point arithmetic is not
258 exact, it is often a bad idea to check for equality of two floating
259 point values. Usually it is better to test for approximate equality.
260 Here's a function to do this:
263 (defvar fuzz-factor 1.0e-6)
264 (defun approx-equal (x y)
265 (or (and (= x 0) (= y 0))
267 (max (abs x) (abs y)))
271 @cindex CL note---integers vrs @code{eq}
273 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
274 @code{=} because Common Lisp implements multi-word integers, and two
275 distinct integer objects can have the same numeric value. Emacs Lisp
276 can have just one integer object for any given value because it has a
277 limited range of integer values.
280 @defun = number-or-marker1 number-or-marker2
281 This function tests whether its arguments are numerically equal, and
282 returns @code{t} if so, @code{nil} otherwise.
285 @defun /= number-or-marker1 number-or-marker2
286 This function tests whether its arguments are numerically equal, and
287 returns @code{t} if they are not, and @code{nil} if they are.
290 @defun < number-or-marker1 number-or-marker2
291 This function tests whether its first argument is strictly less than
292 its second argument. It returns @code{t} if so, @code{nil} otherwise.
295 @defun <= number-or-marker1 number-or-marker2
296 This function tests whether its first argument is less than or equal
297 to its second argument. It returns @code{t} if so, @code{nil}
301 @defun > number-or-marker1 number-or-marker2
302 This function tests whether its first argument is strictly greater
303 than its second argument. It returns @code{t} if so, @code{nil}
307 @defun >= number-or-marker1 number-or-marker2
308 This function tests whether its first argument is greater than or
309 equal to its second argument. It returns @code{t} if so, @code{nil}
313 @defun max number-or-marker &rest numbers-or-markers
314 This function returns the largest of its arguments.
315 If any of the argument is floating-point, the value is returned
316 as floating point, even if it was given as an integer.
328 @defun min number-or-marker &rest numbers-or-markers
329 This function returns the smallest of its arguments.
330 If any of the argument is floating-point, the value is returned
331 as floating point, even if it was given as an integer.
340 This function returns the absolute value of @var{number}.
343 @node Numeric Conversions
344 @section Numeric Conversions
345 @cindex rounding in conversions
347 To convert an integer to floating point, use the function @code{float}.
350 This returns @var{number} converted to floating point.
351 If @var{number} is already a floating point number, @code{float} returns
355 There are four functions to convert floating point numbers to integers;
356 they differ in how they round. These functions accept integer arguments
357 also, and return such arguments unchanged.
359 @defun truncate number
360 This returns @var{number}, converted to an integer by rounding towards
364 @defun floor number &optional divisor
365 This returns @var{number}, converted to an integer by rounding downward
366 (towards negative infinity).
368 If @var{divisor} is specified, @var{number} is divided by @var{divisor}
369 before the floor is taken; this uses the kind of division operation that
370 corresponds to @code{mod}, rounding downward. An @code{arith-error}
371 results if @var{divisor} is 0.
374 @defun ceiling number
375 This returns @var{number}, converted to an integer by rounding upward
376 (towards positive infinity).
380 This returns @var{number}, converted to an integer by rounding towards the
381 nearest integer. Rounding a value equidistant between two integers
382 may choose the integer closer to zero, or it may prefer an even integer,
383 depending on your machine.
386 @node Arithmetic Operations
387 @section Arithmetic Operations
389 Emacs Lisp provides the traditional four arithmetic operations:
390 addition, subtraction, multiplication, and division. Remainder and modulus
391 functions supplement the division functions. The functions to
392 add or subtract 1 are provided because they are traditional in Lisp and
395 All of these functions except @code{%} return a floating point value
396 if any argument is floating.
398 It is important to note that in Emacs Lisp, arithmetic functions
399 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
400 @minus{}134217728, depending on your hardware.
402 @defun 1+ number-or-marker
403 This function returns @var{number-or-marker} plus 1.
413 This function is not analogous to the C operator @code{++}---it does not
414 increment a variable. It just computes a sum. Thus, if we continue,
421 If you want to increment the variable, you must use @code{setq},
430 @defun 1- number-or-marker
431 This function returns @var{number-or-marker} minus 1.
434 @defun + &rest numbers-or-markers
435 This function adds its arguments together. When given no arguments,
448 @defun - &optional number-or-marker &rest more-numbers-or-markers
449 The @code{-} function serves two purposes: negation and subtraction.
450 When @code{-} has a single argument, the value is the negative of the
451 argument. When there are multiple arguments, @code{-} subtracts each of
452 the @var{more-numbers-or-markers} from @var{number-or-marker},
453 cumulatively. If there are no arguments, the result is 0.
465 @defun * &rest numbers-or-markers
466 This function multiplies its arguments together, and returns the
467 product. When given no arguments, @code{*} returns 1.
479 @defun / dividend divisor &rest divisors
480 This function divides @var{dividend} by @var{divisor} and returns the
481 quotient. If there are additional arguments @var{divisors}, then it
482 divides @var{dividend} by each divisor in turn. Each argument may be a
485 If all the arguments are integers, then the result is an integer too.
486 This means the result has to be rounded. On most machines, the result
487 is rounded towards zero after each division, but some machines may round
488 differently with negative arguments. This is because the Lisp function
489 @code{/} is implemented using the C division operator, which also
490 permits machine-dependent rounding. As a practical matter, all known
491 machines round in the standard fashion.
493 @cindex @code{arith-error} in division
494 If you divide an integer by 0, an @code{arith-error} error is signaled.
495 (@xref{Errors}.) Floating point division by zero returns either
496 infinity or a NaN if your machine supports IEEE floating point;
497 otherwise, it signals an @code{arith-error} error.
518 The result of @code{(/ -17 6)} could in principle be -3 on some
522 @defun % dividend divisor
524 This function returns the integer remainder after division of @var{dividend}
525 by @var{divisor}. The arguments must be integers or markers.
527 For negative arguments, the remainder is in principle machine-dependent
528 since the quotient is; but in practice, all known machines behave alike.
530 An @code{arith-error} results if @var{divisor} is 0.
543 For any two integers @var{dividend} and @var{divisor},
547 (+ (% @var{dividend} @var{divisor})
548 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
553 always equals @var{dividend}.
556 @defun mod dividend divisor
558 This function returns the value of @var{dividend} modulo @var{divisor};
559 in other words, the remainder after division of @var{dividend}
560 by @var{divisor}, but with the same sign as @var{divisor}.
561 The arguments must be numbers or markers.
563 Unlike @code{%}, @code{mod} returns a well-defined result for negative
564 arguments. It also permits floating point arguments; it rounds the
565 quotient downward (towards minus infinity) to an integer, and uses that
566 quotient to compute the remainder.
568 An @code{arith-error} results if @var{divisor} is 0.
593 For any two numbers @var{dividend} and @var{divisor},
597 (+ (mod @var{dividend} @var{divisor})
598 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
603 always equals @var{dividend}, subject to rounding error if either
604 argument is floating point. For @code{floor}, see @ref{Numeric
608 @node Rounding Operations
609 @section Rounding Operations
610 @cindex rounding without conversion
612 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
613 @code{ftruncate} take a floating point argument and return a floating
614 point result whose value is a nearby integer. @code{ffloor} returns the
615 nearest integer below; @code{fceiling}, the nearest integer above;
616 @code{ftruncate}, the nearest integer in the direction towards zero;
617 @code{fround}, the nearest integer.
620 This function rounds @var{float} to the next lower integral value, and
621 returns that value as a floating point number.
624 @defun fceiling float
625 This function rounds @var{float} to the next higher integral value, and
626 returns that value as a floating point number.
629 @defun ftruncate float
630 This function rounds @var{float} towards zero to an integral value, and
631 returns that value as a floating point number.
635 This function rounds @var{float} to the nearest integral value,
636 and returns that value as a floating point number.
639 @node Bitwise Operations
640 @section Bitwise Operations on Integers
642 In a computer, an integer is represented as a binary number, a
643 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
644 operation acts on the individual bits of such a sequence. For example,
645 @dfn{shifting} moves the whole sequence left or right one or more places,
646 reproducing the same pattern ``moved over''.
648 The bitwise operations in Emacs Lisp apply only to integers.
650 @defun lsh integer1 count
651 @cindex logical shift
652 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
653 bits in @var{integer1} to the left @var{count} places, or to the right
654 if @var{count} is negative, bringing zeros into the vacated bits. If
655 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
656 (most-significant) bit, producing a positive result even if
657 @var{integer1} is negative. Contrast this with @code{ash}, below.
659 Here are two examples of @code{lsh}, shifting a pattern of bits one
660 place to the left. We show only the low-order eight bits of the binary
661 pattern; the rest are all zero.
667 ;; @r{Decimal 5 becomes decimal 10.}
668 00000101 @result{} 00001010
672 ;; @r{Decimal 7 becomes decimal 14.}
673 00000111 @result{} 00001110
678 As the examples illustrate, shifting the pattern of bits one place to
679 the left produces a number that is twice the value of the previous
682 Shifting a pattern of bits two places to the left produces results
683 like this (with 8-bit binary numbers):
689 ;; @r{Decimal 3 becomes decimal 12.}
690 00000011 @result{} 00001100
694 On the other hand, shifting one place to the right looks like this:
700 ;; @r{Decimal 6 becomes decimal 3.}
701 00000110 @result{} 00000011
707 ;; @r{Decimal 5 becomes decimal 2.}
708 00000101 @result{} 00000010
713 As the example illustrates, shifting one place to the right divides the
714 value of a positive integer by two, rounding downward.
716 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
717 not check for overflow, so shifting left can discard significant bits
718 and change the sign of the number. For example, left shifting
719 134,217,727 produces @minus{}2 on a 28-bit machine:
722 (lsh 134217727 1) ; @r{left shift}
726 In binary, in the 28-bit implementation, the argument looks like this:
730 ;; @r{Decimal 134,217,727}
731 0111 1111 1111 1111 1111 1111 1111
736 which becomes the following when left shifted:
740 ;; @r{Decimal @minus{}2}
741 1111 1111 1111 1111 1111 1111 1110
746 @defun ash integer1 count
747 @cindex arithmetic shift
748 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
749 to the left @var{count} places, or to the right if @var{count}
752 @code{ash} gives the same results as @code{lsh} except when
753 @var{integer1} and @var{count} are both negative. In that case,
754 @code{ash} puts ones in the empty bit positions on the left, while
755 @code{lsh} puts zeros in those bit positions.
757 Thus, with @code{ash}, shifting the pattern of bits one place to the right
762 (ash -6 -1) @result{} -3
763 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
764 1111 1111 1111 1111 1111 1111 1010
766 1111 1111 1111 1111 1111 1111 1101
770 In contrast, shifting the pattern of bits one place to the right with
771 @code{lsh} looks like this:
775 (lsh -6 -1) @result{} 134217725
776 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
777 1111 1111 1111 1111 1111 1111 1010
779 0111 1111 1111 1111 1111 1111 1101
783 Here are other examples:
785 @c !!! Check if lined up in smallbook format! XDVI shows problem
786 @c with smallbook but not with regular book! --rjc 16mar92
789 ; @r{ 28-bit binary values}
791 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
792 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100}
797 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
798 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100}
803 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
804 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001}
811 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
812 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110}
815 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
816 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110}
821 @defun logand &rest ints-or-markers
824 This function returns the ``logical and'' of the arguments: the
825 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
826 set in all the arguments. (``Set'' means that the value of the bit is 1
829 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
830 12 is 12: 1101 combined with 1100 produces 1100.
831 In both the binary numbers, the leftmost two bits are set (i.e., they
832 are 1's), so the leftmost two bits of the returned value are set.
833 However, for the rightmost two bits, each is zero in at least one of
834 the arguments, so the rightmost two bits of the returned value are 0's.
846 If @code{logand} is not passed any argument, it returns a value of
847 @minus{}1. This number is an identity element for @code{logand}
848 because its binary representation consists entirely of ones. If
849 @code{logand} is passed just one argument, it returns that argument.
853 ; @r{ 28-bit binary values}
855 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
856 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
857 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
861 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
862 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
863 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
864 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
869 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111}
874 @defun logior &rest ints-or-markers
875 @cindex logical inclusive or
877 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
878 is set in the result if, and only if, the @var{n}th bit is set in at least
879 one of the arguments. If there are no arguments, the result is zero,
880 which is an identity element for this operation. If @code{logior} is
881 passed just one argument, it returns that argument.
885 ; @r{ 28-bit binary values}
887 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
888 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
889 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
893 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
894 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
895 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
896 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111}
901 @defun logxor &rest ints-or-markers
902 @cindex bitwise exclusive or
903 @cindex logical exclusive or
904 This function returns the ``exclusive or'' of its arguments: the
905 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
906 set in an odd number of the arguments. If there are no arguments, the
907 result is 0, which is an identity element for this operation. If
908 @code{logxor} is passed just one argument, it returns that argument.
912 ; @r{ 28-bit binary values}
914 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
915 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
916 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001}
920 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
921 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
922 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
923 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
928 @defun lognot integer
931 This function returns the logical complement of its argument: the @var{n}th
932 bit is one in the result if, and only if, the @var{n}th bit is zero in
933 @var{integer}, and vice-versa.
938 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
940 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
945 @section Standard Mathematical Functions
946 @cindex transcendental functions
947 @cindex mathematical functions
949 These mathematical functions allow integers as well as floating point
950 numbers as arguments.
955 These are the ordinary trigonometric functions, with argument measured
960 The value of @code{(asin @var{arg})} is a number between
974 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
975 is out of range (outside [-1, 1]), then the result is a NaN.
979 The value of @code{(acos @var{arg})} is a number between 0 and
986 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
987 is out of range (outside [-1, 1]), then the result is a NaN.
991 The value of @code{(atan @var{arg})} is a number between
1005 (exclusive) whose tangent is @var{arg}.
1009 This is the exponential function; it returns
1016 to the power @var{arg}.
1023 is a fundamental mathematical constant also called the base of natural
1027 @defun log arg &optional base
1028 This function returns the logarithm of @var{arg}, with base @var{base}.
1029 If you don't specify @var{base}, the base
1036 is used. If @var{arg}
1037 is negative, the result is a NaN.
1042 This function returns @code{(1- (exp @var{arg}))}, but it is more
1043 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1048 This function returns @code{(log (1+ @var{arg}))}, but it is more
1049 accurate than that when @var{arg} is so small that adding 1 to it would
1055 This function returns the logarithm of @var{arg}, with base 10. If
1056 @var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
1057 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1061 This function returns @var{x} raised to power @var{y}. If both
1062 arguments are integers and @var{y} is positive, the result is an
1063 integer; in this case, it is truncated to fit the range of possible
1068 This returns the square root of @var{arg}. If @var{arg} is negative,
1072 @node Random Numbers
1073 @section Random Numbers
1074 @cindex random numbers
1076 A deterministic computer program cannot generate true random numbers.
1077 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1078 pseudo-random numbers is generated in a deterministic fashion. The
1079 numbers are not truly random, but they have certain properties that
1080 mimic a random series. For example, all possible values occur equally
1081 often in a pseudo-random series.
1083 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1084 Starting from any given seed, the @code{random} function always
1085 generates the same sequence of numbers. Emacs always starts with the
1086 same seed value, so the sequence of values of @code{random} is actually
1087 the same in each Emacs run! For example, in one operating system, the
1088 first call to @code{(random)} after you start Emacs always returns
1089 -1457731, and the second one always returns -7692030. This
1090 repeatability is helpful for debugging.
1092 If you want random numbers that don't always come out the same, execute
1093 @code{(random t)}. This chooses a new seed based on the current time of
1094 day and on Emacs's process @sc{id} number.
1096 @defun random &optional limit
1097 This function returns a pseudo-random integer. Repeated calls return a
1098 series of pseudo-random integers.
1100 If @var{limit} is a positive integer, the value is chosen to be
1101 nonnegative and less than @var{limit}.
1103 If @var{limit} is @code{t}, it means to choose a new seed based on the
1104 current time of day and on Emacs's process @sc{id} number.
1105 @c "Emacs'" is incorrect usage!
1107 On some machines, any integer representable in Lisp may be the result
1108 of @code{random}. On other machines, the result can never be larger
1109 than a certain maximum or less than a certain (negative) minimum.