2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2011
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/numbers
7 @node Numbers, Strings and Characters, Lisp Data Types, Top
12 GNU Emacs supports two numeric data types: @dfn{integers} and
13 @dfn{floating point numbers}. Integers are whole numbers such as
14 @minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
15 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
16 2.71828. They can also be expressed in exponential notation: 1.5e2
17 equals 150; in this example, @samp{e2} stands for ten to the second
18 power, and that is multiplied by 1.5. Floating point values are not
19 exact; they have a fixed, limited amount of precision.
22 * Integer Basics:: Representation and range of integers.
23 * Float Basics:: Representation and range of floating point.
24 * Predicates on Numbers:: Testing for numbers.
25 * Comparison of Numbers:: Equality and inequality predicates.
26 * Numeric Conversions:: Converting float to integer and vice versa.
27 * Arithmetic Operations:: How to add, subtract, multiply and divide.
28 * Rounding Operations:: Explicitly rounding floating point numbers.
29 * Bitwise Operations:: Logical and, or, not, shifting.
30 * Math Functions:: Trig, exponential and logarithmic functions.
31 * Random Numbers:: Obtaining random integers, predictable or not.
35 @comment node-name, next, previous, up
36 @section Integer Basics
38 The range of values for an integer depends on the machine. The
39 minimum range is @minus{}536870912 to 536870911 (30 bits; i.e.,
53 but some machines may provide a wider range. Many examples in this
54 chapter assume an integer has 30 bits.
57 The Lisp reader reads an integer as a sequence of digits with optional
58 initial sign and optional final period.
61 1 ; @r{The integer 1.}
62 1. ; @r{The integer 1.}
63 +1 ; @r{Also the integer 1.}
64 -1 ; @r{The integer @minus{}1.}
65 1073741825 ; @r{Also the integer 1, due to overflow.}
66 0 ; @r{The integer 0.}
67 -0 ; @r{The integer 0.}
70 @cindex integers in specific radix
71 @cindex radix for reading an integer
72 @cindex base for reading an integer
75 @cindex reading numbers in hex, octal, and binary
76 The syntax for integers in bases other than 10 uses @samp{#}
77 followed by a letter that specifies the radix: @samp{b} for binary,
78 @samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
79 specify radix @var{radix}. Case is not significant for the letter
80 that specifies the radix. Thus, @samp{#b@var{integer}} reads
81 @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
82 @var{integer} in radix @var{radix}. Allowed values of @var{radix} run
83 from 2 to 36. For example:
92 To understand how various functions work on integers, especially the
93 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
94 view the numbers in their binary form.
96 In 30-bit binary, the decimal integer 5 looks like this:
99 00 0000 0000 0000 0000 0000 0000 0101
103 (We have inserted spaces between groups of 4 bits, and two spaces
104 between groups of 8 bits, to make the binary integer easier to read.)
106 The integer @minus{}1 looks like this:
109 11 1111 1111 1111 1111 1111 1111 1111
113 @cindex two's complement
114 @minus{}1 is represented as 30 ones. (This is called @dfn{two's
115 complement} notation.)
117 The negative integer, @minus{}5, is creating by subtracting 4 from
118 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
119 @minus{}5 looks like this:
122 11 1111 1111 1111 1111 1111 1111 1011
125 In this implementation, the largest 30-bit binary integer value is
126 536,870,911 in decimal. In binary, it looks like this:
129 01 1111 1111 1111 1111 1111 1111 1111
132 Since the arithmetic functions do not check whether integers go
133 outside their range, when you add 1 to 536,870,911, the value is the
134 negative integer @minus{}536,870,912:
139 @result{} 10 0000 0000 0000 0000 0000 0000 0000
142 Many of the functions described in this chapter accept markers for
143 arguments in place of numbers. (@xref{Markers}.) Since the actual
144 arguments to such functions may be either numbers or markers, we often
145 give these arguments the name @var{number-or-marker}. When the argument
146 value is a marker, its position value is used and its buffer is ignored.
148 @defvar most-positive-fixnum
149 The value of this variable is the largest integer that Emacs Lisp
153 @defvar most-negative-fixnum
154 The value of this variable is the smallest integer that Emacs Lisp can
155 handle. It is negative.
158 @xref{Character Codes, max-char}, for the maximum value of a valid
162 @section Floating Point Basics
164 Floating point numbers are useful for representing numbers that are
165 not integral. The precise range of floating point numbers is
166 machine-specific; it is the same as the range of the C data type
167 @code{double} on the machine you are using.
169 The read-syntax for floating point numbers requires either a decimal
170 point (with at least one digit following), an exponent, or both. For
171 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
172 @samp{.15e4} are five ways of writing a floating point number whose
173 value is 1500. They are all equivalent. You can also use a minus sign
174 to write negative floating point numbers, as in @samp{-1.0}.
176 @cindex @acronym{IEEE} floating point
177 @cindex positive infinity
178 @cindex negative infinity
181 Most modern computers support the @acronym{IEEE} floating point standard,
182 which provides for positive infinity and negative infinity as floating point
183 values. It also provides for a class of values called NaN or
184 ``not-a-number''; numerical functions return such values in cases where
185 there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a
186 NaN. For practical purposes, there's no significant difference between
187 different NaN values in Emacs Lisp, and there's no rule for precisely
188 which NaN value should be used in a particular case, so Emacs Lisp
189 doesn't try to distinguish them (but it does report the sign, if you
190 print it). Here are the read syntaxes for these special floating
194 @item positive infinity
196 @item negative infinity
199 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
202 To test whether a floating point value is a NaN, compare it with
203 itself using @code{=}. That returns @code{nil} for a NaN, and
204 @code{t} for any other floating point value.
206 The value @code{-0.0} is distinguishable from ordinary zero in
207 @acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
208 @code{=} consider them equal values.
210 You can use @code{logb} to extract the binary exponent of a floating
211 point number (or estimate the logarithm of an integer):
214 This function returns the binary exponent of @var{number}. More
215 precisely, the value is the logarithm of @var{number} base 2, rounded
227 The mathematical constant @math{e} (2.71828@dots{}).
231 The mathematical constant @math{pi} (3.14159@dots{}).
234 @node Predicates on Numbers
235 @section Type Predicates for Numbers
236 @cindex predicates for numbers
238 The functions in this section test for numbers, or for a specific
239 type of number. The functions @code{integerp} and @code{floatp} can
240 take any type of Lisp object as argument (they would not be of much
241 use otherwise), but the @code{zerop} predicate requires a number as
242 its argument. See also @code{integer-or-marker-p} and
243 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
246 This predicate tests whether its argument is a floating point
247 number and returns @code{t} if so, @code{nil} otherwise.
249 @code{floatp} does not exist in Emacs versions 18 and earlier.
252 @defun integerp object
253 This predicate tests whether its argument is an integer, and returns
254 @code{t} if so, @code{nil} otherwise.
257 @defun numberp object
258 This predicate tests whether its argument is a number (either integer or
259 floating point), and returns @code{t} if so, @code{nil} otherwise.
262 @defun wholenump object
263 @cindex natural numbers
264 The @code{wholenump} predicate (whose name comes from the phrase
265 ``whole-number-p'') tests to see whether its argument is a nonnegative
266 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
267 considered non-negative.
270 @code{natnump} is an obsolete synonym for @code{wholenump}.
274 This predicate tests whether its argument is zero, and returns @code{t}
275 if so, @code{nil} otherwise. The argument must be a number.
277 @code{(zerop x)} is equivalent to @code{(= x 0)}.
280 @node Comparison of Numbers
281 @section Comparison of Numbers
282 @cindex number comparison
283 @cindex comparing numbers
285 To test numbers for numerical equality, you should normally use
286 @code{=}, not @code{eq}. There can be many distinct floating point
287 number objects with the same numeric value. If you use @code{eq} to
288 compare them, then you test whether two values are the same
289 @emph{object}. By contrast, @code{=} compares only the numeric values
292 At present, each integer value has a unique Lisp object in Emacs Lisp.
293 Therefore, @code{eq} is equivalent to @code{=} where integers are
294 concerned. It is sometimes convenient to use @code{eq} for comparing an
295 unknown value with an integer, because @code{eq} does not report an
296 error if the unknown value is not a number---it accepts arguments of any
297 type. By contrast, @code{=} signals an error if the arguments are not
298 numbers or markers. However, it is a good idea to use @code{=} if you
299 can, even for comparing integers, just in case we change the
300 representation of integers in a future Emacs version.
302 Sometimes it is useful to compare numbers with @code{equal}; it
303 treats two numbers as equal if they have the same data type (both
304 integers, or both floating point) and the same value. By contrast,
305 @code{=} can treat an integer and a floating point number as equal.
306 @xref{Equality Predicates}.
308 There is another wrinkle: because floating point arithmetic is not
309 exact, it is often a bad idea to check for equality of two floating
310 point values. Usually it is better to test for approximate equality.
311 Here's a function to do this:
314 (defvar fuzz-factor 1.0e-6)
315 (defun approx-equal (x y)
316 (or (and (= x 0) (= y 0))
318 (max (abs x) (abs y)))
322 @cindex CL note---integers vrs @code{eq}
324 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
325 @code{=} because Common Lisp implements multi-word integers, and two
326 distinct integer objects can have the same numeric value. Emacs Lisp
327 can have just one integer object for any given value because it has a
328 limited range of integer values.
331 @defun = number-or-marker1 number-or-marker2
332 This function tests whether its arguments are numerically equal, and
333 returns @code{t} if so, @code{nil} otherwise.
336 @defun eql value1 value2
337 This function acts like @code{eq} except when both arguments are
338 numbers. It compares numbers by type and numeric value, so that
339 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
340 @code{(eql 1 1)} both return @code{t}.
343 @defun /= number-or-marker1 number-or-marker2
344 This function tests whether its arguments are numerically equal, and
345 returns @code{t} if they are not, and @code{nil} if they are.
348 @defun < number-or-marker1 number-or-marker2
349 This function tests whether its first argument is strictly less than
350 its second argument. It returns @code{t} if so, @code{nil} otherwise.
353 @defun <= number-or-marker1 number-or-marker2
354 This function tests whether its first argument is less than or equal
355 to its second argument. It returns @code{t} if so, @code{nil}
359 @defun > number-or-marker1 number-or-marker2
360 This function tests whether its first argument is strictly greater
361 than its second argument. It returns @code{t} if so, @code{nil}
365 @defun >= number-or-marker1 number-or-marker2
366 This function tests whether its first argument is greater than or
367 equal to its second argument. It returns @code{t} if so, @code{nil}
371 @defun max number-or-marker &rest numbers-or-markers
372 This function returns the largest of its arguments.
373 If any of the arguments is floating-point, the value is returned
374 as floating point, even if it was given as an integer.
386 @defun min number-or-marker &rest numbers-or-markers
387 This function returns the smallest of its arguments.
388 If any of the arguments is floating-point, the value is returned
389 as floating point, even if it was given as an integer.
398 This function returns the absolute value of @var{number}.
401 @node Numeric Conversions
402 @section Numeric Conversions
403 @cindex rounding in conversions
404 @cindex number conversions
405 @cindex converting numbers
407 To convert an integer to floating point, use the function @code{float}.
410 This returns @var{number} converted to floating point.
411 If @var{number} is already a floating point number, @code{float} returns
415 There are four functions to convert floating point numbers to integers;
416 they differ in how they round. All accept an argument @var{number}
417 and an optional argument @var{divisor}. Both arguments may be
418 integers or floating point numbers. @var{divisor} may also be
419 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
420 functions convert @var{number} to an integer, or return it unchanged
421 if it already is an integer. If @var{divisor} is non-@code{nil}, they
422 divide @var{number} by @var{divisor} and convert the result to an
423 integer. An @code{arith-error} results if @var{divisor} is 0.
425 @defun truncate number &optional divisor
426 This returns @var{number}, converted to an integer by rounding towards
441 @defun floor number &optional divisor
442 This returns @var{number}, converted to an integer by rounding downward
443 (towards negative infinity).
445 If @var{divisor} is specified, this uses the kind of division
446 operation that corresponds to @code{mod}, rounding downward.
462 @defun ceiling number &optional divisor
463 This returns @var{number}, converted to an integer by rounding upward
464 (towards positive infinity).
478 @defun round number &optional divisor
479 This returns @var{number}, converted to an integer by rounding towards the
480 nearest integer. Rounding a value equidistant between two integers
481 may choose the integer closer to zero, or it may prefer an even integer,
482 depending on your machine.
496 @node Arithmetic Operations
497 @section Arithmetic Operations
498 @cindex arithmetic operations
500 Emacs Lisp provides the traditional four arithmetic operations:
501 addition, subtraction, multiplication, and division. Remainder and modulus
502 functions supplement the division functions. The functions to
503 add or subtract 1 are provided because they are traditional in Lisp and
506 All of these functions except @code{%} return a floating point value
507 if any argument is floating.
509 It is important to note that in Emacs Lisp, arithmetic functions
510 do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to
511 @minus{}268435456, depending on your hardware.
513 @defun 1+ number-or-marker
514 This function returns @var{number-or-marker} plus 1.
524 This function is not analogous to the C operator @code{++}---it does not
525 increment a variable. It just computes a sum. Thus, if we continue,
532 If you want to increment the variable, you must use @code{setq},
541 @defun 1- number-or-marker
542 This function returns @var{number-or-marker} minus 1.
545 @defun + &rest numbers-or-markers
546 This function adds its arguments together. When given no arguments,
559 @defun - &optional number-or-marker &rest more-numbers-or-markers
560 The @code{-} function serves two purposes: negation and subtraction.
561 When @code{-} has a single argument, the value is the negative of the
562 argument. When there are multiple arguments, @code{-} subtracts each of
563 the @var{more-numbers-or-markers} from @var{number-or-marker},
564 cumulatively. If there are no arguments, the result is 0.
576 @defun * &rest numbers-or-markers
577 This function multiplies its arguments together, and returns the
578 product. When given no arguments, @code{*} returns 1.
590 @defun / dividend divisor &rest divisors
591 This function divides @var{dividend} by @var{divisor} and returns the
592 quotient. If there are additional arguments @var{divisors}, then it
593 divides @var{dividend} by each divisor in turn. Each argument may be a
596 If all the arguments are integers, then the result is an integer too.
597 This means the result has to be rounded. On most machines, the result
598 is rounded towards zero after each division, but some machines may round
599 differently with negative arguments. This is because the Lisp function
600 @code{/} is implemented using the C division operator, which also
601 permits machine-dependent rounding. As a practical matter, all known
602 machines round in the standard fashion.
604 @cindex @code{arith-error} in division
605 If you divide an integer by 0, an @code{arith-error} error is signaled.
606 (@xref{Errors}.) Floating point division by zero returns either
607 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
608 otherwise, it signals an @code{arith-error} error.
627 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
632 @defun % dividend divisor
634 This function returns the integer remainder after division of @var{dividend}
635 by @var{divisor}. The arguments must be integers or markers.
637 For negative arguments, the remainder is in principle machine-dependent
638 since the quotient is; but in practice, all known machines behave alike.
640 An @code{arith-error} results if @var{divisor} is 0.
653 For any two integers @var{dividend} and @var{divisor},
657 (+ (% @var{dividend} @var{divisor})
658 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
663 always equals @var{dividend}.
666 @defun mod dividend divisor
668 This function returns the value of @var{dividend} modulo @var{divisor};
669 in other words, the remainder after division of @var{dividend}
670 by @var{divisor}, but with the same sign as @var{divisor}.
671 The arguments must be numbers or markers.
673 Unlike @code{%}, @code{mod} returns a well-defined result for negative
674 arguments. It also permits floating point arguments; it rounds the
675 quotient downward (towards minus infinity) to an integer, and uses that
676 quotient to compute the remainder.
678 An @code{arith-error} results if @var{divisor} is 0.
703 For any two numbers @var{dividend} and @var{divisor},
707 (+ (mod @var{dividend} @var{divisor})
708 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
713 always equals @var{dividend}, subject to rounding error if either
714 argument is floating point. For @code{floor}, see @ref{Numeric
718 @node Rounding Operations
719 @section Rounding Operations
720 @cindex rounding without conversion
722 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
723 @code{ftruncate} take a floating point argument and return a floating
724 point result whose value is a nearby integer. @code{ffloor} returns the
725 nearest integer below; @code{fceiling}, the nearest integer above;
726 @code{ftruncate}, the nearest integer in the direction towards zero;
727 @code{fround}, the nearest integer.
730 This function rounds @var{float} to the next lower integral value, and
731 returns that value as a floating point number.
734 @defun fceiling float
735 This function rounds @var{float} to the next higher integral value, and
736 returns that value as a floating point number.
739 @defun ftruncate float
740 This function rounds @var{float} towards zero to an integral value, and
741 returns that value as a floating point number.
745 This function rounds @var{float} to the nearest integral value,
746 and returns that value as a floating point number.
749 @node Bitwise Operations
750 @section Bitwise Operations on Integers
751 @cindex bitwise arithmetic
752 @cindex logical arithmetic
754 In a computer, an integer is represented as a binary number, a
755 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
756 operation acts on the individual bits of such a sequence. For example,
757 @dfn{shifting} moves the whole sequence left or right one or more places,
758 reproducing the same pattern ``moved over.''
760 The bitwise operations in Emacs Lisp apply only to integers.
762 @defun lsh integer1 count
763 @cindex logical shift
764 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
765 bits in @var{integer1} to the left @var{count} places, or to the right
766 if @var{count} is negative, bringing zeros into the vacated bits. If
767 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
768 (most-significant) bit, producing a positive result even if
769 @var{integer1} is negative. Contrast this with @code{ash}, below.
771 Here are two examples of @code{lsh}, shifting a pattern of bits one
772 place to the left. We show only the low-order eight bits of the binary
773 pattern; the rest are all zero.
779 ;; @r{Decimal 5 becomes decimal 10.}
780 00000101 @result{} 00001010
784 ;; @r{Decimal 7 becomes decimal 14.}
785 00000111 @result{} 00001110
790 As the examples illustrate, shifting the pattern of bits one place to
791 the left produces a number that is twice the value of the previous
794 Shifting a pattern of bits two places to the left produces results
795 like this (with 8-bit binary numbers):
801 ;; @r{Decimal 3 becomes decimal 12.}
802 00000011 @result{} 00001100
806 On the other hand, shifting one place to the right looks like this:
812 ;; @r{Decimal 6 becomes decimal 3.}
813 00000110 @result{} 00000011
819 ;; @r{Decimal 5 becomes decimal 2.}
820 00000101 @result{} 00000010
825 As the example illustrates, shifting one place to the right divides the
826 value of a positive integer by two, rounding downward.
828 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
829 not check for overflow, so shifting left can discard significant bits
830 and change the sign of the number. For example, left shifting
831 536,870,911 produces @minus{}2 on a 30-bit machine:
834 (lsh 536870911 1) ; @r{left shift}
838 In binary, in the 30-bit implementation, the argument looks like this:
842 ;; @r{Decimal 536,870,911}
843 01 1111 1111 1111 1111 1111 1111 1111
848 which becomes the following when left shifted:
852 ;; @r{Decimal @minus{}2}
853 11 1111 1111 1111 1111 1111 1111 1110
858 @defun ash integer1 count
859 @cindex arithmetic shift
860 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
861 to the left @var{count} places, or to the right if @var{count}
864 @code{ash} gives the same results as @code{lsh} except when
865 @var{integer1} and @var{count} are both negative. In that case,
866 @code{ash} puts ones in the empty bit positions on the left, while
867 @code{lsh} puts zeros in those bit positions.
869 Thus, with @code{ash}, shifting the pattern of bits one place to the right
874 (ash -6 -1) @result{} -3
875 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
876 11 1111 1111 1111 1111 1111 1111 1010
878 11 1111 1111 1111 1111 1111 1111 1101
882 In contrast, shifting the pattern of bits one place to the right with
883 @code{lsh} looks like this:
887 (lsh -6 -1) @result{} 536870909
888 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
889 11 1111 1111 1111 1111 1111 1111 1010
891 01 1111 1111 1111 1111 1111 1111 1101
895 Here are other examples:
897 @c !!! Check if lined up in smallbook format! XDVI shows problem
898 @c with smallbook but not with regular book! --rjc 16mar92
901 ; @r{ 30-bit binary values}
903 (lsh 5 2) ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
904 @result{} 20 ; = @r{00 0000 0000 0000 0000 0000 0001 0100}
909 (lsh -5 2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
910 @result{} -20 ; = @r{11 1111 1111 1111 1111 1111 1110 1100}
915 (lsh 5 -2) ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
916 @result{} 1 ; = @r{00 0000 0000 0000 0000 0000 0000 0001}
923 (lsh -5 -2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
924 @result{} 268435454 ; = @r{00 0111 1111 1111 1111 1111 1111 1110}
927 (ash -5 -2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
928 @result{} -2 ; = @r{11 1111 1111 1111 1111 1111 1111 1110}
933 @defun logand &rest ints-or-markers
934 This function returns the ``logical and'' of the arguments: the
935 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
936 set in all the arguments. (``Set'' means that the value of the bit is 1
939 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
940 12 is 12: 1101 combined with 1100 produces 1100.
941 In both the binary numbers, the leftmost two bits are set (i.e., they
942 are 1's), so the leftmost two bits of the returned value are set.
943 However, for the rightmost two bits, each is zero in at least one of
944 the arguments, so the rightmost two bits of the returned value are 0's.
956 If @code{logand} is not passed any argument, it returns a value of
957 @minus{}1. This number is an identity element for @code{logand}
958 because its binary representation consists entirely of ones. If
959 @code{logand} is passed just one argument, it returns that argument.
963 ; @r{ 30-bit binary values}
965 (logand 14 13) ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
966 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
967 @result{} 12 ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
971 (logand 14 13 4) ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
972 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
973 ; 4 = @r{00 0000 0000 0000 0000 0000 0000 0100}
974 @result{} 4 ; 4 = @r{00 0000 0000 0000 0000 0000 0000 0100}
979 @result{} -1 ; -1 = @r{11 1111 1111 1111 1111 1111 1111 1111}
984 @defun logior &rest ints-or-markers
985 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
986 is set in the result if, and only if, the @var{n}th bit is set in at least
987 one of the arguments. If there are no arguments, the result is zero,
988 which is an identity element for this operation. If @code{logior} is
989 passed just one argument, it returns that argument.
993 ; @r{ 30-bit binary values}
995 (logior 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
996 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
997 @result{} 13 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
1001 (logior 12 5 7) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1002 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1003 ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111}
1004 @result{} 15 ; 15 = @r{00 0000 0000 0000 0000 0000 0000 1111}
1009 @defun logxor &rest ints-or-markers
1010 This function returns the ``exclusive or'' of its arguments: the
1011 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1012 set in an odd number of the arguments. If there are no arguments, the
1013 result is 0, which is an identity element for this operation. If
1014 @code{logxor} is passed just one argument, it returns that argument.
1018 ; @r{ 30-bit binary values}
1020 (logxor 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1021 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1022 @result{} 9 ; 9 = @r{00 0000 0000 0000 0000 0000 0000 1001}
1026 (logxor 12 5 7) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1027 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1028 ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111}
1029 @result{} 14 ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
1034 @defun lognot integer
1035 This function returns the logical complement of its argument: the @var{n}th
1036 bit is one in the result if, and only if, the @var{n}th bit is zero in
1037 @var{integer}, and vice-versa.
1042 ;; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1044 ;; -6 = @r{11 1111 1111 1111 1111 1111 1111 1010}
1048 @node Math Functions
1049 @section Standard Mathematical Functions
1050 @cindex transcendental functions
1051 @cindex mathematical functions
1052 @cindex floating-point functions
1054 These mathematical functions allow integers as well as floating point
1055 numbers as arguments.
1060 These are the ordinary trigonometric functions, with argument measured
1065 The value of @code{(asin @var{arg})} is a number between
1079 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1080 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1084 The value of @code{(acos @var{arg})} is a number between 0 and
1091 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1092 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1095 @defun atan y &optional x
1096 The value of @code{(atan @var{y})} is a number between
1110 (exclusive) whose tangent is @var{y}. If the optional second
1111 argument @var{x} is given, the value of @code{(atan y x)} is the
1112 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1117 This is the exponential function; it returns
1124 to the power @var{arg}.
1131 is a fundamental mathematical constant also called the base of natural
1135 @defun log arg &optional base
1136 This function returns the logarithm of @var{arg}, with base @var{base}.
1137 If you don't specify @var{base}, the base
1144 is used. If @var{arg} is negative, it signals a @code{domain-error}
1150 This function returns @code{(1- (exp @var{arg}))}, but it is more
1151 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1156 This function returns @code{(log (1+ @var{arg}))}, but it is more
1157 accurate than that when @var{arg} is so small that adding 1 to it would
1163 This function returns the logarithm of @var{arg}, with base 10. If
1164 @var{arg} is negative, it signals a @code{domain-error} error.
1165 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1170 This function returns @var{x} raised to power @var{y}. If both
1171 arguments are integers and @var{y} is positive, the result is an
1172 integer; in this case, overflow causes truncation, so watch out.
1176 This returns the square root of @var{arg}. If @var{arg} is negative,
1177 it signals a @code{domain-error} error.
1180 @node Random Numbers
1181 @section Random Numbers
1182 @cindex random numbers
1184 A deterministic computer program cannot generate true random numbers.
1185 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1186 pseudo-random numbers is generated in a deterministic fashion. The
1187 numbers are not truly random, but they have certain properties that
1188 mimic a random series. For example, all possible values occur equally
1189 often in a pseudo-random series.
1191 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1192 Starting from any given seed, the @code{random} function always
1193 generates the same sequence of numbers. Emacs always starts with the
1194 same seed value, so the sequence of values of @code{random} is actually
1195 the same in each Emacs run! For example, in one operating system, the
1196 first call to @code{(random)} after you start Emacs always returns
1197 @minus{}1457731, and the second one always returns @minus{}7692030. This
1198 repeatability is helpful for debugging.
1200 If you want random numbers that don't always come out the same, execute
1201 @code{(random t)}. This chooses a new seed based on the current time of
1202 day and on Emacs's process @acronym{ID} number.
1204 @defun random &optional limit
1205 This function returns a pseudo-random integer. Repeated calls return a
1206 series of pseudo-random integers.
1208 If @var{limit} is a positive integer, the value is chosen to be
1209 nonnegative and less than @var{limit}.
1211 If @var{limit} is @code{t}, it means to choose a new seed based on the
1212 current time of day and on Emacs's process @acronym{ID} number.
1213 @c "Emacs'" is incorrect usage!
1215 On some machines, any integer representable in Lisp may be the result
1216 of @code{random}. On other machines, the result can never be larger
1217 than a certain maximum or less than a certain (negative) minimum.