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. 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 00 0000 0000 0000 0000 0000 0000 0101
104 (We have inserted spaces between groups of 4 bits, and two spaces
105 between groups of 8 bits, to make the binary integer easier to read.)
107 The integer @minus{}1 looks like this:
110 11 1111 1111 1111 1111 1111 1111 1111
114 @cindex two's complement
115 @minus{}1 is represented as 30 ones. (This is called @dfn{two's
116 complement} notation.)
118 The negative integer, @minus{}5, is creating by subtracting 4 from
119 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
120 @minus{}5 looks like this:
123 11 1111 1111 1111 1111 1111 1111 1011
126 In this implementation, the largest 30-bit binary integer value is
127 536,870,911 in decimal. In binary, it looks like this:
130 01 1111 1111 1111 1111 1111 1111 1111
133 Since the arithmetic functions do not check whether integers go
134 outside their range, when you add 1 to 536,870,911, the value is the
135 negative integer @minus{}536,870,912:
140 @result{} 10 0000 0000 0000 0000 0000 0000 0000
143 Many of the functions described in this chapter accept markers for
144 arguments in place of numbers. (@xref{Markers}.) Since the actual
145 arguments to such functions may be either numbers or markers, we often
146 give these arguments the name @var{number-or-marker}. When the argument
147 value is a marker, its position value is used and its buffer is ignored.
149 @defvar most-positive-fixnum
150 The value of this variable is the largest integer that Emacs Lisp
154 @defvar most-negative-fixnum
155 The value of this variable is the smallest integer that Emacs Lisp can
156 handle. It is negative.
159 @xref{Character Codes, max-char}, for the maximum value of a valid
163 @section Floating Point Basics
165 Floating point numbers are useful for representing numbers that are
166 not integral. The precise range of floating point numbers is
167 machine-specific; it is the same as the range of the C data type
168 @code{double} on the machine you are using.
170 The read-syntax for floating point numbers requires either a decimal
171 point (with at least one digit following), an exponent, or both. For
172 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
173 @samp{.15e4} are five ways of writing a floating point number whose
174 value is 1500. They are all equivalent. You can also use a minus sign
175 to write negative floating point numbers, as in @samp{-1.0}.
177 @cindex @acronym{IEEE} floating point
178 @cindex positive infinity
179 @cindex negative infinity
182 Most modern computers support the @acronym{IEEE} floating point standard,
183 which provides for positive infinity and negative infinity as floating point
184 values. It also provides for a class of values called NaN or
185 ``not-a-number''; numerical functions return such values in cases where
186 there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a
187 NaN. For practical purposes, there's no significant difference between
188 different NaN values in Emacs Lisp, and there's no rule for precisely
189 which NaN value should be used in a particular case, so Emacs Lisp
190 doesn't try to distinguish them (but it does report the sign, if you
191 print it). Here are the read syntaxes for these special floating
195 @item positive infinity
197 @item negative infinity
200 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
203 To test whether a floating point value is a NaN, compare it with
204 itself using @code{=}. That returns @code{nil} for a NaN, and
205 @code{t} for any other floating point value.
207 The value @code{-0.0} is distinguishable from ordinary zero in
208 @acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
209 @code{=} consider them equal values.
211 You can use @code{logb} to extract the binary exponent of a floating
212 point number (or estimate the logarithm of an integer):
215 This function returns the binary exponent of @var{number}. More
216 precisely, the value is the logarithm of @var{number} base 2, rounded
228 The mathematical constant @math{e} (2.71828@dots{}).
232 The mathematical constant @math{pi} (3.14159@dots{}).
235 @node Predicates on Numbers
236 @section Type Predicates for Numbers
237 @cindex predicates for numbers
239 The functions in this section test for numbers, or for a specific
240 type of number. The functions @code{integerp} and @code{floatp} can
241 take any type of Lisp object as argument (they would not be of much
242 use otherwise), but the @code{zerop} predicate requires a number as
243 its argument. See also @code{integer-or-marker-p} and
244 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
247 This predicate tests whether its argument is a floating point
248 number and returns @code{t} if so, @code{nil} otherwise.
250 @code{floatp} does not exist in Emacs versions 18 and earlier.
253 @defun integerp object
254 This predicate tests whether its argument is an integer, and returns
255 @code{t} if so, @code{nil} otherwise.
258 @defun numberp object
259 This predicate tests whether its argument is a number (either integer or
260 floating point), and returns @code{t} if so, @code{nil} otherwise.
263 @defun wholenump object
264 @cindex natural numbers
265 The @code{wholenump} predicate (whose name comes from the phrase
266 ``whole-number-p'') tests to see whether its argument is a nonnegative
267 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
268 considered non-negative.
271 @code{natnump} is an obsolete synonym for @code{wholenump}.
275 This predicate tests whether its argument is zero, and returns @code{t}
276 if so, @code{nil} otherwise. The argument must be a number.
278 @code{(zerop x)} is equivalent to @code{(= x 0)}.
281 @node Comparison of Numbers
282 @section Comparison of Numbers
283 @cindex number comparison
284 @cindex comparing numbers
286 To test numbers for numerical equality, you should normally use
287 @code{=}, not @code{eq}. There can be many distinct floating point
288 number objects with the same numeric value. If you use @code{eq} to
289 compare them, then you test whether two values are the same
290 @emph{object}. By contrast, @code{=} compares only the numeric values
293 At present, each integer value has a unique Lisp object in Emacs Lisp.
294 Therefore, @code{eq} is equivalent to @code{=} where integers are
295 concerned. It is sometimes convenient to use @code{eq} for comparing an
296 unknown value with an integer, because @code{eq} does not report an
297 error if the unknown value is not a number---it accepts arguments of any
298 type. By contrast, @code{=} signals an error if the arguments are not
299 numbers or markers. However, it is a good idea to use @code{=} if you
300 can, even for comparing integers, just in case we change the
301 representation of integers in a future Emacs version.
303 Sometimes it is useful to compare numbers with @code{equal}; it
304 treats two numbers as equal if they have the same data type (both
305 integers, or both floating point) and the same value. By contrast,
306 @code{=} can treat an integer and a floating point number as equal.
307 @xref{Equality Predicates}.
309 There is another wrinkle: because floating point arithmetic is not
310 exact, it is often a bad idea to check for equality of two floating
311 point values. Usually it is better to test for approximate equality.
312 Here's a function to do this:
315 (defvar fuzz-factor 1.0e-6)
316 (defun approx-equal (x y)
317 (or (and (= x 0) (= y 0))
319 (max (abs x) (abs y)))
323 @cindex CL note---integers vrs @code{eq}
325 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
326 @code{=} because Common Lisp implements multi-word integers, and two
327 distinct integer objects can have the same numeric value. Emacs Lisp
328 can have just one integer object for any given value because it has a
329 limited range of integer values.
332 @defun = number-or-marker1 number-or-marker2
333 This function tests whether its arguments are numerically equal, and
334 returns @code{t} if so, @code{nil} otherwise.
337 @defun eql value1 value2
338 This function acts like @code{eq} except when both arguments are
339 numbers. It compares numbers by type and numeric value, so that
340 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
341 @code{(eql 1 1)} both return @code{t}.
344 @defun /= number-or-marker1 number-or-marker2
345 This function tests whether its arguments are numerically equal, and
346 returns @code{t} if they are not, and @code{nil} if they are.
349 @defun < number-or-marker1 number-or-marker2
350 This function tests whether its first argument is strictly less than
351 its second argument. It returns @code{t} if so, @code{nil} otherwise.
354 @defun <= number-or-marker1 number-or-marker2
355 This function tests whether its first argument is less than or equal
356 to its second argument. It returns @code{t} if so, @code{nil}
360 @defun > number-or-marker1 number-or-marker2
361 This function tests whether its first argument is strictly greater
362 than its second argument. It returns @code{t} if so, @code{nil}
366 @defun >= number-or-marker1 number-or-marker2
367 This function tests whether its first argument is greater than or
368 equal to its second argument. It returns @code{t} if so, @code{nil}
372 @defun max number-or-marker &rest numbers-or-markers
373 This function returns the largest of its arguments.
374 If any of the arguments is floating-point, the value is returned
375 as floating point, even if it was given as an integer.
387 @defun min number-or-marker &rest numbers-or-markers
388 This function returns the smallest of its arguments.
389 If any of the arguments is floating-point, the value is returned
390 as floating point, even if it was given as an integer.
399 This function returns the absolute value of @var{number}.
402 @node Numeric Conversions
403 @section Numeric Conversions
404 @cindex rounding in conversions
405 @cindex number conversions
406 @cindex converting numbers
408 To convert an integer to floating point, use the function @code{float}.
411 This returns @var{number} converted to floating point.
412 If @var{number} is already a floating point number, @code{float} returns
416 There are four functions to convert floating point numbers to integers;
417 they differ in how they round. All accept an argument @var{number}
418 and an optional argument @var{divisor}. Both arguments may be
419 integers or floating point numbers. @var{divisor} may also be
420 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
421 functions convert @var{number} to an integer, or return it unchanged
422 if it already is an integer. If @var{divisor} is non-@code{nil}, they
423 divide @var{number} by @var{divisor} and convert the result to an
424 integer. An @code{arith-error} results if @var{divisor} is 0.
426 @defun truncate number &optional divisor
427 This returns @var{number}, converted to an integer by rounding towards
442 @defun floor number &optional divisor
443 This returns @var{number}, converted to an integer by rounding downward
444 (towards negative infinity).
446 If @var{divisor} is specified, this uses the kind of division
447 operation that corresponds to @code{mod}, rounding downward.
463 @defun ceiling number &optional divisor
464 This returns @var{number}, converted to an integer by rounding upward
465 (towards positive infinity).
479 @defun round number &optional divisor
480 This returns @var{number}, converted to an integer by rounding towards the
481 nearest integer. Rounding a value equidistant between two integers
482 may choose the integer closer to zero, or it may prefer an even integer,
483 depending on your machine.
497 @node Arithmetic Operations
498 @section Arithmetic Operations
499 @cindex arithmetic operations
501 Emacs Lisp provides the traditional four arithmetic operations:
502 addition, subtraction, multiplication, and division. Remainder and modulus
503 functions supplement the division functions. The functions to
504 add or subtract 1 are provided because they are traditional in Lisp and
507 All of these functions except @code{%} return a floating point value
508 if any argument is floating.
510 It is important to note that in Emacs Lisp, arithmetic functions
511 do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to
512 @minus{}268435456, depending on your hardware.
514 @defun 1+ number-or-marker
515 This function returns @var{number-or-marker} plus 1.
525 This function is not analogous to the C operator @code{++}---it does not
526 increment a variable. It just computes a sum. Thus, if we continue,
533 If you want to increment the variable, you must use @code{setq},
542 @defun 1- number-or-marker
543 This function returns @var{number-or-marker} minus 1.
546 @defun + &rest numbers-or-markers
547 This function adds its arguments together. When given no arguments,
560 @defun - &optional number-or-marker &rest more-numbers-or-markers
561 The @code{-} function serves two purposes: negation and subtraction.
562 When @code{-} has a single argument, the value is the negative of the
563 argument. When there are multiple arguments, @code{-} subtracts each of
564 the @var{more-numbers-or-markers} from @var{number-or-marker},
565 cumulatively. If there are no arguments, the result is 0.
577 @defun * &rest numbers-or-markers
578 This function multiplies its arguments together, and returns the
579 product. When given no arguments, @code{*} returns 1.
591 @defun / dividend divisor &rest divisors
592 This function divides @var{dividend} by @var{divisor} and returns the
593 quotient. If there are additional arguments @var{divisors}, then it
594 divides @var{dividend} by each divisor in turn. Each argument may be a
597 If all the arguments are integers, then the result is an integer too.
598 This means the result has to be rounded. On most machines, the result
599 is rounded towards zero after each division, but some machines may round
600 differently with negative arguments. This is because the Lisp function
601 @code{/} is implemented using the C division operator, which also
602 permits machine-dependent rounding. As a practical matter, all known
603 machines round in the standard fashion.
605 @cindex @code{arith-error} in division
606 If you divide an integer by 0, an @code{arith-error} error is signaled.
607 (@xref{Errors}.) Floating point division by zero returns either
608 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
609 otherwise, it signals an @code{arith-error} error.
628 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
633 @defun % dividend divisor
635 This function returns the integer remainder after division of @var{dividend}
636 by @var{divisor}. The arguments must be integers or markers.
638 For negative arguments, the remainder is in principle machine-dependent
639 since the quotient is; but in practice, all known machines behave alike.
641 An @code{arith-error} results if @var{divisor} is 0.
654 For any two integers @var{dividend} and @var{divisor},
658 (+ (% @var{dividend} @var{divisor})
659 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
664 always equals @var{dividend}.
667 @defun mod dividend divisor
669 This function returns the value of @var{dividend} modulo @var{divisor};
670 in other words, the remainder after division of @var{dividend}
671 by @var{divisor}, but with the same sign as @var{divisor}.
672 The arguments must be numbers or markers.
674 Unlike @code{%}, @code{mod} returns a well-defined result for negative
675 arguments. It also permits floating point arguments; it rounds the
676 quotient downward (towards minus infinity) to an integer, and uses that
677 quotient to compute the remainder.
679 An @code{arith-error} results if @var{divisor} is 0.
704 For any two numbers @var{dividend} and @var{divisor},
708 (+ (mod @var{dividend} @var{divisor})
709 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
714 always equals @var{dividend}, subject to rounding error if either
715 argument is floating point. For @code{floor}, see @ref{Numeric
719 @node Rounding Operations
720 @section Rounding Operations
721 @cindex rounding without conversion
723 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
724 @code{ftruncate} take a floating point argument and return a floating
725 point result whose value is a nearby integer. @code{ffloor} returns the
726 nearest integer below; @code{fceiling}, the nearest integer above;
727 @code{ftruncate}, the nearest integer in the direction towards zero;
728 @code{fround}, the nearest integer.
731 This function rounds @var{float} to the next lower integral value, and
732 returns that value as a floating point number.
735 @defun fceiling float
736 This function rounds @var{float} to the next higher integral value, and
737 returns that value as a floating point number.
740 @defun ftruncate float
741 This function rounds @var{float} towards zero to an integral value, and
742 returns that value as a floating point number.
746 This function rounds @var{float} to the nearest integral value,
747 and returns that value as a floating point number.
750 @node Bitwise Operations
751 @section Bitwise Operations on Integers
752 @cindex bitwise arithmetic
753 @cindex logical arithmetic
755 In a computer, an integer is represented as a binary number, a
756 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
757 operation acts on the individual bits of such a sequence. For example,
758 @dfn{shifting} moves the whole sequence left or right one or more places,
759 reproducing the same pattern ``moved over.''
761 The bitwise operations in Emacs Lisp apply only to integers.
763 @defun lsh integer1 count
764 @cindex logical shift
765 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
766 bits in @var{integer1} to the left @var{count} places, or to the right
767 if @var{count} is negative, bringing zeros into the vacated bits. If
768 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
769 (most-significant) bit, producing a positive result even if
770 @var{integer1} is negative. Contrast this with @code{ash}, below.
772 Here are two examples of @code{lsh}, shifting a pattern of bits one
773 place to the left. We show only the low-order eight bits of the binary
774 pattern; the rest are all zero.
780 ;; @r{Decimal 5 becomes decimal 10.}
781 00000101 @result{} 00001010
785 ;; @r{Decimal 7 becomes decimal 14.}
786 00000111 @result{} 00001110
791 As the examples illustrate, shifting the pattern of bits one place to
792 the left produces a number that is twice the value of the previous
795 Shifting a pattern of bits two places to the left produces results
796 like this (with 8-bit binary numbers):
802 ;; @r{Decimal 3 becomes decimal 12.}
803 00000011 @result{} 00001100
807 On the other hand, shifting one place to the right looks like this:
813 ;; @r{Decimal 6 becomes decimal 3.}
814 00000110 @result{} 00000011
820 ;; @r{Decimal 5 becomes decimal 2.}
821 00000101 @result{} 00000010
826 As the example illustrates, shifting one place to the right divides the
827 value of a positive integer by two, rounding downward.
829 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
830 not check for overflow, so shifting left can discard significant bits
831 and change the sign of the number. For example, left shifting
832 536,870,911 produces @minus{}2 on a 30-bit machine:
835 (lsh 536870911 1) ; @r{left shift}
839 In binary, in the 30-bit implementation, the argument looks like this:
843 ;; @r{Decimal 536,870,911}
844 01 1111 1111 1111 1111 1111 1111 1111
849 which becomes the following when left shifted:
853 ;; @r{Decimal @minus{}2}
854 11 1111 1111 1111 1111 1111 1111 1110
859 @defun ash integer1 count
860 @cindex arithmetic shift
861 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
862 to the left @var{count} places, or to the right if @var{count}
865 @code{ash} gives the same results as @code{lsh} except when
866 @var{integer1} and @var{count} are both negative. In that case,
867 @code{ash} puts ones in the empty bit positions on the left, while
868 @code{lsh} puts zeros in those bit positions.
870 Thus, with @code{ash}, shifting the pattern of bits one place to the right
875 (ash -6 -1) @result{} -3
876 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
877 11 1111 1111 1111 1111 1111 1111 1010
879 11 1111 1111 1111 1111 1111 1111 1101
883 In contrast, shifting the pattern of bits one place to the right with
884 @code{lsh} looks like this:
888 (lsh -6 -1) @result{} 536870909
889 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
890 11 1111 1111 1111 1111 1111 1111 1010
892 01 1111 1111 1111 1111 1111 1111 1101
896 Here are other examples:
898 @c !!! Check if lined up in smallbook format! XDVI shows problem
899 @c with smallbook but not with regular book! --rjc 16mar92
902 ; @r{ 30-bit binary values}
904 (lsh 5 2) ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
905 @result{} 20 ; = @r{00 0000 0000 0000 0000 0000 0001 0100}
910 (lsh -5 2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
911 @result{} -20 ; = @r{11 1111 1111 1111 1111 1111 1110 1100}
916 (lsh 5 -2) ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
917 @result{} 1 ; = @r{00 0000 0000 0000 0000 0000 0000 0001}
924 (lsh -5 -2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
925 @result{} 268435454 ; = @r{00 0111 1111 1111 1111 1111 1111 1110}
928 (ash -5 -2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
929 @result{} -2 ; = @r{11 1111 1111 1111 1111 1111 1111 1110}
934 @defun logand &rest ints-or-markers
935 This function returns the ``logical and'' of the arguments: the
936 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
937 set in all the arguments. (``Set'' means that the value of the bit is 1
940 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
941 12 is 12: 1101 combined with 1100 produces 1100.
942 In both the binary numbers, the leftmost two bits are set (i.e., they
943 are 1's), so the leftmost two bits of the returned value are set.
944 However, for the rightmost two bits, each is zero in at least one of
945 the arguments, so the rightmost two bits of the returned value are 0's.
957 If @code{logand} is not passed any argument, it returns a value of
958 @minus{}1. This number is an identity element for @code{logand}
959 because its binary representation consists entirely of ones. If
960 @code{logand} is passed just one argument, it returns that argument.
964 ; @r{ 30-bit binary values}
966 (logand 14 13) ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
967 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
968 @result{} 12 ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
972 (logand 14 13 4) ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
973 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
974 ; 4 = @r{00 0000 0000 0000 0000 0000 0000 0100}
975 @result{} 4 ; 4 = @r{00 0000 0000 0000 0000 0000 0000 0100}
980 @result{} -1 ; -1 = @r{11 1111 1111 1111 1111 1111 1111 1111}
985 @defun logior &rest ints-or-markers
986 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
987 is set in the result if, and only if, the @var{n}th bit is set in at least
988 one of the arguments. If there are no arguments, the result is zero,
989 which is an identity element for this operation. If @code{logior} is
990 passed just one argument, it returns that argument.
994 ; @r{ 30-bit binary values}
996 (logior 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
997 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
998 @result{} 13 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
1002 (logior 12 5 7) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1003 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1004 ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111}
1005 @result{} 15 ; 15 = @r{00 0000 0000 0000 0000 0000 0000 1111}
1010 @defun logxor &rest ints-or-markers
1011 This function returns the ``exclusive or'' of its arguments: the
1012 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1013 set in an odd number of the arguments. If there are no arguments, the
1014 result is 0, which is an identity element for this operation. If
1015 @code{logxor} is passed just one argument, it returns that argument.
1019 ; @r{ 30-bit binary values}
1021 (logxor 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1022 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1023 @result{} 9 ; 9 = @r{00 0000 0000 0000 0000 0000 0000 1001}
1027 (logxor 12 5 7) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1028 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1029 ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111}
1030 @result{} 14 ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
1035 @defun lognot integer
1036 This function returns the logical complement of its argument: the @var{n}th
1037 bit is one in the result if, and only if, the @var{n}th bit is zero in
1038 @var{integer}, and vice-versa.
1043 ;; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1045 ;; -6 = @r{11 1111 1111 1111 1111 1111 1111 1010}
1049 @node Math Functions
1050 @section Standard Mathematical Functions
1051 @cindex transcendental functions
1052 @cindex mathematical functions
1053 @cindex floating-point functions
1055 These mathematical functions allow integers as well as floating point
1056 numbers as arguments.
1061 These are the ordinary trigonometric functions, with argument measured
1066 The value of @code{(asin @var{arg})} is a number between
1080 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1081 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1085 The value of @code{(acos @var{arg})} is a number between 0 and
1092 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1093 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1096 @defun atan y &optional x
1097 The value of @code{(atan @var{y})} is a number between
1111 (exclusive) whose tangent is @var{y}. If the optional second
1112 argument @var{x} is given, the value of @code{(atan y x)} is the
1113 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1118 This is the exponential function; it returns
1125 to the power @var{arg}.
1132 is a fundamental mathematical constant also called the base of natural
1136 @defun log arg &optional base
1137 This function returns the logarithm of @var{arg}, with base @var{base}.
1138 If you don't specify @var{base}, the base
1145 is used. If @var{arg} is negative, it signals a @code{domain-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 @node Random Numbers
1182 @section Random Numbers
1183 @cindex random numbers
1185 A deterministic computer program cannot generate true random numbers.
1186 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1187 pseudo-random numbers is generated in a deterministic fashion. The
1188 numbers are not truly random, but they have certain properties that
1189 mimic a random series. For example, all possible values occur equally
1190 often in a pseudo-random series.
1192 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1193 Starting from any given seed, the @code{random} function always
1194 generates the same sequence of numbers. Emacs always starts with the
1195 same seed value, so the sequence of values of @code{random} is actually
1196 the same in each Emacs run! For example, in one operating system, the
1197 first call to @code{(random)} after you start Emacs always returns
1198 @minus{}1457731, and the second one always returns @minus{}7692030. This
1199 repeatability is helpful for debugging.
1201 If you want random numbers that don't always come out the same, execute
1202 @code{(random t)}. This chooses a new seed based on the current time of
1203 day and on Emacs's process @acronym{ID} number.
1205 @defun random &optional limit
1206 This function returns a pseudo-random integer. Repeated calls return a
1207 series of pseudo-random integers.
1209 If @var{limit} is a positive integer, the value is chosen to be
1210 nonnegative and less than @var{limit}.
1212 If @var{limit} is @code{t}, it means to choose a new seed based on the
1213 current time of day and on Emacs's process @acronym{ID} number.
1214 @c "Emacs'" is incorrect usage!
1216 On some machines, any integer representable in Lisp may be the result
1217 of @code{random}. On other machines, the result can never be larger
1218 than a certain maximum or less than a certain (negative) minimum.