2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
5 @c Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../../info/numbers
8 @node Numbers, Strings and Characters, Lisp Data Types, Top
13 GNU Emacs supports two numeric data types: @dfn{integers} and
14 @dfn{floating point numbers}. Integers are whole numbers such as
15 @minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
16 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
17 2.71828. They can also be expressed in exponential notation: 1.5e2
18 equals 150; in this example, @samp{e2} stands for ten to the second
19 power, and that is multiplied by 1.5. Floating point values are not
20 exact; they have a fixed, limited amount of precision.
23 * Integer Basics:: Representation and range of integers.
24 * Float Basics:: Representation and range of floating point.
25 * Predicates on Numbers:: Testing for numbers.
26 * Comparison of Numbers:: Equality and inequality predicates.
27 * Numeric Conversions:: Converting float to integer and vice versa.
28 * Arithmetic Operations:: How to add, subtract, multiply and divide.
29 * Rounding Operations:: Explicitly rounding floating point numbers.
30 * Bitwise Operations:: Logical and, or, not, shifting.
31 * Math Functions:: Trig, exponential and logarithmic functions.
32 * Random Numbers:: Obtaining random integers, predictable or not.
36 @comment node-name, next, previous, up
37 @section Integer Basics
39 The range of values for an integer depends on the machine. The
40 minimum range is @minus{}536870912 to 536870911 (30 bits; i.e.,
54 but some machines may provide a wider range. Many examples in this
55 chapter assume an integer has 30 bits.
58 The Lisp reader reads an integer as a sequence of digits with optional
59 initial sign and optional final period.
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{Also the integer 1, due to overflow.}
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
227 @node Predicates on Numbers
228 @section Type Predicates for Numbers
229 @cindex predicates for numbers
231 The functions in this section test for numbers, or for a specific
232 type of number. The functions @code{integerp} and @code{floatp} can
233 take any type of Lisp object as argument (they would not be of much
234 use otherwise), but the @code{zerop} predicate requires a number as
235 its argument. See also @code{integer-or-marker-p} and
236 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
239 This predicate tests whether its argument is a floating point
240 number and returns @code{t} if so, @code{nil} otherwise.
242 @code{floatp} does not exist in Emacs versions 18 and earlier.
245 @defun integerp object
246 This predicate tests whether its argument is an integer, and returns
247 @code{t} if so, @code{nil} otherwise.
250 @defun numberp object
251 This predicate tests whether its argument is a number (either integer or
252 floating point), and returns @code{t} if so, @code{nil} otherwise.
255 @defun wholenump object
256 @cindex natural numbers
257 The @code{wholenump} predicate (whose name comes from the phrase
258 ``whole-number-p'') tests to see whether its argument is a nonnegative
259 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
260 considered non-negative.
263 @code{natnump} is an obsolete synonym for @code{wholenump}.
267 This predicate tests whether its argument is zero, and returns @code{t}
268 if so, @code{nil} otherwise. The argument must be a number.
270 @code{(zerop x)} is equivalent to @code{(= x 0)}.
273 @node Comparison of Numbers
274 @section Comparison of Numbers
275 @cindex number comparison
276 @cindex comparing numbers
278 To test numbers for numerical equality, you should normally use
279 @code{=}, not @code{eq}. There can be many distinct floating point
280 number objects with the same numeric value. If you use @code{eq} to
281 compare them, then you test whether two values are the same
282 @emph{object}. By contrast, @code{=} compares only the numeric values
285 At present, each integer value has a unique Lisp object in Emacs Lisp.
286 Therefore, @code{eq} is equivalent to @code{=} where integers are
287 concerned. It is sometimes convenient to use @code{eq} for comparing an
288 unknown value with an integer, because @code{eq} does not report an
289 error if the unknown value is not a number---it accepts arguments of any
290 type. By contrast, @code{=} signals an error if the arguments are not
291 numbers or markers. However, it is a good idea to use @code{=} if you
292 can, even for comparing integers, just in case we change the
293 representation of integers in a future Emacs version.
295 Sometimes it is useful to compare numbers with @code{equal}; it
296 treats two numbers as equal if they have the same data type (both
297 integers, or both floating point) and the same value. By contrast,
298 @code{=} can treat an integer and a floating point number as equal.
299 @xref{Equality Predicates}.
301 There is another wrinkle: because floating point arithmetic is not
302 exact, it is often a bad idea to check for equality of two floating
303 point values. Usually it is better to test for approximate equality.
304 Here's a function to do this:
307 (defvar fuzz-factor 1.0e-6)
308 (defun approx-equal (x y)
309 (or (and (= x 0) (= y 0))
311 (max (abs x) (abs y)))
315 @cindex CL note---integers vrs @code{eq}
317 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
318 @code{=} because Common Lisp implements multi-word integers, and two
319 distinct integer objects can have the same numeric value. Emacs Lisp
320 can have just one integer object for any given value because it has a
321 limited range of integer values.
324 @defun = number-or-marker1 number-or-marker2
325 This function tests whether its arguments are numerically equal, and
326 returns @code{t} if so, @code{nil} otherwise.
329 @defun eql value1 value2
330 This function acts like @code{eq} except when both arguments are
331 numbers. It compares numbers by type and numeric value, so that
332 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
333 @code{(eql 1 1)} both return @code{t}.
336 @defun /= number-or-marker1 number-or-marker2
337 This function tests whether its arguments are numerically equal, and
338 returns @code{t} if they are not, and @code{nil} if they are.
341 @defun < number-or-marker1 number-or-marker2
342 This function tests whether its first argument is strictly less than
343 its second argument. It returns @code{t} if so, @code{nil} otherwise.
346 @defun <= number-or-marker1 number-or-marker2
347 This function tests whether its first argument is less than or equal
348 to its second argument. It returns @code{t} if so, @code{nil}
352 @defun > number-or-marker1 number-or-marker2
353 This function tests whether its first argument is strictly greater
354 than its second argument. It returns @code{t} if so, @code{nil}
358 @defun >= number-or-marker1 number-or-marker2
359 This function tests whether its first argument is greater than or
360 equal to its second argument. It returns @code{t} if so, @code{nil}
364 @defun max number-or-marker &rest numbers-or-markers
365 This function returns the largest of its arguments.
366 If any of the arguments is floating-point, the value is returned
367 as floating point, even if it was given as an integer.
379 @defun min number-or-marker &rest numbers-or-markers
380 This function returns the smallest of its arguments.
381 If any of the arguments is floating-point, the value is returned
382 as floating point, even if it was given as an integer.
391 This function returns the absolute value of @var{number}.
394 @node Numeric Conversions
395 @section Numeric Conversions
396 @cindex rounding in conversions
397 @cindex number conversions
398 @cindex converting numbers
400 To convert an integer to floating point, use the function @code{float}.
403 This returns @var{number} converted to floating point.
404 If @var{number} is already a floating point number, @code{float} returns
408 There are four functions to convert floating point numbers to integers;
409 they differ in how they round. All accept an argument @var{number}
410 and an optional argument @var{divisor}. Both arguments may be
411 integers or floating point numbers. @var{divisor} may also be
412 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
413 functions convert @var{number} to an integer, or return it unchanged
414 if it already is an integer. If @var{divisor} is non-@code{nil}, they
415 divide @var{number} by @var{divisor} and convert the result to an
416 integer. An @code{arith-error} results if @var{divisor} is 0.
418 @defun truncate number &optional divisor
419 This returns @var{number}, converted to an integer by rounding towards
434 @defun floor number &optional divisor
435 This returns @var{number}, converted to an integer by rounding downward
436 (towards negative infinity).
438 If @var{divisor} is specified, this uses the kind of division
439 operation that corresponds to @code{mod}, rounding downward.
455 @defun ceiling number &optional divisor
456 This returns @var{number}, converted to an integer by rounding upward
457 (towards positive infinity).
471 @defun round number &optional divisor
472 This returns @var{number}, converted to an integer by rounding towards the
473 nearest integer. Rounding a value equidistant between two integers
474 may choose the integer closer to zero, or it may prefer an even integer,
475 depending on your machine.
489 @node Arithmetic Operations
490 @section Arithmetic Operations
491 @cindex arithmetic operations
493 Emacs Lisp provides the traditional four arithmetic operations:
494 addition, subtraction, multiplication, and division. Remainder and modulus
495 functions supplement the division functions. The functions to
496 add or subtract 1 are provided because they are traditional in Lisp and
499 All of these functions except @code{%} return a floating point value
500 if any argument is floating.
502 It is important to note that in Emacs Lisp, arithmetic functions
503 do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to
504 @minus{}268435456, depending on your hardware.
506 @defun 1+ number-or-marker
507 This function returns @var{number-or-marker} plus 1.
517 This function is not analogous to the C operator @code{++}---it does not
518 increment a variable. It just computes a sum. Thus, if we continue,
525 If you want to increment the variable, you must use @code{setq},
534 @defun 1- number-or-marker
535 This function returns @var{number-or-marker} minus 1.
538 @defun + &rest numbers-or-markers
539 This function adds its arguments together. When given no arguments,
552 @defun - &optional number-or-marker &rest more-numbers-or-markers
553 The @code{-} function serves two purposes: negation and subtraction.
554 When @code{-} has a single argument, the value is the negative of the
555 argument. When there are multiple arguments, @code{-} subtracts each of
556 the @var{more-numbers-or-markers} from @var{number-or-marker},
557 cumulatively. If there are no arguments, the result is 0.
569 @defun * &rest numbers-or-markers
570 This function multiplies its arguments together, and returns the
571 product. When given no arguments, @code{*} returns 1.
583 @defun / dividend divisor &rest divisors
584 This function divides @var{dividend} by @var{divisor} and returns the
585 quotient. If there are additional arguments @var{divisors}, then it
586 divides @var{dividend} by each divisor in turn. Each argument may be a
589 If all the arguments are integers, then the result is an integer too.
590 This means the result has to be rounded. On most machines, the result
591 is rounded towards zero after each division, but some machines may round
592 differently with negative arguments. This is because the Lisp function
593 @code{/} is implemented using the C division operator, which also
594 permits machine-dependent rounding. As a practical matter, all known
595 machines round in the standard fashion.
597 @cindex @code{arith-error} in division
598 If you divide an integer by 0, an @code{arith-error} error is signaled.
599 (@xref{Errors}.) Floating point division by zero returns either
600 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
601 otherwise, it signals an @code{arith-error} error.
620 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
625 @defun % dividend divisor
627 This function returns the integer remainder after division of @var{dividend}
628 by @var{divisor}. The arguments must be integers or markers.
630 For negative arguments, the remainder is in principle machine-dependent
631 since the quotient is; but in practice, all known machines behave alike.
633 An @code{arith-error} results if @var{divisor} is 0.
646 For any two integers @var{dividend} and @var{divisor},
650 (+ (% @var{dividend} @var{divisor})
651 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
656 always equals @var{dividend}.
659 @defun mod dividend divisor
661 This function returns the value of @var{dividend} modulo @var{divisor};
662 in other words, the remainder after division of @var{dividend}
663 by @var{divisor}, but with the same sign as @var{divisor}.
664 The arguments must be numbers or markers.
666 Unlike @code{%}, @code{mod} returns a well-defined result for negative
667 arguments. It also permits floating point arguments; it rounds the
668 quotient downward (towards minus infinity) to an integer, and uses that
669 quotient to compute the remainder.
671 An @code{arith-error} results if @var{divisor} is 0.
696 For any two numbers @var{dividend} and @var{divisor},
700 (+ (mod @var{dividend} @var{divisor})
701 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
706 always equals @var{dividend}, subject to rounding error if either
707 argument is floating point. For @code{floor}, see @ref{Numeric
711 @node Rounding Operations
712 @section Rounding Operations
713 @cindex rounding without conversion
715 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
716 @code{ftruncate} take a floating point argument and return a floating
717 point result whose value is a nearby integer. @code{ffloor} returns the
718 nearest integer below; @code{fceiling}, the nearest integer above;
719 @code{ftruncate}, the nearest integer in the direction towards zero;
720 @code{fround}, the nearest integer.
723 This function rounds @var{float} to the next lower integral value, and
724 returns that value as a floating point number.
727 @defun fceiling float
728 This function rounds @var{float} to the next higher integral value, and
729 returns that value as a floating point number.
732 @defun ftruncate float
733 This function rounds @var{float} towards zero to an integral value, and
734 returns that value as a floating point number.
738 This function rounds @var{float} to the nearest integral value,
739 and returns that value as a floating point number.
742 @node Bitwise Operations
743 @section Bitwise Operations on Integers
744 @cindex bitwise arithmetic
745 @cindex logical arithmetic
747 In a computer, an integer is represented as a binary number, a
748 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
749 operation acts on the individual bits of such a sequence. For example,
750 @dfn{shifting} moves the whole sequence left or right one or more places,
751 reproducing the same pattern ``moved over.''
753 The bitwise operations in Emacs Lisp apply only to integers.
755 @defun lsh integer1 count
756 @cindex logical shift
757 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
758 bits in @var{integer1} to the left @var{count} places, or to the right
759 if @var{count} is negative, bringing zeros into the vacated bits. If
760 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
761 (most-significant) bit, producing a positive result even if
762 @var{integer1} is negative. Contrast this with @code{ash}, below.
764 Here are two examples of @code{lsh}, shifting a pattern of bits one
765 place to the left. We show only the low-order eight bits of the binary
766 pattern; the rest are all zero.
772 ;; @r{Decimal 5 becomes decimal 10.}
773 00000101 @result{} 00001010
777 ;; @r{Decimal 7 becomes decimal 14.}
778 00000111 @result{} 00001110
783 As the examples illustrate, shifting the pattern of bits one place to
784 the left produces a number that is twice the value of the previous
787 Shifting a pattern of bits two places to the left produces results
788 like this (with 8-bit binary numbers):
794 ;; @r{Decimal 3 becomes decimal 12.}
795 00000011 @result{} 00001100
799 On the other hand, shifting one place to the right looks like this:
805 ;; @r{Decimal 6 becomes decimal 3.}
806 00000110 @result{} 00000011
812 ;; @r{Decimal 5 becomes decimal 2.}
813 00000101 @result{} 00000010
818 As the example illustrates, shifting one place to the right divides the
819 value of a positive integer by two, rounding downward.
821 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
822 not check for overflow, so shifting left can discard significant bits
823 and change the sign of the number. For example, left shifting
824 536,870,911 produces @minus{}2 on a 30-bit machine:
827 (lsh 536870911 1) ; @r{left shift}
831 In binary, in the 30-bit implementation, the argument looks like this:
835 ;; @r{Decimal 536,870,911}
836 01 1111 1111 1111 1111 1111 1111 1111
841 which becomes the following when left shifted:
845 ;; @r{Decimal @minus{}2}
846 11 1111 1111 1111 1111 1111 1111 1110
851 @defun ash integer1 count
852 @cindex arithmetic shift
853 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
854 to the left @var{count} places, or to the right if @var{count}
857 @code{ash} gives the same results as @code{lsh} except when
858 @var{integer1} and @var{count} are both negative. In that case,
859 @code{ash} puts ones in the empty bit positions on the left, while
860 @code{lsh} puts zeros in those bit positions.
862 Thus, with @code{ash}, shifting the pattern of bits one place to the right
867 (ash -6 -1) @result{} -3
868 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
869 11 1111 1111 1111 1111 1111 1111 1010
871 11 1111 1111 1111 1111 1111 1111 1101
875 In contrast, shifting the pattern of bits one place to the right with
876 @code{lsh} looks like this:
880 (lsh -6 -1) @result{} 536870909
881 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
882 11 1111 1111 1111 1111 1111 1111 1010
884 01 1111 1111 1111 1111 1111 1111 1101
888 Here are other examples:
890 @c !!! Check if lined up in smallbook format! XDVI shows problem
891 @c with smallbook but not with regular book! --rjc 16mar92
894 ; @r{ 30-bit binary values}
896 (lsh 5 2) ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
897 @result{} 20 ; = @r{00 0000 0000 0000 0000 0000 0001 0100}
902 (lsh -5 2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
903 @result{} -20 ; = @r{11 1111 1111 1111 1111 1111 1110 1100}
908 (lsh 5 -2) ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
909 @result{} 1 ; = @r{00 0000 0000 0000 0000 0000 0000 0001}
916 (lsh -5 -2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
917 @result{} 268435454 ; = @r{00 0111 1111 1111 1111 1111 1111 1110}
920 (ash -5 -2) ; -5 = @r{11 1111 1111 1111 1111 1111 1111 1011}
921 @result{} -2 ; = @r{11 1111 1111 1111 1111 1111 1111 1110}
926 @defun logand &rest ints-or-markers
927 This function returns the ``logical and'' of the arguments: the
928 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
929 set in all the arguments. (``Set'' means that the value of the bit is 1
932 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
933 12 is 12: 1101 combined with 1100 produces 1100.
934 In both the binary numbers, the leftmost two bits are set (i.e., they
935 are 1's), so the leftmost two bits of the returned value are set.
936 However, for the rightmost two bits, each is zero in at least one of
937 the arguments, so the rightmost two bits of the returned value are 0's.
949 If @code{logand} is not passed any argument, it returns a value of
950 @minus{}1. This number is an identity element for @code{logand}
951 because its binary representation consists entirely of ones. If
952 @code{logand} is passed just one argument, it returns that argument.
956 ; @r{ 30-bit binary values}
958 (logand 14 13) ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
959 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
960 @result{} 12 ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
964 (logand 14 13 4) ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
965 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
966 ; 4 = @r{00 0000 0000 0000 0000 0000 0000 0100}
967 @result{} 4 ; 4 = @r{00 0000 0000 0000 0000 0000 0000 0100}
972 @result{} -1 ; -1 = @r{11 1111 1111 1111 1111 1111 1111 1111}
977 @defun logior &rest ints-or-markers
978 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
979 is set in the result if, and only if, the @var{n}th bit is set in at least
980 one of the arguments. If there are no arguments, the result is zero,
981 which is an identity element for this operation. If @code{logior} is
982 passed just one argument, it returns that argument.
986 ; @r{ 30-bit binary values}
988 (logior 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
989 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
990 @result{} 13 ; 13 = @r{00 0000 0000 0000 0000 0000 0000 1101}
994 (logior 12 5 7) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
995 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
996 ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111}
997 @result{} 15 ; 15 = @r{00 0000 0000 0000 0000 0000 0000 1111}
1002 @defun logxor &rest ints-or-markers
1003 This function returns the ``exclusive or'' of its arguments: the
1004 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1005 set in an odd number of the arguments. If there are no arguments, the
1006 result is 0, which is an identity element for this operation. If
1007 @code{logxor} is passed just one argument, it returns that argument.
1011 ; @r{ 30-bit binary values}
1013 (logxor 12 5) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1014 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1015 @result{} 9 ; 9 = @r{00 0000 0000 0000 0000 0000 0000 1001}
1019 (logxor 12 5 7) ; 12 = @r{00 0000 0000 0000 0000 0000 0000 1100}
1020 ; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1021 ; 7 = @r{00 0000 0000 0000 0000 0000 0000 0111}
1022 @result{} 14 ; 14 = @r{00 0000 0000 0000 0000 0000 0000 1110}
1027 @defun lognot integer
1028 This function returns the logical complement of its argument: the @var{n}th
1029 bit is one in the result if, and only if, the @var{n}th bit is zero in
1030 @var{integer}, and vice-versa.
1035 ;; 5 = @r{00 0000 0000 0000 0000 0000 0000 0101}
1037 ;; -6 = @r{11 1111 1111 1111 1111 1111 1111 1010}
1041 @node Math Functions
1042 @section Standard Mathematical Functions
1043 @cindex transcendental functions
1044 @cindex mathematical functions
1045 @cindex floating-point functions
1047 These mathematical functions allow integers as well as floating point
1048 numbers as arguments.
1053 These are the ordinary trigonometric functions, with argument measured
1058 The value of @code{(asin @var{arg})} is a number between
1072 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1073 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1077 The value of @code{(acos @var{arg})} is a number between 0 and
1084 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1085 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1088 @defun atan y &optional x
1089 The value of @code{(atan @var{y})} is a number between
1103 (exclusive) whose tangent is @var{y}. If the optional second
1104 argument @var{x} is given, the value of @code{(atan y x)} is the
1105 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1110 This is the exponential function; it returns
1117 to the power @var{arg}.
1124 is a fundamental mathematical constant also called the base of natural
1128 @defun log arg &optional base
1129 This function returns the logarithm of @var{arg}, with base @var{base}.
1130 If you don't specify @var{base}, the base
1137 is used. If @var{arg} is negative, it signals a @code{domain-error}
1143 This function returns @code{(1- (exp @var{arg}))}, but it is more
1144 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1149 This function returns @code{(log (1+ @var{arg}))}, but it is more
1150 accurate than that when @var{arg} is so small that adding 1 to it would
1156 This function returns the logarithm of @var{arg}, with base 10. If
1157 @var{arg} is negative, it signals a @code{domain-error} error.
1158 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1163 This function returns @var{x} raised to power @var{y}. If both
1164 arguments are integers and @var{y} is positive, the result is an
1165 integer; in this case, overflow causes truncation, so watch out.
1169 This returns the square root of @var{arg}. If @var{arg} is negative,
1170 it signals a @code{domain-error} error.
1173 @node Random Numbers
1174 @section Random Numbers
1175 @cindex random numbers
1177 A deterministic computer program cannot generate true random numbers.
1178 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1179 pseudo-random numbers is generated in a deterministic fashion. The
1180 numbers are not truly random, but they have certain properties that
1181 mimic a random series. For example, all possible values occur equally
1182 often in a pseudo-random series.
1184 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1185 Starting from any given seed, the @code{random} function always
1186 generates the same sequence of numbers. Emacs always starts with the
1187 same seed value, so the sequence of values of @code{random} is actually
1188 the same in each Emacs run! For example, in one operating system, the
1189 first call to @code{(random)} after you start Emacs always returns
1190 @minus{}1457731, and the second one always returns @minus{}7692030. This
1191 repeatability is helpful for debugging.
1193 If you want random numbers that don't always come out the same, execute
1194 @code{(random t)}. This chooses a new seed based on the current time of
1195 day and on Emacs's process @acronym{ID} number.
1197 @defun random &optional limit
1198 This function returns a pseudo-random integer. Repeated calls return a
1199 series of pseudo-random integers.
1201 If @var{limit} is a positive integer, the value is chosen to be
1202 nonnegative and less than @var{limit}.
1204 If @var{limit} is @code{t}, it means to choose a new seed based on the
1205 current time of day and on Emacs's process @acronym{ID} number.
1206 @c "Emacs'" is incorrect usage!
1208 On some machines, any integer representable in Lisp may be the result
1209 of @code{random}. On other machines, the result can never be larger
1210 than a certain maximum or less than a certain (negative) minimum.
1214 arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e