2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
5 @c See the file elisp.texi for copying conditions.
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. Floating-point numbers are numbers with
14 fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can
15 also be expressed in exponential notation: @samp{1.5e2} is the same as
16 @samp{150.0}; here, @samp{e2} stands for ten to the second power, and
17 that is multiplied by 1.5. Integer computations are exact, though
18 they may overflow. Floating-point computations often involve rounding
19 errors, as the numbers have a fixed 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 @section Integer Basics
37 The range of values for an integer depends on the machine. The
38 minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
52 but many machines provide a wider range. Many examples in this
53 chapter assume the minimum integer width of 30 bits.
56 The Lisp reader reads an integer as a sequence of digits with optional
57 initial sign and optional final period. An integer that is out of the
58 Emacs range is treated as a floating-point number.
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.}
66 ; @r{The floating-point number 9e18.}
67 0 ; @r{The integer 0.}
68 -0 ; @r{The integer 0.}
71 @cindex integers in specific radix
72 @cindex radix for reading an integer
73 @cindex base for reading an integer
76 @cindex reading numbers in hex, octal, and binary
77 The syntax for integers in bases other than 10 uses @samp{#}
78 followed by a letter that specifies the radix: @samp{b} for binary,
79 @samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
80 specify radix @var{radix}. Case is not significant for the letter
81 that specifies the radix. Thus, @samp{#b@var{integer}} reads
82 @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
83 @var{integer} in radix @var{radix}. Allowed values of @var{radix} run
84 from 2 to 36. For example:
93 To understand how various functions work on integers, especially the
94 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
95 view the numbers in their binary form.
97 In 30-bit binary, the decimal integer 5 looks like this:
100 0000...000101 (30 bits total)
104 (The @samp{...} stands for enough bits to fill out a 30-bit word; in
105 this case, @samp{...} stands for twenty 0 bits. Later examples also
106 use the @samp{...} notation to make binary integers easier to read.)
108 The integer @minus{}1 looks like this:
111 1111...111111 (30 bits total)
115 @cindex two's complement
116 @minus{}1 is represented as 30 ones. (This is called @dfn{two's
117 complement} notation.)
119 The negative integer, @minus{}5, is creating by subtracting 4 from
120 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
121 @minus{}5 looks like this:
124 1111...111011 (30 bits total)
127 In this implementation, the largest 30-bit binary integer is
128 536,870,911 in decimal. In binary, it looks like this:
131 0111...111111 (30 bits total)
134 Since the arithmetic functions do not check whether integers go
135 outside their range, when you add 1 to 536,870,911, the value is the
136 negative integer @minus{}536,870,912:
141 @result{} 1000...000000 (30 bits total)
144 Many of the functions described in this chapter accept markers for
145 arguments in place of numbers. (@xref{Markers}.) Since the actual
146 arguments to such functions may be either numbers or markers, we often
147 give these arguments the name @var{number-or-marker}. When the argument
148 value is a marker, its position value is used and its buffer is ignored.
150 @cindex largest Lisp integer
151 @cindex maximum Lisp integer
152 @defvar most-positive-fixnum
153 The value of this variable is the largest integer that Emacs Lisp can
154 handle. Typical values are
171 @cindex smallest Lisp integer
172 @cindex minimum Lisp integer
173 @defvar most-negative-fixnum
174 The value of this variable is the smallest integer that Emacs Lisp can
175 handle. It is negative. Typical values are
192 In Emacs Lisp, text characters are represented by integers. Any
193 integer between zero and the value of @code{max-char}, inclusive, is
194 considered to be valid as a character. @xref{String Basics}.
197 @section Floating-Point Basics
199 @cindex @acronym{IEEE} floating point
200 Floating-point numbers are useful for representing numbers that are
201 not integral. The range of floating-point numbers is
202 the same as the range of the C data type @code{double} on the machine
203 you are using. On all computers currently supported by Emacs, this is
204 double-precision @acronym{IEEE} floating point.
206 The read syntax for floating-point numbers requires either a decimal
207 point, an exponent, or both. Optional signs (@samp{+} or @samp{-})
208 precede the number and its exponent. For example, @samp{1500.0},
209 @samp{+15e2}, @samp{15.0e+2}, @samp{+1500000e-3}, and @samp{.15e4} are
210 five ways of writing a floating-point number whose value is 1500.
211 They are all equivalent. Like Common Lisp, Emacs Lisp requires at
212 least one digit after any decimal point in a floating-point number;
213 @samp{1500.} is an integer, not a floating-point number.
215 Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero
216 with respect to @code{equal} and @code{=}. This follows the
217 @acronym{IEEE} floating-point standard, which says @code{-0.0} and
218 @code{0.0} are numerically equal even though other operations can
221 @cindex positive infinity
222 @cindex negative infinity
225 The @acronym{IEEE} floating-point standard supports positive
226 infinity and negative infinity as floating-point values. It also
227 provides for a class of values called NaN or ``not-a-number'';
228 numerical functions return such values in cases where there is no
229 correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@.
230 Although NaN values carry a sign, for practical purposes there is no other
231 significant difference between different NaN values in Emacs Lisp.
233 Here are read syntaxes for these special floating-point values:
237 @samp{1.0e+INF} and @samp{-1.0e+INF}
239 @samp{0.0e+NaN} and @samp{-0.0e+NaN}
242 The following functions are specialized for handling floating-point
246 This predicate returns @code{t} if its floating-point argument is a NaN,
247 @code{nil} otherwise.
251 This function returns a cons cell @code{(@var{s} . @var{e})},
252 where @var{s} and @var{e} are respectively the significand and
253 exponent of the floating-point number @var{x}.
255 If @var{x} is finite, @var{s} is a floating-point number between 0.5
256 (inclusive) and 1.0 (exclusive), @var{e} is an integer, and
258 @var{x} = @var{s} * 2**@var{e}.
263 If @var{x} is zero or infinity, @var{s} is the same as @var{x}.
264 If @var{x} is a NaN, @var{s} is also a NaN.
265 If @var{x} is zero, @var{e} is 0.
268 @defun ldexp sig &optional exp
269 This function returns a floating-point number corresponding to the
270 significand @var{sig} and exponent @var{exp}.
273 @defun copysign x1 x2
274 This function copies the sign of @var{x2} to the value of @var{x1},
275 and returns the result. @var{x1} and @var{x2} must be floating point.
279 This function returns the binary exponent of @var{number}. More
280 precisely, the value is the logarithm of |@var{number}| base 2, rounded
291 @node Predicates on Numbers
292 @section Type Predicates for Numbers
293 @cindex predicates for numbers
295 The functions in this section test for numbers, or for a specific
296 type of number. The functions @code{integerp} and @code{floatp} can
297 take any type of Lisp object as argument (they would not be of much
298 use otherwise), but the @code{zerop} predicate requires a number as
299 its argument. See also @code{integer-or-marker-p} and
300 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
303 This predicate tests whether its argument is floating point
304 and returns @code{t} if so, @code{nil} otherwise.
307 @defun integerp object
308 This predicate tests whether its argument is an integer, and returns
309 @code{t} if so, @code{nil} otherwise.
312 @defun numberp object
313 This predicate tests whether its argument is a number (either integer or
314 floating point), and returns @code{t} if so, @code{nil} otherwise.
317 @defun natnump object
318 @cindex natural numbers
319 This predicate (whose name comes from the phrase ``natural number'')
320 tests to see whether its argument is a nonnegative integer, and
321 returns @code{t} if so, @code{nil} otherwise. 0 is considered
325 @code{wholenump} is a synonym for @code{natnump}.
329 This predicate tests whether its argument is zero, and returns @code{t}
330 if so, @code{nil} otherwise. The argument must be a number.
332 @code{(zerop x)} is equivalent to @code{(= x 0)}.
335 @node Comparison of Numbers
336 @section Comparison of Numbers
337 @cindex number comparison
338 @cindex comparing numbers
340 To test numbers for numerical equality, you should normally use
341 @code{=}, not @code{eq}. There can be many distinct floating-point
342 objects with the same numeric value. If you use @code{eq} to
343 compare them, then you test whether two values are the same
344 @emph{object}. By contrast, @code{=} compares only the numeric values
347 In Emacs Lisp, each integer is a unique Lisp object.
348 Therefore, @code{eq} is equivalent to @code{=} where integers are
349 concerned. It is sometimes convenient to use @code{eq} for comparing
350 an unknown value with an integer, because @code{eq} does not report an
351 error if the unknown value is not a number---it accepts arguments of
352 any type. By contrast, @code{=} signals an error if the arguments are
353 not numbers or markers. However, it is better programming practice to
354 use @code{=} if you can, even for comparing integers.
356 Sometimes it is useful to compare numbers with @code{equal}, which
357 treats two numbers as equal if they have the same data type (both
358 integers, or both floating point) and the same value. By contrast,
359 @code{=} can treat an integer and a floating-point number as equal.
360 @xref{Equality Predicates}.
362 There is another wrinkle: because floating-point arithmetic is not
363 exact, it is often a bad idea to check for equality of floating-point
364 values. Usually it is better to test for approximate equality.
365 Here's a function to do this:
368 (defvar fuzz-factor 1.0e-6)
369 (defun approx-equal (x y)
370 (or (and (= x 0) (= y 0))
372 (max (abs x) (abs y)))
376 @cindex CL note---integers vrs @code{eq}
378 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
379 @code{=} because Common Lisp implements multi-word integers, and two
380 distinct integer objects can have the same numeric value. Emacs Lisp
381 can have just one integer object for any given value because it has a
382 limited range of integers.
385 @defun = number-or-marker &rest number-or-markers
386 This function tests whether all its arguments are numerically equal,
387 and returns @code{t} if so, @code{nil} otherwise.
390 @defun eql value1 value2
391 This function acts like @code{eq} except when both arguments are
392 numbers. It compares numbers by type and numeric value, so that
393 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
394 @code{(eql 1 1)} both return @code{t}.
397 @defun /= number-or-marker1 number-or-marker2
398 This function tests whether its arguments are numerically equal, and
399 returns @code{t} if they are not, and @code{nil} if they are.
402 @defun < number-or-marker &rest number-or-markers
403 This function tests whether every argument is strictly less than the
404 respective next argument. It returns @code{t} if so, @code{nil}
408 @defun <= number-or-marker &rest number-or-markers
409 This function tests whether every argument is less than or equal to
410 the respective next argument. It returns @code{t} if so, @code{nil}
414 @defun > number-or-marker &rest number-or-markers
415 This function tests whether every argument is strictly greater than
416 the respective next argument. It returns @code{t} if so, @code{nil}
420 @defun >= number-or-marker &rest number-or-markers
421 This function tests whether every argument is greater than or equal to
422 the respective next argument. It returns @code{t} if so, @code{nil}
426 @defun max number-or-marker &rest numbers-or-markers
427 This function returns the largest of its arguments.
428 If any of the arguments is floating point, the value is returned
429 as floating point, even if it was given as an integer.
441 @defun min number-or-marker &rest numbers-or-markers
442 This function returns the smallest of its arguments.
443 If any of the arguments is floating point, the value is returned
444 as floating point, even if it was given as an integer.
453 This function returns the absolute value of @var{number}.
456 @node Numeric Conversions
457 @section Numeric Conversions
458 @cindex rounding in conversions
459 @cindex number conversions
460 @cindex converting numbers
462 To convert an integer to floating point, use the function @code{float}.
465 This returns @var{number} converted to floating point.
466 If @var{number} is already floating point, @code{float} returns
470 There are four functions to convert floating-point numbers to
471 integers; they differ in how they round. All accept an argument
472 @var{number} and an optional argument @var{divisor}. Both arguments
473 may be integers or floating-point numbers. @var{divisor} may also be
474 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
475 functions convert @var{number} to an integer, or return it unchanged
476 if it already is an integer. If @var{divisor} is non-@code{nil}, they
477 divide @var{number} by @var{divisor} and convert the result to an
478 integer. If @var{divisor} is zero (whether integer or
479 floating point), Emacs signals an @code{arith-error} error.
481 @defun truncate number &optional divisor
482 This returns @var{number}, converted to an integer by rounding towards
497 @defun floor number &optional divisor
498 This returns @var{number}, converted to an integer by rounding downward
499 (towards negative infinity).
501 If @var{divisor} is specified, this uses the kind of division
502 operation that corresponds to @code{mod}, rounding downward.
518 @defun ceiling number &optional divisor
519 This returns @var{number}, converted to an integer by rounding upward
520 (towards positive infinity).
534 @defun round number &optional divisor
535 This returns @var{number}, converted to an integer by rounding towards the
536 nearest integer. Rounding a value equidistant between two integers
537 may choose the integer closer to zero, or it may prefer an even integer,
538 depending on your machine.
552 @node Arithmetic Operations
553 @section Arithmetic Operations
554 @cindex arithmetic operations
556 Emacs Lisp provides the traditional four arithmetic operations
557 (addition, subtraction, multiplication, and division), as well as
558 remainder and modulus functions, and functions to add or subtract 1.
559 Except for @code{%}, each of these functions accepts both integer and
560 floating-point arguments, and returns a floating-point number if any
561 argument is floating point.
563 Emacs Lisp arithmetic functions do not check for integer overflow.
564 Thus @code{(1+ 536870911)} may evaluate to
565 @minus{}536870912, depending on your hardware.
567 @defun 1+ number-or-marker
568 This function returns @var{number-or-marker} plus 1.
578 This function is not analogous to the C operator @code{++}---it does not
579 increment a variable. It just computes a sum. Thus, if we continue,
586 If you want to increment the variable, you must use @code{setq},
595 @defun 1- number-or-marker
596 This function returns @var{number-or-marker} minus 1.
599 @defun + &rest numbers-or-markers
600 This function adds its arguments together. When given no arguments,
613 @defun - &optional number-or-marker &rest more-numbers-or-markers
614 The @code{-} function serves two purposes: negation and subtraction.
615 When @code{-} has a single argument, the value is the negative of the
616 argument. When there are multiple arguments, @code{-} subtracts each of
617 the @var{more-numbers-or-markers} from @var{number-or-marker},
618 cumulatively. If there are no arguments, the result is 0.
630 @defun * &rest numbers-or-markers
631 This function multiplies its arguments together, and returns the
632 product. When given no arguments, @code{*} returns 1.
644 @defun / dividend divisor &rest divisors
645 This function divides @var{dividend} by @var{divisor} and returns the
646 quotient. If there are additional arguments @var{divisors}, then it
647 divides @var{dividend} by each divisor in turn. Each argument may be a
650 If all the arguments are integers, the result is an integer, obtained
651 by rounding the quotient towards zero after each division.
652 (Hypothetically, some machines may have different rounding behavior
653 for negative arguments, because @code{/} is implemented using the C
654 division operator, which permits machine-dependent rounding; but this
655 does not happen in practice.)
688 @cindex @code{arith-error} in division
689 If you divide an integer by the integer 0, Emacs signals an
690 @code{arith-error} error (@pxref{Errors}). Floating-point division of
691 a nonzero number by zero yields either positive or negative infinity
692 (@pxref{Float Basics}).
695 @defun % dividend divisor
697 This function returns the integer remainder after division of @var{dividend}
698 by @var{divisor}. The arguments must be integers or markers.
700 For any two integers @var{dividend} and @var{divisor},
704 (+ (% @var{dividend} @var{divisor})
705 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
710 always equals @var{dividend}. If @var{divisor} is zero, Emacs signals
711 an @code{arith-error} error.
725 @defun mod dividend divisor
727 This function returns the value of @var{dividend} modulo @var{divisor};
728 in other words, the remainder after division of @var{dividend}
729 by @var{divisor}, but with the same sign as @var{divisor}.
730 The arguments must be numbers or markers.
732 Unlike @code{%}, @code{mod} permits floating-point arguments; it
733 rounds the quotient downward (towards minus infinity) to an integer,
734 and uses that quotient to compute the remainder.
736 If @var{divisor} is zero, @code{mod} signals an @code{arith-error}
737 error if both arguments are integers, and returns a NaN otherwise.
762 For any two numbers @var{dividend} and @var{divisor},
766 (+ (mod @var{dividend} @var{divisor})
767 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
772 always equals @var{dividend}, subject to rounding error if either
773 argument is floating point. For @code{floor}, see @ref{Numeric
777 @node Rounding Operations
778 @section Rounding Operations
779 @cindex rounding without conversion
781 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
782 @code{ftruncate} take a floating-point argument and return a floating-point
783 result whose value is a nearby integer. @code{ffloor} returns the
784 nearest integer below; @code{fceiling}, the nearest integer above;
785 @code{ftruncate}, the nearest integer in the direction towards zero;
786 @code{fround}, the nearest integer.
789 This function rounds @var{float} to the next lower integral value, and
790 returns that value as a floating-point number.
793 @defun fceiling float
794 This function rounds @var{float} to the next higher integral value, and
795 returns that value as a floating-point number.
798 @defun ftruncate float
799 This function rounds @var{float} towards zero to an integral value, and
800 returns that value as a floating-point number.
804 This function rounds @var{float} to the nearest integral value,
805 and returns that value as a floating-point number.
808 @node Bitwise Operations
809 @section Bitwise Operations on Integers
810 @cindex bitwise arithmetic
811 @cindex logical arithmetic
813 In a computer, an integer is represented as a binary number, a
814 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
815 operation acts on the individual bits of such a sequence. For example,
816 @dfn{shifting} moves the whole sequence left or right one or more places,
817 reproducing the same pattern ``moved over''.
819 The bitwise operations in Emacs Lisp apply only to integers.
821 @defun lsh integer1 count
822 @cindex logical shift
823 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
824 bits in @var{integer1} to the left @var{count} places, or to the right
825 if @var{count} is negative, bringing zeros into the vacated bits. If
826 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
827 (most-significant) bit, producing a positive result even if
828 @var{integer1} is negative. Contrast this with @code{ash}, below.
830 Here are two examples of @code{lsh}, shifting a pattern of bits one
831 place to the left. We show only the low-order eight bits of the binary
832 pattern; the rest are all zero.
838 ;; @r{Decimal 5 becomes decimal 10.}
839 00000101 @result{} 00001010
843 ;; @r{Decimal 7 becomes decimal 14.}
844 00000111 @result{} 00001110
849 As the examples illustrate, shifting the pattern of bits one place to
850 the left produces a number that is twice the value of the previous
853 Shifting a pattern of bits two places to the left produces results
854 like this (with 8-bit binary numbers):
860 ;; @r{Decimal 3 becomes decimal 12.}
861 00000011 @result{} 00001100
865 On the other hand, shifting one place to the right looks like this:
871 ;; @r{Decimal 6 becomes decimal 3.}
872 00000110 @result{} 00000011
878 ;; @r{Decimal 5 becomes decimal 2.}
879 00000101 @result{} 00000010
884 As the example illustrates, shifting one place to the right divides the
885 value of a positive integer by two, rounding downward.
887 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
888 not check for overflow, so shifting left can discard significant bits
889 and change the sign of the number. For example, left shifting
890 536,870,911 produces @minus{}2 in the 30-bit implementation:
893 (lsh 536870911 1) ; @r{left shift}
897 In binary, the argument looks like this:
901 ;; @r{Decimal 536,870,911}
902 0111...111111 (30 bits total)
907 which becomes the following when left shifted:
911 ;; @r{Decimal @minus{}2}
912 1111...111110 (30 bits total)
917 @defun ash integer1 count
918 @cindex arithmetic shift
919 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
920 to the left @var{count} places, or to the right if @var{count}
923 @code{ash} gives the same results as @code{lsh} except when
924 @var{integer1} and @var{count} are both negative. In that case,
925 @code{ash} puts ones in the empty bit positions on the left, while
926 @code{lsh} puts zeros in those bit positions.
928 Thus, with @code{ash}, shifting the pattern of bits one place to the right
933 (ash -6 -1) @result{} -3
934 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
935 1111...111010 (30 bits total)
937 1111...111101 (30 bits total)
941 In contrast, shifting the pattern of bits one place to the right with
942 @code{lsh} looks like this:
946 (lsh -6 -1) @result{} 536870909
947 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
948 1111...111010 (30 bits total)
950 0111...111101 (30 bits total)
954 Here are other examples:
956 @c !!! Check if lined up in smallbook format! XDVI shows problem
957 @c with smallbook but not with regular book! --rjc 16mar92
960 ; @r{ 30-bit binary values}
962 (lsh 5 2) ; 5 = @r{0000...000101}
963 @result{} 20 ; = @r{0000...010100}
968 (lsh -5 2) ; -5 = @r{1111...111011}
969 @result{} -20 ; = @r{1111...101100}
974 (lsh 5 -2) ; 5 = @r{0000...000101}
975 @result{} 1 ; = @r{0000...000001}
982 (lsh -5 -2) ; -5 = @r{1111...111011}
984 ; = @r{0011...111110}
987 (ash -5 -2) ; -5 = @r{1111...111011}
988 @result{} -2 ; = @r{1111...111110}
993 @defun logand &rest ints-or-markers
994 This function returns the ``logical and'' of the arguments: the
995 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
996 set in all the arguments. (``Set'' means that the value of the bit is 1
999 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
1000 12 is 12: 1101 combined with 1100 produces 1100.
1001 In both the binary numbers, the leftmost two bits are set (i.e., they
1002 are 1's), so the leftmost two bits of the returned value are set.
1003 However, for the rightmost two bits, each is zero in at least one of
1004 the arguments, so the rightmost two bits of the returned value are 0's.
1016 If @code{logand} is not passed any argument, it returns a value of
1017 @minus{}1. This number is an identity element for @code{logand}
1018 because its binary representation consists entirely of ones. If
1019 @code{logand} is passed just one argument, it returns that argument.
1023 ; @r{ 30-bit binary values}
1025 (logand 14 13) ; 14 = @r{0000...001110}
1026 ; 13 = @r{0000...001101}
1027 @result{} 12 ; 12 = @r{0000...001100}
1031 (logand 14 13 4) ; 14 = @r{0000...001110}
1032 ; 13 = @r{0000...001101}
1033 ; 4 = @r{0000...000100}
1034 @result{} 4 ; 4 = @r{0000...000100}
1039 @result{} -1 ; -1 = @r{1111...111111}
1044 @defun logior &rest ints-or-markers
1045 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
1046 is set in the result if, and only if, the @var{n}th bit is set in at least
1047 one of the arguments. If there are no arguments, the result is zero,
1048 which is an identity element for this operation. If @code{logior} is
1049 passed just one argument, it returns that argument.
1053 ; @r{ 30-bit binary values}
1055 (logior 12 5) ; 12 = @r{0000...001100}
1056 ; 5 = @r{0000...000101}
1057 @result{} 13 ; 13 = @r{0000...001101}
1061 (logior 12 5 7) ; 12 = @r{0000...001100}
1062 ; 5 = @r{0000...000101}
1063 ; 7 = @r{0000...000111}
1064 @result{} 15 ; 15 = @r{0000...001111}
1069 @defun logxor &rest ints-or-markers
1070 This function returns the ``exclusive or'' of its arguments: the
1071 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1072 set in an odd number of the arguments. If there are no arguments, the
1073 result is 0, which is an identity element for this operation. If
1074 @code{logxor} is passed just one argument, it returns that argument.
1078 ; @r{ 30-bit binary values}
1080 (logxor 12 5) ; 12 = @r{0000...001100}
1081 ; 5 = @r{0000...000101}
1082 @result{} 9 ; 9 = @r{0000...001001}
1086 (logxor 12 5 7) ; 12 = @r{0000...001100}
1087 ; 5 = @r{0000...000101}
1088 ; 7 = @r{0000...000111}
1089 @result{} 14 ; 14 = @r{0000...001110}
1094 @defun lognot integer
1095 This function returns the logical complement of its argument: the @var{n}th
1096 bit is one in the result if, and only if, the @var{n}th bit is zero in
1097 @var{integer}, and vice-versa.
1102 ;; 5 = @r{0000...000101} (30 bits total)
1104 ;; -6 = @r{1111...111010} (30 bits total)
1108 @node Math Functions
1109 @section Standard Mathematical Functions
1110 @cindex transcendental functions
1111 @cindex mathematical functions
1112 @cindex floating-point functions
1114 These mathematical functions allow integers as well as floating-point
1115 numbers as arguments.
1120 These are the basic trigonometric functions, with argument @var{arg}
1121 measured in radians.
1125 The value of @code{(asin @var{arg})} is a number between
1139 (inclusive) whose sine is @var{arg}. If @var{arg} is out of range
1140 (outside [@minus{}1, 1]), @code{asin} returns a NaN.
1144 The value of @code{(acos @var{arg})} is a number between 0 and
1151 (inclusive) whose cosine is @var{arg}. If @var{arg} is out of range
1152 (outside [@minus{}1, 1]), @code{acos} returns a NaN.
1155 @defun atan y &optional x
1156 The value of @code{(atan @var{y})} is a number between
1170 (exclusive) whose tangent is @var{y}. If the optional second
1171 argument @var{x} is given, the value of @code{(atan y x)} is the
1172 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1177 This is the exponential function; it returns @math{e} to the power
1181 @defun log arg &optional base
1182 This function returns the logarithm of @var{arg}, with base
1183 @var{base}. If you don't specify @var{base}, the natural base
1184 @math{e} is used. If @var{arg} or @var{base} is negative, @code{log}
1189 This function returns @var{x} raised to power @var{y}. If both
1190 arguments are integers and @var{y} is positive, the result is an
1191 integer; in this case, overflow causes truncation, so watch out.
1192 If @var{x} is a finite negative number and @var{y} is a finite
1193 non-integer, @code{expt} returns a NaN.
1197 This returns the square root of @var{arg}. If @var{arg} is negative,
1198 @code{sqrt} returns a NaN.
1201 In addition, Emacs defines the following common mathematical
1205 The mathematical constant @math{e} (2.71828@dots{}).
1209 The mathematical constant @math{pi} (3.14159@dots{}).
1212 @node Random Numbers
1213 @section Random Numbers
1214 @cindex random numbers
1216 A deterministic computer program cannot generate true random
1217 numbers. For most purposes, @dfn{pseudo-random numbers} suffice. A
1218 series of pseudo-random numbers is generated in a deterministic
1219 fashion. The numbers are not truly random, but they have certain
1220 properties that mimic a random series. For example, all possible
1221 values occur equally often in a pseudo-random series.
1223 Pseudo-random numbers are generated from a ``seed''. Starting from
1224 any given seed, the @code{random} function always generates the same
1225 sequence of numbers. By default, Emacs initializes the random seed at
1226 startup, in such a way that the sequence of values of @code{random}
1227 (with overwhelming likelihood) differs in each Emacs run.
1229 Sometimes you want the random number sequence to be repeatable. For
1230 example, when debugging a program whose behavior depends on the random
1231 number sequence, it is helpful to get the same behavior in each
1232 program run. To make the sequence repeat, execute @code{(random "")}.
1233 This sets the seed to a constant value for your particular Emacs
1234 executable (though it may differ for other Emacs builds). You can use
1235 other strings to choose various seed values.
1237 @defun random &optional limit
1238 This function returns a pseudo-random integer. Repeated calls return a
1239 series of pseudo-random integers.
1241 If @var{limit} is a positive integer, the value is chosen to be
1242 nonnegative and less than @var{limit}. Otherwise, the value might be
1243 any integer representable in Lisp, i.e., an integer between
1244 @code{most-negative-fixnum} and @code{most-positive-fixnum}
1245 (@pxref{Integer Basics}).
1247 If @var{limit} is @code{t}, it means to choose a new seed based on the
1248 current time of day and on Emacs's process @acronym{ID} number.
1250 If @var{limit} is a string, it means to choose a new seed based on the