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.
271 @code{floatp} does not exist in Emacs versions 18 and earlier.
274 @defun integerp object
275 This predicate tests whether its argument is an integer, and returns
276 @code{t} if so, @code{nil} otherwise.
279 @defun numberp object
280 This predicate tests whether its argument is a number (either integer or
281 floating point), and returns @code{t} if so, @code{nil} otherwise.
284 @defun natnump object
285 @cindex natural numbers
286 This predicate (whose name comes from the phrase ``natural number'')
287 tests to see whether its argument is a nonnegative integer, and
288 returns @code{t} if so, @code{nil} otherwise. 0 is considered
291 @findex wholenump number
292 This is a synonym for @code{natnump}.
296 This predicate tests whether its argument is zero, and returns @code{t}
297 if so, @code{nil} otherwise. The argument must be a number.
299 @code{(zerop x)} is equivalent to @code{(= x 0)}.
302 @node Comparison of Numbers
303 @section Comparison of Numbers
304 @cindex number comparison
305 @cindex comparing numbers
307 To test numbers for numerical equality, you should normally use
308 @code{=}, not @code{eq}. There can be many distinct floating point
309 number objects with the same numeric value. If you use @code{eq} to
310 compare them, then you test whether two values are the same
311 @emph{object}. By contrast, @code{=} compares only the numeric values
314 At present, each integer value has a unique Lisp object in Emacs Lisp.
315 Therefore, @code{eq} is equivalent to @code{=} where integers are
316 concerned. It is sometimes convenient to use @code{eq} for comparing an
317 unknown value with an integer, because @code{eq} does not report an
318 error if the unknown value is not a number---it accepts arguments of any
319 type. By contrast, @code{=} signals an error if the arguments are not
320 numbers or markers. However, it is a good idea to use @code{=} if you
321 can, even for comparing integers, just in case we change the
322 representation of integers in a future Emacs version.
324 Sometimes it is useful to compare numbers with @code{equal}; it
325 treats two numbers as equal if they have the same data type (both
326 integers, or both floating point) and the same value. By contrast,
327 @code{=} can treat an integer and a floating point number as equal.
328 @xref{Equality Predicates}.
330 There is another wrinkle: because floating point arithmetic is not
331 exact, it is often a bad idea to check for equality of two floating
332 point values. Usually it is better to test for approximate equality.
333 Here's a function to do this:
336 (defvar fuzz-factor 1.0e-6)
337 (defun approx-equal (x y)
338 (or (and (= x 0) (= y 0))
340 (max (abs x) (abs y)))
344 @cindex CL note---integers vrs @code{eq}
346 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
347 @code{=} because Common Lisp implements multi-word integers, and two
348 distinct integer objects can have the same numeric value. Emacs Lisp
349 can have just one integer object for any given value because it has a
350 limited range of integer values.
353 @defun = number-or-marker1 number-or-marker2
354 This function tests whether its arguments are numerically equal, and
355 returns @code{t} if so, @code{nil} otherwise.
358 @defun eql value1 value2
359 This function acts like @code{eq} except when both arguments are
360 numbers. It compares numbers by type and numeric value, so that
361 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
362 @code{(eql 1 1)} both return @code{t}.
365 @defun /= number-or-marker1 number-or-marker2
366 This function tests whether its arguments are numerically equal, and
367 returns @code{t} if they are not, and @code{nil} if they are.
370 @defun < number-or-marker1 number-or-marker2
371 This function tests whether its first argument is strictly less than
372 its second argument. It returns @code{t} if so, @code{nil} otherwise.
375 @defun <= number-or-marker1 number-or-marker2
376 This function tests whether its first argument is less than or equal
377 to its second argument. It returns @code{t} if so, @code{nil}
381 @defun > number-or-marker1 number-or-marker2
382 This function tests whether its first argument is strictly greater
383 than its second argument. It returns @code{t} if so, @code{nil}
387 @defun >= number-or-marker1 number-or-marker2
388 This function tests whether its first argument is greater than or
389 equal to its second argument. It returns @code{t} if so, @code{nil}
393 @defun max number-or-marker &rest numbers-or-markers
394 This function returns the largest of its arguments.
395 If any of the arguments is floating-point, the value is returned
396 as floating point, even if it was given as an integer.
408 @defun min number-or-marker &rest numbers-or-markers
409 This function returns the smallest of its arguments.
410 If any of the arguments is floating-point, the value is returned
411 as floating point, even if it was given as an integer.
420 This function returns the absolute value of @var{number}.
423 @node Numeric Conversions
424 @section Numeric Conversions
425 @cindex rounding in conversions
426 @cindex number conversions
427 @cindex converting numbers
429 To convert an integer to floating point, use the function @code{float}.
432 This returns @var{number} converted to floating point.
433 If @var{number} is already a floating point number, @code{float} returns
437 There are four functions to convert floating point numbers to integers;
438 they differ in how they round. All accept an argument @var{number}
439 and an optional argument @var{divisor}. Both arguments may be
440 integers or floating point numbers. @var{divisor} may also be
441 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
442 functions convert @var{number} to an integer, or return it unchanged
443 if it already is an integer. If @var{divisor} is non-@code{nil}, they
444 divide @var{number} by @var{divisor} and convert the result to an
445 integer. An @code{arith-error} results if @var{divisor} is 0.
447 @defun truncate number &optional divisor
448 This returns @var{number}, converted to an integer by rounding towards
463 @defun floor number &optional divisor
464 This returns @var{number}, converted to an integer by rounding downward
465 (towards negative infinity).
467 If @var{divisor} is specified, this uses the kind of division
468 operation that corresponds to @code{mod}, rounding downward.
484 @defun ceiling number &optional divisor
485 This returns @var{number}, converted to an integer by rounding upward
486 (towards positive infinity).
500 @defun round number &optional divisor
501 This returns @var{number}, converted to an integer by rounding towards the
502 nearest integer. Rounding a value equidistant between two integers
503 may choose the integer closer to zero, or it may prefer an even integer,
504 depending on your machine.
518 @node Arithmetic Operations
519 @section Arithmetic Operations
520 @cindex arithmetic operations
522 Emacs Lisp provides the traditional four arithmetic operations:
523 addition, subtraction, multiplication, and division. Remainder and modulus
524 functions supplement the division functions. The functions to
525 add or subtract 1 are provided because they are traditional in Lisp and
528 All of these functions except @code{%} return a floating point value
529 if any argument is floating.
531 It is important to note that in Emacs Lisp, arithmetic functions
532 do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to
533 @minus{}536870912, depending on your hardware.
535 @defun 1+ number-or-marker
536 This function returns @var{number-or-marker} plus 1.
546 This function is not analogous to the C operator @code{++}---it does not
547 increment a variable. It just computes a sum. Thus, if we continue,
554 If you want to increment the variable, you must use @code{setq},
563 @defun 1- number-or-marker
564 This function returns @var{number-or-marker} minus 1.
567 @defun + &rest numbers-or-markers
568 This function adds its arguments together. When given no arguments,
581 @defun - &optional number-or-marker &rest more-numbers-or-markers
582 The @code{-} function serves two purposes: negation and subtraction.
583 When @code{-} has a single argument, the value is the negative of the
584 argument. When there are multiple arguments, @code{-} subtracts each of
585 the @var{more-numbers-or-markers} from @var{number-or-marker},
586 cumulatively. If there are no arguments, the result is 0.
598 @defun * &rest numbers-or-markers
599 This function multiplies its arguments together, and returns the
600 product. When given no arguments, @code{*} returns 1.
612 @defun / dividend divisor &rest divisors
613 This function divides @var{dividend} by @var{divisor} and returns the
614 quotient. If there are additional arguments @var{divisors}, then it
615 divides @var{dividend} by each divisor in turn. Each argument may be a
618 If all the arguments are integers, then the result is an integer too.
619 This means the result has to be rounded. On most machines, the result
620 is rounded towards zero after each division, but some machines may round
621 differently with negative arguments. This is because the Lisp function
622 @code{/} is implemented using the C division operator, which also
623 permits machine-dependent rounding. As a practical matter, all known
624 machines round in the standard fashion.
626 @cindex @code{arith-error} in division
627 If you divide an integer by 0, an @code{arith-error} error is signaled.
628 (@xref{Errors}.) Floating point division by zero returns either
629 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
630 otherwise, it signals an @code{arith-error} error.
649 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
654 @defun % dividend divisor
656 This function returns the integer remainder after division of @var{dividend}
657 by @var{divisor}. The arguments must be integers or markers.
659 For negative arguments, the remainder is in principle machine-dependent
660 since the quotient is; but in practice, all known machines behave alike.
662 An @code{arith-error} results if @var{divisor} is 0.
675 For any two integers @var{dividend} and @var{divisor},
679 (+ (% @var{dividend} @var{divisor})
680 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
685 always equals @var{dividend}.
688 @defun mod dividend divisor
690 This function returns the value of @var{dividend} modulo @var{divisor};
691 in other words, the remainder after division of @var{dividend}
692 by @var{divisor}, but with the same sign as @var{divisor}.
693 The arguments must be numbers or markers.
695 Unlike @code{%}, @code{mod} returns a well-defined result for negative
696 arguments. It also permits floating point arguments; it rounds the
697 quotient downward (towards minus infinity) to an integer, and uses that
698 quotient to compute the remainder.
700 An @code{arith-error} results if @var{divisor} is 0.
725 For any two numbers @var{dividend} and @var{divisor},
729 (+ (mod @var{dividend} @var{divisor})
730 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
735 always equals @var{dividend}, subject to rounding error if either
736 argument is floating point. For @code{floor}, see @ref{Numeric
740 @node Rounding Operations
741 @section Rounding Operations
742 @cindex rounding without conversion
744 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
745 @code{ftruncate} take a floating point argument and return a floating
746 point result whose value is a nearby integer. @code{ffloor} returns the
747 nearest integer below; @code{fceiling}, the nearest integer above;
748 @code{ftruncate}, the nearest integer in the direction towards zero;
749 @code{fround}, the nearest integer.
752 This function rounds @var{float} to the next lower integral value, and
753 returns that value as a floating point number.
756 @defun fceiling float
757 This function rounds @var{float} to the next higher integral value, and
758 returns that value as a floating point number.
761 @defun ftruncate float
762 This function rounds @var{float} towards zero to an integral value, and
763 returns that value as a floating point number.
767 This function rounds @var{float} to the nearest integral value,
768 and returns that value as a floating point number.
771 @node Bitwise Operations
772 @section Bitwise Operations on Integers
773 @cindex bitwise arithmetic
774 @cindex logical arithmetic
776 In a computer, an integer is represented as a binary number, a
777 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
778 operation acts on the individual bits of such a sequence. For example,
779 @dfn{shifting} moves the whole sequence left or right one or more places,
780 reproducing the same pattern ``moved over''.
782 The bitwise operations in Emacs Lisp apply only to integers.
784 @defun lsh integer1 count
785 @cindex logical shift
786 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
787 bits in @var{integer1} to the left @var{count} places, or to the right
788 if @var{count} is negative, bringing zeros into the vacated bits. If
789 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
790 (most-significant) bit, producing a positive result even if
791 @var{integer1} is negative. Contrast this with @code{ash}, below.
793 Here are two examples of @code{lsh}, shifting a pattern of bits one
794 place to the left. We show only the low-order eight bits of the binary
795 pattern; the rest are all zero.
801 ;; @r{Decimal 5 becomes decimal 10.}
802 00000101 @result{} 00001010
806 ;; @r{Decimal 7 becomes decimal 14.}
807 00000111 @result{} 00001110
812 As the examples illustrate, shifting the pattern of bits one place to
813 the left produces a number that is twice the value of the previous
816 Shifting a pattern of bits two places to the left produces results
817 like this (with 8-bit binary numbers):
823 ;; @r{Decimal 3 becomes decimal 12.}
824 00000011 @result{} 00001100
828 On the other hand, shifting one place to the right looks like this:
834 ;; @r{Decimal 6 becomes decimal 3.}
835 00000110 @result{} 00000011
841 ;; @r{Decimal 5 becomes decimal 2.}
842 00000101 @result{} 00000010
847 As the example illustrates, shifting one place to the right divides the
848 value of a positive integer by two, rounding downward.
850 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
851 not check for overflow, so shifting left can discard significant bits
852 and change the sign of the number. For example, left shifting
853 536,870,911 produces @minus{}2 in the 30-bit implementation:
856 (lsh 536870911 1) ; @r{left shift}
860 In binary, the argument looks like this:
864 ;; @r{Decimal 536,870,911}
865 0111...111111 (30 bits total)
870 which becomes the following when left shifted:
874 ;; @r{Decimal @minus{}2}
875 1111...111110 (30 bits total)
880 @defun ash integer1 count
881 @cindex arithmetic shift
882 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
883 to the left @var{count} places, or to the right if @var{count}
886 @code{ash} gives the same results as @code{lsh} except when
887 @var{integer1} and @var{count} are both negative. In that case,
888 @code{ash} puts ones in the empty bit positions on the left, while
889 @code{lsh} puts zeros in those bit positions.
891 Thus, with @code{ash}, shifting the pattern of bits one place to the right
896 (ash -6 -1) @result{} -3
897 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
898 1111...111010 (30 bits total)
900 1111...111101 (30 bits total)
904 In contrast, shifting the pattern of bits one place to the right with
905 @code{lsh} looks like this:
909 (lsh -6 -1) @result{} 536870909
910 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
911 1111...111010 (30 bits total)
913 0111...111101 (30 bits total)
917 Here are other examples:
919 @c !!! Check if lined up in smallbook format! XDVI shows problem
920 @c with smallbook but not with regular book! --rjc 16mar92
923 ; @r{ 30-bit binary values}
925 (lsh 5 2) ; 5 = @r{0000...000101}
926 @result{} 20 ; = @r{0000...010100}
931 (lsh -5 2) ; -5 = @r{1111...111011}
932 @result{} -20 ; = @r{1111...101100}
937 (lsh 5 -2) ; 5 = @r{0000...000101}
938 @result{} 1 ; = @r{0000...000001}
945 (lsh -5 -2) ; -5 = @r{1111...111011}
947 ; = @r{0011...111110}
950 (ash -5 -2) ; -5 = @r{1111...111011}
951 @result{} -2 ; = @r{1111...111110}
956 @defun logand &rest ints-or-markers
957 This function returns the ``logical and'' of the arguments: the
958 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
959 set in all the arguments. (``Set'' means that the value of the bit is 1
962 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
963 12 is 12: 1101 combined with 1100 produces 1100.
964 In both the binary numbers, the leftmost two bits are set (i.e., they
965 are 1's), so the leftmost two bits of the returned value are set.
966 However, for the rightmost two bits, each is zero in at least one of
967 the arguments, so the rightmost two bits of the returned value are 0's.
979 If @code{logand} is not passed any argument, it returns a value of
980 @minus{}1. This number is an identity element for @code{logand}
981 because its binary representation consists entirely of ones. If
982 @code{logand} is passed just one argument, it returns that argument.
986 ; @r{ 30-bit binary values}
988 (logand 14 13) ; 14 = @r{0000...001110}
989 ; 13 = @r{0000...001101}
990 @result{} 12 ; 12 = @r{0000...001100}
994 (logand 14 13 4) ; 14 = @r{0000...001110}
995 ; 13 = @r{0000...001101}
996 ; 4 = @r{0000...000100}
997 @result{} 4 ; 4 = @r{0000...000100}
1002 @result{} -1 ; -1 = @r{1111...111111}
1007 @defun logior &rest ints-or-markers
1008 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
1009 is set in the result if, and only if, the @var{n}th bit is set in at least
1010 one of the arguments. If there are no arguments, the result is zero,
1011 which is an identity element for this operation. If @code{logior} is
1012 passed just one argument, it returns that argument.
1016 ; @r{ 30-bit binary values}
1018 (logior 12 5) ; 12 = @r{0000...001100}
1019 ; 5 = @r{0000...000101}
1020 @result{} 13 ; 13 = @r{0000...001101}
1024 (logior 12 5 7) ; 12 = @r{0000...001100}
1025 ; 5 = @r{0000...000101}
1026 ; 7 = @r{0000...000111}
1027 @result{} 15 ; 15 = @r{0000...001111}
1032 @defun logxor &rest ints-or-markers
1033 This function returns the ``exclusive or'' of its arguments: the
1034 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1035 set in an odd number of the arguments. If there are no arguments, the
1036 result is 0, which is an identity element for this operation. If
1037 @code{logxor} is passed just one argument, it returns that argument.
1041 ; @r{ 30-bit binary values}
1043 (logxor 12 5) ; 12 = @r{0000...001100}
1044 ; 5 = @r{0000...000101}
1045 @result{} 9 ; 9 = @r{0000...001001}
1049 (logxor 12 5 7) ; 12 = @r{0000...001100}
1050 ; 5 = @r{0000...000101}
1051 ; 7 = @r{0000...000111}
1052 @result{} 14 ; 14 = @r{0000...001110}
1057 @defun lognot integer
1058 This function returns the logical complement of its argument: the @var{n}th
1059 bit is one in the result if, and only if, the @var{n}th bit is zero in
1060 @var{integer}, and vice-versa.
1065 ;; 5 = @r{0000...000101} (30 bits total)
1067 ;; -6 = @r{1111...111010} (30 bits total)
1071 @node Math Functions
1072 @section Standard Mathematical Functions
1073 @cindex transcendental functions
1074 @cindex mathematical functions
1075 @cindex floating-point functions
1077 These mathematical functions allow integers as well as floating point
1078 numbers as arguments.
1083 These are the ordinary trigonometric functions, with argument measured
1088 The value of @code{(asin @var{arg})} is a number between
1102 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1103 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1107 The value of @code{(acos @var{arg})} is a number between 0 and
1114 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1115 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1118 @defun atan y &optional x
1119 The value of @code{(atan @var{y})} is a number between
1133 (exclusive) whose tangent is @var{y}. If the optional second
1134 argument @var{x} is given, the value of @code{(atan y x)} is the
1135 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1140 This is the exponential function; it returns @math{e} to the power
1144 @defun log arg &optional base
1145 This function returns the logarithm of @var{arg}, with base
1146 @var{base}. If you don't specify @var{base}, the natural base
1147 @math{e} is used. If @var{arg} is negative, it signals a
1148 @code{domain-error} error.
1153 This function returns @code{(1- (exp @var{arg}))}, but it is more
1154 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1159 This function returns @code{(log (1+ @var{arg}))}, but it is more
1160 accurate than that when @var{arg} is so small that adding 1 to it would
1166 This function returns the logarithm of @var{arg}, with base 10. If
1167 @var{arg} is negative, it signals a @code{domain-error} error.
1168 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1173 This function returns @var{x} raised to power @var{y}. If both
1174 arguments are integers and @var{y} is positive, the result is an
1175 integer; in this case, overflow causes truncation, so watch out.
1179 This returns the square root of @var{arg}. If @var{arg} is negative,
1180 it signals a @code{domain-error} error.
1183 In addition, Emacs defines the following common mathematical
1187 The mathematical constant @math{e} (2.71828@dots{}).
1191 The mathematical constant @math{pi} (3.14159@dots{}).
1194 @node Random Numbers
1195 @section Random Numbers
1196 @cindex random numbers
1198 A deterministic computer program cannot generate true random numbers.
1199 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1200 pseudo-random numbers is generated in a deterministic fashion. The
1201 numbers are not truly random, but they have certain properties that
1202 mimic a random series. For example, all possible values occur equally
1203 often in a pseudo-random series.
1205 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1206 Starting from any given seed, the @code{random} function always
1207 generates the same sequence of numbers. Emacs always starts with the
1208 same seed value, so the sequence of values of @code{random} is actually
1209 the same in each Emacs run! For example, in one operating system, the
1210 first call to @code{(random)} after you start Emacs always returns
1211 @minus{}1457731, and the second one always returns @minus{}7692030. This
1212 repeatability is helpful for debugging.
1214 If you want random numbers that don't always come out the same, execute
1215 @code{(random t)}. This chooses a new seed based on the current time of
1216 day and on Emacs's process @acronym{ID} number.
1218 @defun random &optional limit
1219 This function returns a pseudo-random integer. Repeated calls return a
1220 series of pseudo-random integers.
1222 If @var{limit} is a positive integer, the value is chosen to be
1223 nonnegative and less than @var{limit}.
1225 If @var{limit} is @code{t}, it means to choose a new seed based on the
1226 current time of day and on Emacs's process @acronym{ID} number.
1228 On some machines, any integer representable in Lisp may be the result
1229 of @code{random}. On other machines, the result can never be larger
1230 than a certain maximum or less than a certain (negative) minimum.