2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/numbers
7 @node Numbers, Strings and Characters, Lisp Data Types, Top
12 GNU Emacs supports two numeric data types: @dfn{integers} and
13 @dfn{floating point numbers}. Integers are whole numbers such as
14 @minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
15 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
16 2.71828. They can also be expressed in exponential notation: 1.5e2
17 equals 150; in this example, @samp{e2} stands for ten to the second
18 power, and that is multiplied by 1.5. Floating point values are not
19 exact; they have a fixed, limited amount of precision.
22 * Integer Basics:: Representation and range of integers.
23 * Float Basics:: Representation and range of floating point.
24 * Predicates on Numbers:: Testing for numbers.
25 * Comparison of Numbers:: Equality and inequality predicates.
26 * Numeric Conversions:: Converting float to integer and vice versa.
27 * Arithmetic Operations:: How to add, subtract, multiply and divide.
28 * Rounding Operations:: Explicitly rounding floating point numbers.
29 * Bitwise Operations:: Logical and, or, not, shifting.
30 * Math Functions:: Trig, exponential and logarithmic functions.
31 * Random Numbers:: Obtaining random integers, predictable or not.
35 @comment node-name, next, previous, up
36 @section Integer Basics
38 The range of values for an integer depends on the machine. The
39 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
53 but some machines may provide a wider range. Many examples in this
54 chapter assume an integer has 28 bits.
57 The Lisp reader reads an integer as a sequence of digits with optional
58 initial sign and optional final period.
61 1 ; @r{The integer 1.}
62 1. ; @r{The integer 1.}
63 +1 ; @r{Also the integer 1.}
64 -1 ; @r{The integer @minus{}1.}
65 268435457 ; @r{Also the integer 1, due to overflow.}
66 0 ; @r{The integer 0.}
67 -0 ; @r{The integer 0.}
70 To understand how various functions work on integers, especially the
71 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
72 view the numbers in their binary form.
74 In 28-bit binary, the decimal integer 5 looks like this:
77 0000 0000 0000 0000 0000 0000 0101
81 (We have inserted spaces between groups of 4 bits, and two spaces
82 between groups of 8 bits, to make the binary integer easier to read.)
84 The integer @minus{}1 looks like this:
87 1111 1111 1111 1111 1111 1111 1111
91 @cindex two's complement
92 @minus{}1 is represented as 28 ones. (This is called @dfn{two's
93 complement} notation.)
95 The negative integer, @minus{}5, is creating by subtracting 4 from
96 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
97 @minus{}5 looks like this:
100 1111 1111 1111 1111 1111 1111 1011
103 In this implementation, the largest 28-bit binary integer value is
104 134,217,727 in decimal. In binary, it looks like this:
107 0111 1111 1111 1111 1111 1111 1111
110 Since the arithmetic functions do not check whether integers go
111 outside their range, when you add 1 to 134,217,727, the value is the
112 negative integer @minus{}134,217,728:
117 @result{} 1000 0000 0000 0000 0000 0000 0000
120 Many of the functions described in this chapter accept markers for
121 arguments in place of numbers. (@xref{Markers}.) Since the actual
122 arguments to such functions may be either numbers or markers, we often
123 give these arguments the name @var{number-or-marker}. When the argument
124 value is a marker, its position value is used and its buffer is ignored.
127 @section Floating Point Basics
129 Floating point numbers are useful for representing numbers that are
130 not integral. The precise range of floating point numbers is
131 machine-specific; it is the same as the range of the C data type
132 @code{double} on the machine you are using.
134 The read-syntax for floating point numbers requires either a decimal
135 point (with at least one digit following), an exponent, or both. For
136 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
137 @samp{.15e4} are five ways of writing a floating point number whose
138 value is 1500. They are all equivalent. You can also use a minus sign
139 to write negative floating point numbers, as in @samp{-1.0}.
141 @cindex IEEE floating point
142 @cindex positive infinity
143 @cindex negative infinity
146 Most modern computers support the IEEE floating point standard, which
147 provides for positive infinity and negative infinity as floating point
148 values. It also provides for a class of values called NaN or
149 ``not-a-number''; numerical functions return such values in cases where
150 there is no correct answer. For example, @code{(sqrt -1.0)} returns a
151 NaN. For practical purposes, there's no significant difference between
152 different NaN values in Emacs Lisp, and there's no rule for precisely
153 which NaN value should be used in a particular case, so Emacs Lisp
154 doesn't try to distinguish them. Here are the read syntaxes for
155 these special floating point values:
158 @item positive infinity
160 @item negative infinity
166 In addition, the value @code{-0.0} is distinguishable from ordinary
167 zero in IEEE floating point (although @code{equal} and @code{=} consider
170 You can use @code{logb} to extract the binary exponent of a floating
171 point number (or estimate the logarithm of an integer):
174 This function returns the binary exponent of @var{number}. More
175 precisely, the value is the logarithm of @var{number} base 2, rounded
186 @node Predicates on Numbers
187 @section Type Predicates for Numbers
189 The functions in this section test whether the argument is a number or
190 whether it is a certain sort of number. The functions @code{integerp}
191 and @code{floatp} can take any type of Lisp object as argument (the
192 predicates would not be of much use otherwise); but the @code{zerop}
193 predicate requires a number as its argument. See also
194 @code{integer-or-marker-p} and @code{number-or-marker-p}, in
195 @ref{Predicates on Markers}.
198 This predicate tests whether its argument is a floating point
199 number and returns @code{t} if so, @code{nil} otherwise.
201 @code{floatp} does not exist in Emacs versions 18 and earlier.
204 @defun integerp object
205 This predicate tests whether its argument is an integer, and returns
206 @code{t} if so, @code{nil} otherwise.
209 @defun numberp object
210 This predicate tests whether its argument is a number (either integer or
211 floating point), and returns @code{t} if so, @code{nil} otherwise.
214 @defun wholenump object
215 @cindex natural numbers
216 The @code{wholenump} predicate (whose name comes from the phrase
217 ``whole-number-p'') tests to see whether its argument is a nonnegative
218 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
219 considered non-negative.
222 @code{natnump} is an obsolete synonym for @code{wholenump}.
226 This predicate tests whether its argument is zero, and returns @code{t}
227 if so, @code{nil} otherwise. The argument must be a number.
229 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
232 @node Comparison of Numbers
233 @section Comparison of Numbers
234 @cindex number equality
236 To test numbers for numerical equality, you should normally use
237 @code{=}, not @code{eq}. There can be many distinct floating point
238 number objects with the same numeric value. If you use @code{eq} to
239 compare them, then you test whether two values are the same
240 @emph{object}. By contrast, @code{=} compares only the numeric values
243 At present, each integer value has a unique Lisp object in Emacs Lisp.
244 Therefore, @code{eq} is equivalent to @code{=} where integers are
245 concerned. It is sometimes convenient to use @code{eq} for comparing an
246 unknown value with an integer, because @code{eq} does not report an
247 error if the unknown value is not a number---it accepts arguments of any
248 type. By contrast, @code{=} signals an error if the arguments are not
249 numbers or markers. However, it is a good idea to use @code{=} if you
250 can, even for comparing integers, just in case we change the
251 representation of integers in a future Emacs version.
253 Sometimes it is useful to compare numbers with @code{equal}; it treats
254 two numbers as equal if they have the same data type (both integers, or
255 both floating point) and the same value. By contrast, @code{=} can
256 treat an integer and a floating point number as equal.
258 There is another wrinkle: because floating point arithmetic is not
259 exact, it is often a bad idea to check for equality of two floating
260 point values. Usually it is better to test for approximate equality.
261 Here's a function to do this:
264 (defvar fuzz-factor 1.0e-6)
265 (defun approx-equal (x y)
266 (or (and (= x 0) (= y 0))
268 (max (abs x) (abs y)))
272 @cindex CL note---integers vrs @code{eq}
274 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
275 @code{=} because Common Lisp implements multi-word integers, and two
276 distinct integer objects can have the same numeric value. Emacs Lisp
277 can have just one integer object for any given value because it has a
278 limited range of integer values.
281 @defun = number-or-marker1 number-or-marker2
282 This function tests whether its arguments are numerically equal, and
283 returns @code{t} if so, @code{nil} otherwise.
286 @defun /= number-or-marker1 number-or-marker2
287 This function tests whether its arguments are numerically equal, and
288 returns @code{t} if they are not, and @code{nil} if they are.
291 @defun < number-or-marker1 number-or-marker2
292 This function tests whether its first argument is strictly less than
293 its second argument. It returns @code{t} if so, @code{nil} otherwise.
296 @defun <= number-or-marker1 number-or-marker2
297 This function tests whether its first argument is less than or equal
298 to its second argument. It returns @code{t} if so, @code{nil}
302 @defun > number-or-marker1 number-or-marker2
303 This function tests whether its first argument is strictly greater
304 than its second argument. It returns @code{t} if so, @code{nil}
308 @defun >= number-or-marker1 number-or-marker2
309 This function tests whether its first argument is greater than or
310 equal to its second argument. It returns @code{t} if so, @code{nil}
314 @defun max number-or-marker &rest numbers-or-markers
315 This function returns the largest of its arguments.
316 If any of the argument is floating-point, the value is returned
317 as floating point, even if it was given as an integer.
329 @defun min number-or-marker &rest numbers-or-markers
330 This function returns the smallest of its arguments.
331 If any of the argument is floating-point, the value is returned
332 as floating point, even if it was given as an integer.
341 This function returns the absolute value of @var{number}.
344 @node Numeric Conversions
345 @section Numeric Conversions
346 @cindex rounding in conversions
348 To convert an integer to floating point, use the function @code{float}.
351 This returns @var{number} converted to floating point.
352 If @var{number} is already a floating point number, @code{float} returns
356 There are four functions to convert floating point numbers to integers;
357 they differ in how they round. These functions accept integer arguments
358 also, and return such arguments unchanged.
360 @defun truncate number
361 This returns @var{number}, converted to an integer by rounding towards
376 @defun floor number &optional divisor
377 This returns @var{number}, converted to an integer by rounding downward
378 (towards negative infinity).
380 If @var{divisor} is specified, @code{floor} divides @var{number} by
381 @var{divisor} and then converts to an integer; this uses the kind of
382 division operation that corresponds to @code{mod}, rounding downward.
383 An @code{arith-error} results if @var{divisor} is 0.
399 @defun ceiling number
400 This returns @var{number}, converted to an integer by rounding upward
401 (towards positive infinity).
416 This returns @var{number}, converted to an integer by rounding towards the
417 nearest integer. Rounding a value equidistant between two integers
418 may choose the integer closer to zero, or it may prefer an even integer,
419 depending on your machine.
433 @node Arithmetic Operations
434 @section Arithmetic Operations
436 Emacs Lisp provides the traditional four arithmetic operations:
437 addition, subtraction, multiplication, and division. Remainder and modulus
438 functions supplement the division functions. The functions to
439 add or subtract 1 are provided because they are traditional in Lisp and
442 All of these functions except @code{%} return a floating point value
443 if any argument is floating.
445 It is important to note that in Emacs Lisp, arithmetic functions
446 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
447 @minus{}134217728, depending on your hardware.
449 @defun 1+ number-or-marker
450 This function returns @var{number-or-marker} plus 1.
460 This function is not analogous to the C operator @code{++}---it does not
461 increment a variable. It just computes a sum. Thus, if we continue,
468 If you want to increment the variable, you must use @code{setq},
477 @defun 1- number-or-marker
478 This function returns @var{number-or-marker} minus 1.
481 @defun + &rest numbers-or-markers
482 This function adds its arguments together. When given no arguments,
495 @defun - &optional number-or-marker &rest more-numbers-or-markers
496 The @code{-} function serves two purposes: negation and subtraction.
497 When @code{-} has a single argument, the value is the negative of the
498 argument. When there are multiple arguments, @code{-} subtracts each of
499 the @var{more-numbers-or-markers} from @var{number-or-marker},
500 cumulatively. If there are no arguments, the result is 0.
512 @defun * &rest numbers-or-markers
513 This function multiplies its arguments together, and returns the
514 product. When given no arguments, @code{*} returns 1.
526 @defun / dividend divisor &rest divisors
527 This function divides @var{dividend} by @var{divisor} and returns the
528 quotient. If there are additional arguments @var{divisors}, then it
529 divides @var{dividend} by each divisor in turn. Each argument may be a
532 If all the arguments are integers, then the result is an integer too.
533 This means the result has to be rounded. On most machines, the result
534 is rounded towards zero after each division, but some machines may round
535 differently with negative arguments. This is because the Lisp function
536 @code{/} is implemented using the C division operator, which also
537 permits machine-dependent rounding. As a practical matter, all known
538 machines round in the standard fashion.
540 @cindex @code{arith-error} in division
541 If you divide an integer by 0, an @code{arith-error} error is signaled.
542 (@xref{Errors}.) Floating point division by zero returns either
543 infinity or a NaN if your machine supports IEEE floating point;
544 otherwise, it signals an @code{arith-error} error.
565 The result of @code{(/ -17 6)} could in principle be -3 on some
569 @defun % dividend divisor
571 This function returns the integer remainder after division of @var{dividend}
572 by @var{divisor}. The arguments must be integers or markers.
574 For negative arguments, the remainder is in principle machine-dependent
575 since the quotient is; but in practice, all known machines behave alike.
577 An @code{arith-error} results if @var{divisor} is 0.
590 For any two integers @var{dividend} and @var{divisor},
594 (+ (% @var{dividend} @var{divisor})
595 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
600 always equals @var{dividend}.
603 @defun mod dividend divisor
605 This function returns the value of @var{dividend} modulo @var{divisor};
606 in other words, the remainder after division of @var{dividend}
607 by @var{divisor}, but with the same sign as @var{divisor}.
608 The arguments must be numbers or markers.
610 Unlike @code{%}, @code{mod} returns a well-defined result for negative
611 arguments. It also permits floating point arguments; it rounds the
612 quotient downward (towards minus infinity) to an integer, and uses that
613 quotient to compute the remainder.
615 An @code{arith-error} results if @var{divisor} is 0.
640 For any two numbers @var{dividend} and @var{divisor},
644 (+ (mod @var{dividend} @var{divisor})
645 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
650 always equals @var{dividend}, subject to rounding error if either
651 argument is floating point. For @code{floor}, see @ref{Numeric
655 @node Rounding Operations
656 @section Rounding Operations
657 @cindex rounding without conversion
659 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
660 @code{ftruncate} take a floating point argument and return a floating
661 point result whose value is a nearby integer. @code{ffloor} returns the
662 nearest integer below; @code{fceiling}, the nearest integer above;
663 @code{ftruncate}, the nearest integer in the direction towards zero;
664 @code{fround}, the nearest integer.
667 This function rounds @var{float} to the next lower integral value, and
668 returns that value as a floating point number.
671 @defun fceiling float
672 This function rounds @var{float} to the next higher integral value, and
673 returns that value as a floating point number.
676 @defun ftruncate float
677 This function rounds @var{float} towards zero to an integral value, and
678 returns that value as a floating point number.
682 This function rounds @var{float} to the nearest integral value,
683 and returns that value as a floating point number.
686 @node Bitwise Operations
687 @section Bitwise Operations on Integers
689 In a computer, an integer is represented as a binary number, a
690 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
691 operation acts on the individual bits of such a sequence. For example,
692 @dfn{shifting} moves the whole sequence left or right one or more places,
693 reproducing the same pattern ``moved over''.
695 The bitwise operations in Emacs Lisp apply only to integers.
697 @defun lsh integer1 count
698 @cindex logical shift
699 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
700 bits in @var{integer1} to the left @var{count} places, or to the right
701 if @var{count} is negative, bringing zeros into the vacated bits. If
702 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
703 (most-significant) bit, producing a positive result even if
704 @var{integer1} is negative. Contrast this with @code{ash}, below.
706 Here are two examples of @code{lsh}, shifting a pattern of bits one
707 place to the left. We show only the low-order eight bits of the binary
708 pattern; the rest are all zero.
714 ;; @r{Decimal 5 becomes decimal 10.}
715 00000101 @result{} 00001010
719 ;; @r{Decimal 7 becomes decimal 14.}
720 00000111 @result{} 00001110
725 As the examples illustrate, shifting the pattern of bits one place to
726 the left produces a number that is twice the value of the previous
729 Shifting a pattern of bits two places to the left produces results
730 like this (with 8-bit binary numbers):
736 ;; @r{Decimal 3 becomes decimal 12.}
737 00000011 @result{} 00001100
741 On the other hand, shifting one place to the right looks like this:
747 ;; @r{Decimal 6 becomes decimal 3.}
748 00000110 @result{} 00000011
754 ;; @r{Decimal 5 becomes decimal 2.}
755 00000101 @result{} 00000010
760 As the example illustrates, shifting one place to the right divides the
761 value of a positive integer by two, rounding downward.
763 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
764 not check for overflow, so shifting left can discard significant bits
765 and change the sign of the number. For example, left shifting
766 134,217,727 produces @minus{}2 on a 28-bit machine:
769 (lsh 134217727 1) ; @r{left shift}
773 In binary, in the 28-bit implementation, the argument looks like this:
777 ;; @r{Decimal 134,217,727}
778 0111 1111 1111 1111 1111 1111 1111
783 which becomes the following when left shifted:
787 ;; @r{Decimal @minus{}2}
788 1111 1111 1111 1111 1111 1111 1110
793 @defun ash integer1 count
794 @cindex arithmetic shift
795 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
796 to the left @var{count} places, or to the right if @var{count}
799 @code{ash} gives the same results as @code{lsh} except when
800 @var{integer1} and @var{count} are both negative. In that case,
801 @code{ash} puts ones in the empty bit positions on the left, while
802 @code{lsh} puts zeros in those bit positions.
804 Thus, with @code{ash}, shifting the pattern of bits one place to the right
809 (ash -6 -1) @result{} -3
810 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
811 1111 1111 1111 1111 1111 1111 1010
813 1111 1111 1111 1111 1111 1111 1101
817 In contrast, shifting the pattern of bits one place to the right with
818 @code{lsh} looks like this:
822 (lsh -6 -1) @result{} 134217725
823 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
824 1111 1111 1111 1111 1111 1111 1010
826 0111 1111 1111 1111 1111 1111 1101
830 Here are other examples:
832 @c !!! Check if lined up in smallbook format! XDVI shows problem
833 @c with smallbook but not with regular book! --rjc 16mar92
836 ; @r{ 28-bit binary values}
838 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
839 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100}
844 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
845 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100}
850 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
851 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001}
858 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
859 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110}
862 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
863 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110}
868 @defun logand &rest ints-or-markers
871 This function returns the ``logical and'' of the arguments: the
872 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
873 set in all the arguments. (``Set'' means that the value of the bit is 1
876 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
877 12 is 12: 1101 combined with 1100 produces 1100.
878 In both the binary numbers, the leftmost two bits are set (i.e., they
879 are 1's), so the leftmost two bits of the returned value are set.
880 However, for the rightmost two bits, each is zero in at least one of
881 the arguments, so the rightmost two bits of the returned value are 0's.
893 If @code{logand} is not passed any argument, it returns a value of
894 @minus{}1. This number is an identity element for @code{logand}
895 because its binary representation consists entirely of ones. If
896 @code{logand} is passed just one argument, it returns that argument.
900 ; @r{ 28-bit binary values}
902 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
903 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
904 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
908 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
909 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
910 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
911 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
916 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111}
921 @defun logior &rest ints-or-markers
922 @cindex logical inclusive or
924 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
925 is set in the result if, and only if, the @var{n}th bit is set in at least
926 one of the arguments. If there are no arguments, the result is zero,
927 which is an identity element for this operation. If @code{logior} is
928 passed just one argument, it returns that argument.
932 ; @r{ 28-bit binary values}
934 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
935 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
936 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
940 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
941 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
942 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
943 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111}
948 @defun logxor &rest ints-or-markers
949 @cindex bitwise exclusive or
950 @cindex logical exclusive or
951 This function returns the ``exclusive or'' of its arguments: the
952 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
953 set in an odd number of the arguments. If there are no arguments, the
954 result is 0, which is an identity element for this operation. If
955 @code{logxor} is passed just one argument, it returns that argument.
959 ; @r{ 28-bit binary values}
961 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
962 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
963 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001}
967 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
968 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
969 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
970 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
975 @defun lognot integer
978 This function returns the logical complement of its argument: the @var{n}th
979 bit is one in the result if, and only if, the @var{n}th bit is zero in
980 @var{integer}, and vice-versa.
985 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
987 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
992 @section Standard Mathematical Functions
993 @cindex transcendental functions
994 @cindex mathematical functions
996 These mathematical functions allow integers as well as floating point
997 numbers as arguments.
1002 These are the ordinary trigonometric functions, with argument measured
1007 The value of @code{(asin @var{arg})} is a number between
1021 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
1022 is out of range (outside [-1, 1]), then the result is a NaN.
1026 The value of @code{(acos @var{arg})} is a number between 0 and
1033 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
1034 is out of range (outside [-1, 1]), then the result is a NaN.
1038 The value of @code{(atan @var{arg})} is a number between
1052 (exclusive) whose tangent is @var{arg}.
1056 This is the exponential function; it returns
1063 to the power @var{arg}.
1070 is a fundamental mathematical constant also called the base of natural
1074 @defun log arg &optional base
1075 This function returns the logarithm of @var{arg}, with base @var{base}.
1076 If you don't specify @var{base}, the base
1083 is used. If @var{arg}
1084 is negative, the result is a NaN.
1089 This function returns @code{(1- (exp @var{arg}))}, but it is more
1090 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1095 This function returns @code{(log (1+ @var{arg}))}, but it is more
1096 accurate than that when @var{arg} is so small that adding 1 to it would
1102 This function returns the logarithm of @var{arg}, with base 10. If
1103 @var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
1104 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1108 This function returns @var{x} raised to power @var{y}. If both
1109 arguments are integers and @var{y} is positive, the result is an
1110 integer; in this case, it is truncated to fit the range of possible
1115 This returns the square root of @var{arg}. If @var{arg} is negative,
1119 @node Random Numbers
1120 @section Random Numbers
1121 @cindex random numbers
1123 A deterministic computer program cannot generate true random numbers.
1124 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1125 pseudo-random numbers is generated in a deterministic fashion. The
1126 numbers are not truly random, but they have certain properties that
1127 mimic a random series. For example, all possible values occur equally
1128 often in a pseudo-random series.
1130 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1131 Starting from any given seed, the @code{random} function always
1132 generates the same sequence of numbers. Emacs always starts with the
1133 same seed value, so the sequence of values of @code{random} is actually
1134 the same in each Emacs run! For example, in one operating system, the
1135 first call to @code{(random)} after you start Emacs always returns
1136 -1457731, and the second one always returns -7692030. This
1137 repeatability is helpful for debugging.
1139 If you want random numbers that don't always come out the same, execute
1140 @code{(random t)}. This chooses a new seed based on the current time of
1141 day and on Emacs's process @sc{id} number.
1143 @defun random &optional limit
1144 This function returns a pseudo-random integer. Repeated calls return a
1145 series of pseudo-random integers.
1147 If @var{limit} is a positive integer, the value is chosen to be
1148 nonnegative and less than @var{limit}.
1150 If @var{limit} is @code{t}, it means to choose a new seed based on the
1151 current time of day and on Emacs's process @sc{id} number.
1152 @c "Emacs'" is incorrect usage!
1154 On some machines, any integer representable in Lisp may be the result
1155 of @code{random}. On other machines, the result can never be larger
1156 than a certain maximum or less than a certain (negative) minimum.