2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
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{}536870912 to 536870911 (30 bits; i.e.,
52 but some machines provide a wider range. Many examples in this
53 chapter assume that an integer has 30 bits and that floating point
54 numbers are IEEE double precision.
57 The Lisp reader reads an integer as a sequence of digits with optional
58 initial sign and optional final period. An integer that is out of the
59 Emacs range is treated as a floating-point number.
62 1 ; @r{The integer 1.}
63 1. ; @r{The integer 1.}
64 +1 ; @r{Also the integer 1.}
65 -1 ; @r{The integer @minus{}1.}
66 1073741825 ; @r{The floating point number 1073741825.0.}
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 value 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 number
151 @cindex maximum Lisp integer number
152 @defvar most-positive-fixnum
153 The value of this variable is the largest integer that Emacs Lisp
157 @cindex smallest Lisp integer number
158 @cindex minimum Lisp integer number
159 @defvar most-negative-fixnum
160 The value of this variable is the smallest integer that Emacs Lisp can
161 handle. It is negative.
164 @xref{Character Codes, max-char}, for the maximum value of a valid
168 @section Floating Point Basics
170 @cindex @acronym{IEEE} floating point
171 Floating point numbers are useful for representing numbers that are
172 not integral. The precise range of floating point numbers is
173 machine-specific; it is the same as the range of the C data type
174 @code{double} on the machine you are using. Emacs uses the
175 @acronym{IEEE} floating point standard where possible (the standard is
176 supported by most modern computers).
178 The read syntax for floating point numbers requires either a decimal
179 point (with at least one digit following), an exponent, or both. For
180 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
181 @samp{.15e4} are five ways of writing a floating point number whose
182 value is 1500. They are all equivalent. You can also use a minus
183 sign to write negative floating point numbers, as in @samp{-1.0}.
185 Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with
186 respect to @code{equal} and @code{=}), even though the two are
187 distinguishable in the @acronym{IEEE} floating point standard.
189 @cindex positive infinity
190 @cindex negative infinity
193 The @acronym{IEEE} floating point standard supports positive
194 infinity and negative infinity as floating point values. It also
195 provides for a class of values called NaN or ``not-a-number'';
196 numerical functions return such values in cases where there is no
197 correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN. (NaN
198 values can also carry a sign, but for practical purposes there's no
199 significant difference between different NaN values in Emacs Lisp.)
200 Here are the read syntaxes for these special floating point values:
203 @item positive infinity
205 @item negative infinity
208 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
212 This predicate tests whether its argument is NaN, and returns @code{t}
213 if so, @code{nil} otherwise. The argument must be a number.
216 The following functions are specialized for handling floating point
220 This function returns a cons cell @code{(@var{sig} . @var{exp})},
221 where @var{sig} and @var{exp} are respectively the significand and
222 exponent of the floating point number @var{x}:
225 @var{x} = @var{sig} * 2^@var{exp}
228 @var{sig} is a floating point number between 0.5 (inclusive) and 1.0
229 (exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}.
232 @defun ldexp sig &optional exp
233 This function returns a floating point number corresponding to the
234 significand @var{sig} and exponent @var{exp}.
237 @defun copysign x1 x2
238 This function copies the sign of @var{x2} to the value of @var{x1},
239 and returns the result. @var{x1} and @var{x2} must be floating point
244 This function returns the binary exponent of @var{number}. More
245 precisely, the value is the logarithm of @var{number} base 2, rounded
256 @node Predicates on Numbers
257 @section Type Predicates for Numbers
258 @cindex predicates for numbers
260 The functions in this section test for numbers, or for a specific
261 type of number. The functions @code{integerp} and @code{floatp} can
262 take any type of Lisp object as argument (they would not be of much
263 use otherwise), but the @code{zerop} predicate requires a number as
264 its argument. See also @code{integer-or-marker-p} and
265 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
268 This predicate tests whether its argument is a floating point
269 number and returns @code{t} if so, @code{nil} otherwise.
272 @defun integerp object
273 This predicate tests whether its argument is an integer, and returns
274 @code{t} if so, @code{nil} otherwise.
277 @defun numberp object
278 This predicate tests whether its argument is a number (either integer or
279 floating point), and returns @code{t} if so, @code{nil} otherwise.
282 @defun natnump object
283 @cindex natural numbers
284 This predicate (whose name comes from the phrase ``natural number'')
285 tests to see whether its argument is a nonnegative integer, and
286 returns @code{t} if so, @code{nil} otherwise. 0 is considered
289 @findex wholenump number
290 This is a synonym for @code{natnump}.
294 This predicate tests whether its argument is zero, and returns @code{t}
295 if so, @code{nil} otherwise. The argument must be a number.
297 @code{(zerop x)} is equivalent to @code{(= x 0)}.
300 @node Comparison of Numbers
301 @section Comparison of Numbers
302 @cindex number comparison
303 @cindex comparing numbers
305 To test numbers for numerical equality, you should normally use
306 @code{=}, not @code{eq}. There can be many distinct floating point
307 number objects with the same numeric value. If you use @code{eq} to
308 compare them, then you test whether two values are the same
309 @emph{object}. By contrast, @code{=} compares only the numeric values
312 At present, each integer value has a unique Lisp object in Emacs Lisp.
313 Therefore, @code{eq} is equivalent to @code{=} where integers are
314 concerned. It is sometimes convenient to use @code{eq} for comparing an
315 unknown value with an integer, because @code{eq} does not report an
316 error if the unknown value is not a number---it accepts arguments of any
317 type. By contrast, @code{=} signals an error if the arguments are not
318 numbers or markers. However, it is a good idea to use @code{=} if you
319 can, even for comparing integers, just in case we change the
320 representation of integers in a future Emacs version.
322 Sometimes it is useful to compare numbers with @code{equal}; it
323 treats two numbers as equal if they have the same data type (both
324 integers, or both floating point) and the same value. By contrast,
325 @code{=} can treat an integer and a floating point number as equal.
326 @xref{Equality Predicates}.
328 There is another wrinkle: because floating point arithmetic is not
329 exact, it is often a bad idea to check for equality of two floating
330 point values. Usually it is better to test for approximate equality.
331 Here's a function to do this:
334 (defvar fuzz-factor 1.0e-6)
335 (defun approx-equal (x y)
336 (or (and (= x 0) (= y 0))
338 (max (abs x) (abs y)))
342 @cindex CL note---integers vrs @code{eq}
344 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
345 @code{=} because Common Lisp implements multi-word integers, and two
346 distinct integer objects can have the same numeric value. Emacs Lisp
347 can have just one integer object for any given value because it has a
348 limited range of integer values.
351 @defun = number-or-marker1 number-or-marker2
352 This function tests whether its arguments are numerically equal, and
353 returns @code{t} if so, @code{nil} otherwise.
356 @defun eql value1 value2
357 This function acts like @code{eq} except when both arguments are
358 numbers. It compares numbers by type and numeric value, so that
359 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
360 @code{(eql 1 1)} both return @code{t}.
363 @defun /= number-or-marker1 number-or-marker2
364 This function tests whether its arguments are numerically equal, and
365 returns @code{t} if they are not, and @code{nil} if they are.
368 @defun < number-or-marker1 number-or-marker2
369 This function tests whether its first argument is strictly less than
370 its second argument. It returns @code{t} if so, @code{nil} otherwise.
373 @defun <= number-or-marker1 number-or-marker2
374 This function tests whether its first argument is less than or equal
375 to its second argument. It returns @code{t} if so, @code{nil}
379 @defun > number-or-marker1 number-or-marker2
380 This function tests whether its first argument is strictly greater
381 than its second argument. It returns @code{t} if so, @code{nil}
385 @defun >= number-or-marker1 number-or-marker2
386 This function tests whether its first argument is greater than or
387 equal to its second argument. It returns @code{t} if so, @code{nil}
391 @defun max number-or-marker &rest numbers-or-markers
392 This function returns the largest of its arguments.
393 If any of the arguments is floating-point, the value is returned
394 as floating point, even if it was given as an integer.
406 @defun min number-or-marker &rest numbers-or-markers
407 This function returns the smallest of its arguments.
408 If any of the arguments is floating-point, the value is returned
409 as floating point, even if it was given as an integer.
418 This function returns the absolute value of @var{number}.
421 @node Numeric Conversions
422 @section Numeric Conversions
423 @cindex rounding in conversions
424 @cindex number conversions
425 @cindex converting numbers
427 To convert an integer to floating point, use the function @code{float}.
430 This returns @var{number} converted to floating point.
431 If @var{number} is already a floating point number, @code{float} returns
435 There are four functions to convert floating point numbers to integers;
436 they differ in how they round. All accept an argument @var{number}
437 and an optional argument @var{divisor}. Both arguments may be
438 integers or floating point numbers. @var{divisor} may also be
439 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
440 functions convert @var{number} to an integer, or return it unchanged
441 if it already is an integer. If @var{divisor} is non-@code{nil}, they
442 divide @var{number} by @var{divisor} and convert the result to an
443 integer. An @code{arith-error} results if @var{divisor} is 0.
445 @defun truncate number &optional divisor
446 This returns @var{number}, converted to an integer by rounding towards
461 @defun floor number &optional divisor
462 This returns @var{number}, converted to an integer by rounding downward
463 (towards negative infinity).
465 If @var{divisor} is specified, this uses the kind of division
466 operation that corresponds to @code{mod}, rounding downward.
482 @defun ceiling number &optional divisor
483 This returns @var{number}, converted to an integer by rounding upward
484 (towards positive infinity).
498 @defun round number &optional divisor
499 This returns @var{number}, converted to an integer by rounding towards the
500 nearest integer. Rounding a value equidistant between two integers
501 may choose the integer closer to zero, or it may prefer an even integer,
502 depending on your machine.
516 @node Arithmetic Operations
517 @section Arithmetic Operations
518 @cindex arithmetic operations
520 Emacs Lisp provides the traditional four arithmetic operations:
521 addition, subtraction, multiplication, and division. Remainder and modulus
522 functions supplement the division functions. The functions to
523 add or subtract 1 are provided because they are traditional in Lisp and
526 All of these functions except @code{%} return a floating point value
527 if any argument is floating.
529 It is important to note that in Emacs Lisp, arithmetic functions
530 do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to
531 @minus{}536870912, depending on your hardware.
533 @defun 1+ number-or-marker
534 This function returns @var{number-or-marker} plus 1.
544 This function is not analogous to the C operator @code{++}---it does not
545 increment a variable. It just computes a sum. Thus, if we continue,
552 If you want to increment the variable, you must use @code{setq},
561 @defun 1- number-or-marker
562 This function returns @var{number-or-marker} minus 1.
565 @defun + &rest numbers-or-markers
566 This function adds its arguments together. When given no arguments,
579 @defun - &optional number-or-marker &rest more-numbers-or-markers
580 The @code{-} function serves two purposes: negation and subtraction.
581 When @code{-} has a single argument, the value is the negative of the
582 argument. When there are multiple arguments, @code{-} subtracts each of
583 the @var{more-numbers-or-markers} from @var{number-or-marker},
584 cumulatively. If there are no arguments, the result is 0.
596 @defun * &rest numbers-or-markers
597 This function multiplies its arguments together, and returns the
598 product. When given no arguments, @code{*} returns 1.
610 @defun / dividend divisor &rest divisors
611 This function divides @var{dividend} by @var{divisor} and returns the
612 quotient. If there are additional arguments @var{divisors}, then it
613 divides @var{dividend} by each divisor in turn. Each argument may be a
616 If all the arguments are integers, then the result is an integer too.
617 This means the result has to be rounded. On most machines, the result
618 is rounded towards zero after each division, but some machines may round
619 differently with negative arguments. This is because the Lisp function
620 @code{/} is implemented using the C division operator, which also
621 permits machine-dependent rounding. As a practical matter, all known
622 machines round in the standard fashion.
624 @cindex @code{arith-error} in division
625 If you divide an integer by 0, an @code{arith-error} error is signaled.
626 (@xref{Errors}.) Floating point division by zero returns either
627 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
628 otherwise, it signals an @code{arith-error} error.
647 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
652 @defun % dividend divisor
654 This function returns the integer remainder after division of @var{dividend}
655 by @var{divisor}. The arguments must be integers or markers.
657 For negative arguments, the remainder is in principle machine-dependent
658 since the quotient is; but in practice, all known machines behave alike.
660 An @code{arith-error} results if @var{divisor} is 0.
673 For any two integers @var{dividend} and @var{divisor},
677 (+ (% @var{dividend} @var{divisor})
678 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
683 always equals @var{dividend}.
686 @defun mod dividend divisor
688 This function returns the value of @var{dividend} modulo @var{divisor};
689 in other words, the remainder after division of @var{dividend}
690 by @var{divisor}, but with the same sign as @var{divisor}.
691 The arguments must be numbers or markers.
693 Unlike @code{%}, @code{mod} returns a well-defined result for negative
694 arguments. It also permits floating point arguments; it rounds the
695 quotient downward (towards minus infinity) to an integer, and uses that
696 quotient to compute the remainder.
698 An @code{arith-error} results if @var{divisor} is 0.
723 For any two numbers @var{dividend} and @var{divisor},
727 (+ (mod @var{dividend} @var{divisor})
728 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
733 always equals @var{dividend}, subject to rounding error if either
734 argument is floating point. For @code{floor}, see @ref{Numeric
738 @node Rounding Operations
739 @section Rounding Operations
740 @cindex rounding without conversion
742 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
743 @code{ftruncate} take a floating point argument and return a floating
744 point result whose value is a nearby integer. @code{ffloor} returns the
745 nearest integer below; @code{fceiling}, the nearest integer above;
746 @code{ftruncate}, the nearest integer in the direction towards zero;
747 @code{fround}, the nearest integer.
750 This function rounds @var{float} to the next lower integral value, and
751 returns that value as a floating point number.
754 @defun fceiling float
755 This function rounds @var{float} to the next higher integral value, and
756 returns that value as a floating point number.
759 @defun ftruncate float
760 This function rounds @var{float} towards zero to an integral value, and
761 returns that value as a floating point number.
765 This function rounds @var{float} to the nearest integral value,
766 and returns that value as a floating point number.
769 @node Bitwise Operations
770 @section Bitwise Operations on Integers
771 @cindex bitwise arithmetic
772 @cindex logical arithmetic
774 In a computer, an integer is represented as a binary number, a
775 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
776 operation acts on the individual bits of such a sequence. For example,
777 @dfn{shifting} moves the whole sequence left or right one or more places,
778 reproducing the same pattern ``moved over''.
780 The bitwise operations in Emacs Lisp apply only to integers.
782 @defun lsh integer1 count
783 @cindex logical shift
784 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
785 bits in @var{integer1} to the left @var{count} places, or to the right
786 if @var{count} is negative, bringing zeros into the vacated bits. If
787 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
788 (most-significant) bit, producing a positive result even if
789 @var{integer1} is negative. Contrast this with @code{ash}, below.
791 Here are two examples of @code{lsh}, shifting a pattern of bits one
792 place to the left. We show only the low-order eight bits of the binary
793 pattern; the rest are all zero.
799 ;; @r{Decimal 5 becomes decimal 10.}
800 00000101 @result{} 00001010
804 ;; @r{Decimal 7 becomes decimal 14.}
805 00000111 @result{} 00001110
810 As the examples illustrate, shifting the pattern of bits one place to
811 the left produces a number that is twice the value of the previous
814 Shifting a pattern of bits two places to the left produces results
815 like this (with 8-bit binary numbers):
821 ;; @r{Decimal 3 becomes decimal 12.}
822 00000011 @result{} 00001100
826 On the other hand, shifting one place to the right looks like this:
832 ;; @r{Decimal 6 becomes decimal 3.}
833 00000110 @result{} 00000011
839 ;; @r{Decimal 5 becomes decimal 2.}
840 00000101 @result{} 00000010
845 As the example illustrates, shifting one place to the right divides the
846 value of a positive integer by two, rounding downward.
848 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
849 not check for overflow, so shifting left can discard significant bits
850 and change the sign of the number. For example, left shifting
851 536,870,911 produces @minus{}2 in the 30-bit implementation:
854 (lsh 536870911 1) ; @r{left shift}
858 In binary, the argument looks like this:
862 ;; @r{Decimal 536,870,911}
863 0111...111111 (30 bits total)
868 which becomes the following when left shifted:
872 ;; @r{Decimal @minus{}2}
873 1111...111110 (30 bits total)
878 @defun ash integer1 count
879 @cindex arithmetic shift
880 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
881 to the left @var{count} places, or to the right if @var{count}
884 @code{ash} gives the same results as @code{lsh} except when
885 @var{integer1} and @var{count} are both negative. In that case,
886 @code{ash} puts ones in the empty bit positions on the left, while
887 @code{lsh} puts zeros in those bit positions.
889 Thus, with @code{ash}, shifting the pattern of bits one place to the right
894 (ash -6 -1) @result{} -3
895 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
896 1111...111010 (30 bits total)
898 1111...111101 (30 bits total)
902 In contrast, shifting the pattern of bits one place to the right with
903 @code{lsh} looks like this:
907 (lsh -6 -1) @result{} 536870909
908 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
909 1111...111010 (30 bits total)
911 0111...111101 (30 bits total)
915 Here are other examples:
917 @c !!! Check if lined up in smallbook format! XDVI shows problem
918 @c with smallbook but not with regular book! --rjc 16mar92
921 ; @r{ 30-bit binary values}
923 (lsh 5 2) ; 5 = @r{0000...000101}
924 @result{} 20 ; = @r{0000...010100}
929 (lsh -5 2) ; -5 = @r{1111...111011}
930 @result{} -20 ; = @r{1111...101100}
935 (lsh 5 -2) ; 5 = @r{0000...000101}
936 @result{} 1 ; = @r{0000...000001}
943 (lsh -5 -2) ; -5 = @r{1111...111011}
945 ; = @r{0011...111110}
948 (ash -5 -2) ; -5 = @r{1111...111011}
949 @result{} -2 ; = @r{1111...111110}
954 @defun logand &rest ints-or-markers
955 This function returns the ``logical and'' of the arguments: the
956 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
957 set in all the arguments. (``Set'' means that the value of the bit is 1
960 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
961 12 is 12: 1101 combined with 1100 produces 1100.
962 In both the binary numbers, the leftmost two bits are set (i.e., they
963 are 1's), so the leftmost two bits of the returned value are set.
964 However, for the rightmost two bits, each is zero in at least one of
965 the arguments, so the rightmost two bits of the returned value are 0's.
977 If @code{logand} is not passed any argument, it returns a value of
978 @minus{}1. This number is an identity element for @code{logand}
979 because its binary representation consists entirely of ones. If
980 @code{logand} is passed just one argument, it returns that argument.
984 ; @r{ 30-bit binary values}
986 (logand 14 13) ; 14 = @r{0000...001110}
987 ; 13 = @r{0000...001101}
988 @result{} 12 ; 12 = @r{0000...001100}
992 (logand 14 13 4) ; 14 = @r{0000...001110}
993 ; 13 = @r{0000...001101}
994 ; 4 = @r{0000...000100}
995 @result{} 4 ; 4 = @r{0000...000100}
1000 @result{} -1 ; -1 = @r{1111...111111}
1005 @defun logior &rest ints-or-markers
1006 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
1007 is set in the result if, and only if, the @var{n}th bit is set in at least
1008 one of the arguments. If there are no arguments, the result is zero,
1009 which is an identity element for this operation. If @code{logior} is
1010 passed just one argument, it returns that argument.
1014 ; @r{ 30-bit binary values}
1016 (logior 12 5) ; 12 = @r{0000...001100}
1017 ; 5 = @r{0000...000101}
1018 @result{} 13 ; 13 = @r{0000...001101}
1022 (logior 12 5 7) ; 12 = @r{0000...001100}
1023 ; 5 = @r{0000...000101}
1024 ; 7 = @r{0000...000111}
1025 @result{} 15 ; 15 = @r{0000...001111}
1030 @defun logxor &rest ints-or-markers
1031 This function returns the ``exclusive or'' of its arguments: the
1032 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1033 set in an odd number of the arguments. If there are no arguments, the
1034 result is 0, which is an identity element for this operation. If
1035 @code{logxor} is passed just one argument, it returns that argument.
1039 ; @r{ 30-bit binary values}
1041 (logxor 12 5) ; 12 = @r{0000...001100}
1042 ; 5 = @r{0000...000101}
1043 @result{} 9 ; 9 = @r{0000...001001}
1047 (logxor 12 5 7) ; 12 = @r{0000...001100}
1048 ; 5 = @r{0000...000101}
1049 ; 7 = @r{0000...000111}
1050 @result{} 14 ; 14 = @r{0000...001110}
1055 @defun lognot integer
1056 This function returns the logical complement of its argument: the @var{n}th
1057 bit is one in the result if, and only if, the @var{n}th bit is zero in
1058 @var{integer}, and vice-versa.
1063 ;; 5 = @r{0000...000101} (30 bits total)
1065 ;; -6 = @r{1111...111010} (30 bits total)
1069 @node Math Functions
1070 @section Standard Mathematical Functions
1071 @cindex transcendental functions
1072 @cindex mathematical functions
1073 @cindex floating-point functions
1075 These mathematical functions allow integers as well as floating point
1076 numbers as arguments.
1081 These are the ordinary trigonometric functions, with argument measured
1086 The value of @code{(asin @var{arg})} is a number between
1100 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1101 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1105 The value of @code{(acos @var{arg})} is a number between 0 and
1112 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1113 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1116 @defun atan y &optional x
1117 The value of @code{(atan @var{y})} is a number between
1131 (exclusive) whose tangent is @var{y}. If the optional second
1132 argument @var{x} is given, the value of @code{(atan y x)} is the
1133 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1138 This is the exponential function; it returns @math{e} to the power
1142 @defun log arg &optional base
1143 This function returns the logarithm of @var{arg}, with base
1144 @var{base}. If you don't specify @var{base}, the natural base
1145 @math{e} is used. If @var{arg} is negative, it signals a
1146 @code{domain-error} error.
1151 This function returns @code{(1- (exp @var{arg}))}, but it is more
1152 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1157 This function returns @code{(log (1+ @var{arg}))}, but it is more
1158 accurate than that when @var{arg} is so small that adding 1 to it would
1164 This function returns the logarithm of @var{arg}, with base 10. If
1165 @var{arg} is negative, it signals a @code{domain-error} error.
1166 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1171 This function returns @var{x} raised to power @var{y}. If both
1172 arguments are integers and @var{y} is positive, the result is an
1173 integer; in this case, overflow causes truncation, so watch out.
1177 This returns the square root of @var{arg}. If @var{arg} is negative,
1178 it signals a @code{domain-error} error.
1181 In addition, Emacs defines the following common mathematical
1185 The mathematical constant @math{e} (2.71828@dots{}).
1189 The mathematical constant @math{pi} (3.14159@dots{}).
1192 @node Random Numbers
1193 @section Random Numbers
1194 @cindex random numbers
1196 A deterministic computer program cannot generate true random numbers.
1197 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1198 pseudo-random numbers is generated in a deterministic fashion. The
1199 numbers are not truly random, but they have certain properties that
1200 mimic a random series. For example, all possible values occur equally
1201 often in a pseudo-random series.
1203 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1204 Starting from any given seed, the @code{random} function always
1205 generates the same sequence of numbers. Emacs always starts with the
1206 same seed value, so the sequence of values of @code{random} is actually
1207 the same in each Emacs run! For example, in one operating system, the
1208 first call to @code{(random)} after you start Emacs always returns
1209 @minus{}1457731, and the second one always returns @minus{}7692030. This
1210 repeatability is helpful for debugging.
1212 If you want random numbers that don't always come out the same, execute
1213 @code{(random t)}. This chooses a new seed based on the current time of
1214 day and on Emacs's process @acronym{ID} number.
1216 @defun random &optional limit
1217 This function returns a pseudo-random integer. Repeated calls return a
1218 series of pseudo-random integers.
1220 If @var{limit} is a positive integer, the value is chosen to be
1221 nonnegative and less than @var{limit}.
1223 If @var{limit} is @code{t}, it means to choose a new seed based on the
1224 current time of day and on Emacs's process @acronym{ID} number.
1226 On some machines, any integer representable in Lisp may be the result
1227 of @code{random}. On other machines, the result can never be larger
1228 than a certain maximum or less than a certain (negative) minimum.