2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @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 provide a wider range. Many examples in this
54 chapter assume that an integer has 30 bits and that floating point
55 numbers are IEEE double precision.
58 The Lisp reader reads an integer as a sequence of digits with optional
59 initial sign and optional final period. An integer that is out of the
60 Emacs range is treated as a floating-point number.
63 1 ; @r{The integer 1.}
64 1. ; @r{The integer 1.}
65 +1 ; @r{Also the integer 1.}
66 -1 ; @r{The integer @minus{}1.}
67 1073741825 ; @r{The floating point number 1073741825.0.}
68 0 ; @r{The integer 0.}
69 -0 ; @r{The integer 0.}
72 @cindex integers in specific radix
73 @cindex radix for reading an integer
74 @cindex base for reading an integer
77 @cindex reading numbers in hex, octal, and binary
78 The syntax for integers in bases other than 10 uses @samp{#}
79 followed by a letter that specifies the radix: @samp{b} for binary,
80 @samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
81 specify radix @var{radix}. Case is not significant for the letter
82 that specifies the radix. Thus, @samp{#b@var{integer}} reads
83 @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
84 @var{integer} in radix @var{radix}. Allowed values of @var{radix} run
85 from 2 to 36. For example:
94 To understand how various functions work on integers, especially the
95 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
96 view the numbers in their binary form.
98 In 30-bit binary, the decimal integer 5 looks like this:
101 0000...000101 (30 bits total)
105 (The @samp{...} stands for enough bits to fill out a 30-bit word; in
106 this case, @samp{...} stands for twenty 0 bits. Later examples also
107 use the @samp{...} notation to make binary integers easier to read.)
109 The integer @minus{}1 looks like this:
112 1111...111111 (30 bits total)
116 @cindex two's complement
117 @minus{}1 is represented as 30 ones. (This is called @dfn{two's
118 complement} notation.)
120 The negative integer, @minus{}5, is creating by subtracting 4 from
121 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
122 @minus{}5 looks like this:
125 1111...111011 (30 bits total)
128 In this implementation, the largest 30-bit binary integer value is
129 536,870,911 in decimal. In binary, it looks like this:
132 0111...111111 (30 bits total)
135 Since the arithmetic functions do not check whether integers go
136 outside their range, when you add 1 to 536,870,911, the value is the
137 negative integer @minus{}536,870,912:
142 @result{} 1000...000000 (30 bits total)
145 Many of the functions described in this chapter accept markers for
146 arguments in place of numbers. (@xref{Markers}.) Since the actual
147 arguments to such functions may be either numbers or markers, we often
148 give these arguments the name @var{number-or-marker}. When the argument
149 value is a marker, its position value is used and its buffer is ignored.
151 @cindex largest Lisp integer number
152 @cindex maximum Lisp integer number
153 @defvar most-positive-fixnum
154 The value of this variable is the largest integer that Emacs Lisp
158 @cindex smallest Lisp integer number
159 @cindex minimum Lisp integer number
160 @defvar most-negative-fixnum
161 The value of this variable is the smallest integer that Emacs Lisp can
162 handle. It is negative.
165 @xref{Character Codes, max-char}, for the maximum value of a valid
169 @section Floating Point Basics
171 Floating point numbers are useful for representing numbers that are
172 not integral. The precise range of floating point numbers is
173 machine-specific; it is the same as the range of the C data type
174 @code{double} on the machine you are using.
176 The read-syntax for floating point numbers requires either a decimal
177 point (with at least one digit following), an exponent, or both. For
178 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
179 @samp{.15e4} are five ways of writing a floating point number whose
180 value is 1500. They are all equivalent. You can also use a minus sign
181 to write negative floating point numbers, as in @samp{-1.0}.
183 @cindex @acronym{IEEE} floating point
184 @cindex positive infinity
185 @cindex negative infinity
188 Most modern computers support the @acronym{IEEE} floating point standard,
189 which provides for positive infinity and negative infinity as floating point
190 values. It also provides for a class of values called NaN or
191 ``not-a-number''; numerical functions return such values in cases where
192 there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a
193 NaN. For practical purposes, there's no significant difference between
194 different NaN values in Emacs Lisp, and there's no rule for precisely
195 which NaN value should be used in a particular case, so Emacs Lisp
196 doesn't try to distinguish them (but it does report the sign, if you
197 print it). Here are the read syntaxes for these special floating
201 @item positive infinity
203 @item negative infinity
206 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
209 To test whether a floating point value is a NaN, compare it with
210 itself using @code{=}. That returns @code{nil} for a NaN, and
211 @code{t} for any other floating point value.
213 The value @code{-0.0} is distinguishable from ordinary zero in
214 @acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
215 @code{=} consider them equal values.
217 You can use @code{logb} to extract the binary exponent of a floating
218 point number (or estimate the logarithm of an integer):
221 This function returns the binary exponent of @var{number}. More
222 precisely, the value is the logarithm of @var{number} base 2, rounded
234 The mathematical constant @math{e} (2.71828@dots{}).
238 The mathematical constant @math{pi} (3.14159@dots{}).
241 @node Predicates on Numbers
242 @section Type Predicates for Numbers
243 @cindex predicates for numbers
245 The functions in this section test for numbers, or for a specific
246 type of number. The functions @code{integerp} and @code{floatp} can
247 take any type of Lisp object as argument (they would not be of much
248 use otherwise), but the @code{zerop} predicate requires a number as
249 its argument. See also @code{integer-or-marker-p} and
250 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
253 This predicate tests whether its argument is a floating point
254 number and returns @code{t} if so, @code{nil} otherwise.
256 @code{floatp} does not exist in Emacs versions 18 and earlier.
259 @defun integerp object
260 This predicate tests whether its argument is an integer, and returns
261 @code{t} if so, @code{nil} otherwise.
264 @defun numberp object
265 This predicate tests whether its argument is a number (either integer or
266 floating point), and returns @code{t} if so, @code{nil} otherwise.
269 @defun wholenump object
270 @cindex natural numbers
271 The @code{wholenump} predicate (whose name comes from the phrase
272 ``whole-number-p'') tests to see whether its argument is a nonnegative
273 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
274 considered non-negative.
277 @code{natnump} is an obsolete synonym for @code{wholenump}.
281 This predicate tests whether its argument is zero, and returns @code{t}
282 if so, @code{nil} otherwise. The argument must be a number.
284 @code{(zerop x)} is equivalent to @code{(= x 0)}.
287 @node Comparison of Numbers
288 @section Comparison of Numbers
289 @cindex number comparison
290 @cindex comparing numbers
292 To test numbers for numerical equality, you should normally use
293 @code{=}, not @code{eq}. There can be many distinct floating point
294 number objects with the same numeric value. If you use @code{eq} to
295 compare them, then you test whether two values are the same
296 @emph{object}. By contrast, @code{=} compares only the numeric values
299 At present, each integer value has a unique Lisp object in Emacs Lisp.
300 Therefore, @code{eq} is equivalent to @code{=} where integers are
301 concerned. It is sometimes convenient to use @code{eq} for comparing an
302 unknown value with an integer, because @code{eq} does not report an
303 error if the unknown value is not a number---it accepts arguments of any
304 type. By contrast, @code{=} signals an error if the arguments are not
305 numbers or markers. However, it is a good idea to use @code{=} if you
306 can, even for comparing integers, just in case we change the
307 representation of integers in a future Emacs version.
309 Sometimes it is useful to compare numbers with @code{equal}; it
310 treats two numbers as equal if they have the same data type (both
311 integers, or both floating point) and the same value. By contrast,
312 @code{=} can treat an integer and a floating point number as equal.
313 @xref{Equality Predicates}.
315 There is another wrinkle: because floating point arithmetic is not
316 exact, it is often a bad idea to check for equality of two floating
317 point values. Usually it is better to test for approximate equality.
318 Here's a function to do this:
321 (defvar fuzz-factor 1.0e-6)
322 (defun approx-equal (x y)
323 (or (and (= x 0) (= y 0))
325 (max (abs x) (abs y)))
329 @cindex CL note---integers vrs @code{eq}
331 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
332 @code{=} because Common Lisp implements multi-word integers, and two
333 distinct integer objects can have the same numeric value. Emacs Lisp
334 can have just one integer object for any given value because it has a
335 limited range of integer values.
338 @defun = number-or-marker1 number-or-marker2
339 This function tests whether its arguments are numerically equal, and
340 returns @code{t} if so, @code{nil} otherwise.
343 @defun eql value1 value2
344 This function acts like @code{eq} except when both arguments are
345 numbers. It compares numbers by type and numeric value, so that
346 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
347 @code{(eql 1 1)} both return @code{t}.
350 @defun /= number-or-marker1 number-or-marker2
351 This function tests whether its arguments are numerically equal, and
352 returns @code{t} if they are not, and @code{nil} if they are.
355 @defun < number-or-marker1 number-or-marker2
356 This function tests whether its first argument is strictly less than
357 its second argument. It returns @code{t} if so, @code{nil} otherwise.
360 @defun <= number-or-marker1 number-or-marker2
361 This function tests whether its first argument is less than or equal
362 to 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 strictly greater
368 than its second argument. It returns @code{t} if so, @code{nil}
372 @defun >= number-or-marker1 number-or-marker2
373 This function tests whether its first argument is greater than or
374 equal to its second argument. It returns @code{t} if so, @code{nil}
378 @defun max number-or-marker &rest numbers-or-markers
379 This function returns the largest of its arguments.
380 If any of the arguments is floating-point, the value is returned
381 as floating point, even if it was given as an integer.
393 @defun min number-or-marker &rest numbers-or-markers
394 This function returns the smallest of its arguments.
395 If any of the arguments is floating-point, the value is returned
396 as floating point, even if it was given as an integer.
405 This function returns the absolute value of @var{number}.
408 @node Numeric Conversions
409 @section Numeric Conversions
410 @cindex rounding in conversions
411 @cindex number conversions
412 @cindex converting numbers
414 To convert an integer to floating point, use the function @code{float}.
417 This returns @var{number} converted to floating point.
418 If @var{number} is already a floating point number, @code{float} returns
422 There are four functions to convert floating point numbers to integers;
423 they differ in how they round. All accept an argument @var{number}
424 and an optional argument @var{divisor}. Both arguments may be
425 integers or floating point numbers. @var{divisor} may also be
426 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
427 functions convert @var{number} to an integer, or return it unchanged
428 if it already is an integer. If @var{divisor} is non-@code{nil}, they
429 divide @var{number} by @var{divisor} and convert the result to an
430 integer. An @code{arith-error} results if @var{divisor} is 0.
432 @defun truncate number &optional divisor
433 This returns @var{number}, converted to an integer by rounding towards
448 @defun floor number &optional divisor
449 This returns @var{number}, converted to an integer by rounding downward
450 (towards negative infinity).
452 If @var{divisor} is specified, this uses the kind of division
453 operation that corresponds to @code{mod}, rounding downward.
469 @defun ceiling number &optional divisor
470 This returns @var{number}, converted to an integer by rounding upward
471 (towards positive infinity).
485 @defun round number &optional divisor
486 This returns @var{number}, converted to an integer by rounding towards the
487 nearest integer. Rounding a value equidistant between two integers
488 may choose the integer closer to zero, or it may prefer an even integer,
489 depending on your machine.
503 @node Arithmetic Operations
504 @section Arithmetic Operations
505 @cindex arithmetic operations
507 Emacs Lisp provides the traditional four arithmetic operations:
508 addition, subtraction, multiplication, and division. Remainder and modulus
509 functions supplement the division functions. The functions to
510 add or subtract 1 are provided because they are traditional in Lisp and
513 All of these functions except @code{%} return a floating point value
514 if any argument is floating.
516 It is important to note that in Emacs Lisp, arithmetic functions
517 do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to
518 @minus{}536870912, depending on your hardware.
520 @defun 1+ number-or-marker
521 This function returns @var{number-or-marker} plus 1.
531 This function is not analogous to the C operator @code{++}---it does not
532 increment a variable. It just computes a sum. Thus, if we continue,
539 If you want to increment the variable, you must use @code{setq},
548 @defun 1- number-or-marker
549 This function returns @var{number-or-marker} minus 1.
552 @defun + &rest numbers-or-markers
553 This function adds its arguments together. When given no arguments,
566 @defun - &optional number-or-marker &rest more-numbers-or-markers
567 The @code{-} function serves two purposes: negation and subtraction.
568 When @code{-} has a single argument, the value is the negative of the
569 argument. When there are multiple arguments, @code{-} subtracts each of
570 the @var{more-numbers-or-markers} from @var{number-or-marker},
571 cumulatively. If there are no arguments, the result is 0.
583 @defun * &rest numbers-or-markers
584 This function multiplies its arguments together, and returns the
585 product. When given no arguments, @code{*} returns 1.
597 @defun / dividend divisor &rest divisors
598 This function divides @var{dividend} by @var{divisor} and returns the
599 quotient. If there are additional arguments @var{divisors}, then it
600 divides @var{dividend} by each divisor in turn. Each argument may be a
603 If all the arguments are integers, then the result is an integer too.
604 This means the result has to be rounded. On most machines, the result
605 is rounded towards zero after each division, but some machines may round
606 differently with negative arguments. This is because the Lisp function
607 @code{/} is implemented using the C division operator, which also
608 permits machine-dependent rounding. As a practical matter, all known
609 machines round in the standard fashion.
611 @cindex @code{arith-error} in division
612 If you divide an integer by 0, an @code{arith-error} error is signaled.
613 (@xref{Errors}.) Floating point division by zero returns either
614 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
615 otherwise, it signals an @code{arith-error} error.
634 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
639 @defun % dividend divisor
641 This function returns the integer remainder after division of @var{dividend}
642 by @var{divisor}. The arguments must be integers or markers.
644 For negative arguments, the remainder is in principle machine-dependent
645 since the quotient is; but in practice, all known machines behave alike.
647 An @code{arith-error} results if @var{divisor} is 0.
660 For any two integers @var{dividend} and @var{divisor},
664 (+ (% @var{dividend} @var{divisor})
665 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
670 always equals @var{dividend}.
673 @defun mod dividend divisor
675 This function returns the value of @var{dividend} modulo @var{divisor};
676 in other words, the remainder after division of @var{dividend}
677 by @var{divisor}, but with the same sign as @var{divisor}.
678 The arguments must be numbers or markers.
680 Unlike @code{%}, @code{mod} returns a well-defined result for negative
681 arguments. It also permits floating point arguments; it rounds the
682 quotient downward (towards minus infinity) to an integer, and uses that
683 quotient to compute the remainder.
685 An @code{arith-error} results if @var{divisor} is 0.
710 For any two numbers @var{dividend} and @var{divisor},
714 (+ (mod @var{dividend} @var{divisor})
715 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
720 always equals @var{dividend}, subject to rounding error if either
721 argument is floating point. For @code{floor}, see @ref{Numeric
725 @node Rounding Operations
726 @section Rounding Operations
727 @cindex rounding without conversion
729 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
730 @code{ftruncate} take a floating point argument and return a floating
731 point result whose value is a nearby integer. @code{ffloor} returns the
732 nearest integer below; @code{fceiling}, the nearest integer above;
733 @code{ftruncate}, the nearest integer in the direction towards zero;
734 @code{fround}, the nearest integer.
737 This function rounds @var{float} to the next lower integral value, and
738 returns that value as a floating point number.
741 @defun fceiling float
742 This function rounds @var{float} to the next higher integral value, and
743 returns that value as a floating point number.
746 @defun ftruncate float
747 This function rounds @var{float} towards zero to an integral value, and
748 returns that value as a floating point number.
752 This function rounds @var{float} to the nearest integral value,
753 and returns that value as a floating point number.
756 @node Bitwise Operations
757 @section Bitwise Operations on Integers
758 @cindex bitwise arithmetic
759 @cindex logical arithmetic
761 In a computer, an integer is represented as a binary number, a
762 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
763 operation acts on the individual bits of such a sequence. For example,
764 @dfn{shifting} moves the whole sequence left or right one or more places,
765 reproducing the same pattern ``moved over.''
767 The bitwise operations in Emacs Lisp apply only to integers.
769 @defun lsh integer1 count
770 @cindex logical shift
771 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
772 bits in @var{integer1} to the left @var{count} places, or to the right
773 if @var{count} is negative, bringing zeros into the vacated bits. If
774 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
775 (most-significant) bit, producing a positive result even if
776 @var{integer1} is negative. Contrast this with @code{ash}, below.
778 Here are two examples of @code{lsh}, shifting a pattern of bits one
779 place to the left. We show only the low-order eight bits of the binary
780 pattern; the rest are all zero.
786 ;; @r{Decimal 5 becomes decimal 10.}
787 00000101 @result{} 00001010
791 ;; @r{Decimal 7 becomes decimal 14.}
792 00000111 @result{} 00001110
797 As the examples illustrate, shifting the pattern of bits one place to
798 the left produces a number that is twice the value of the previous
801 Shifting a pattern of bits two places to the left produces results
802 like this (with 8-bit binary numbers):
808 ;; @r{Decimal 3 becomes decimal 12.}
809 00000011 @result{} 00001100
813 On the other hand, shifting one place to the right looks like this:
819 ;; @r{Decimal 6 becomes decimal 3.}
820 00000110 @result{} 00000011
826 ;; @r{Decimal 5 becomes decimal 2.}
827 00000101 @result{} 00000010
832 As the example illustrates, shifting one place to the right divides the
833 value of a positive integer by two, rounding downward.
835 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
836 not check for overflow, so shifting left can discard significant bits
837 and change the sign of the number. For example, left shifting
838 536,870,911 produces @minus{}2 in the 30-bit implementation:
841 (lsh 536870911 1) ; @r{left shift}
845 In binary, the argument looks like this:
849 ;; @r{Decimal 536,870,911}
850 0111...111111 (30 bits total)
855 which becomes the following when left shifted:
859 ;; @r{Decimal @minus{}2}
860 1111...111110 (30 bits total)
865 @defun ash integer1 count
866 @cindex arithmetic shift
867 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
868 to the left @var{count} places, or to the right if @var{count}
871 @code{ash} gives the same results as @code{lsh} except when
872 @var{integer1} and @var{count} are both negative. In that case,
873 @code{ash} puts ones in the empty bit positions on the left, while
874 @code{lsh} puts zeros in those bit positions.
876 Thus, with @code{ash}, shifting the pattern of bits one place to the right
881 (ash -6 -1) @result{} -3
882 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
883 1111...111010 (30 bits total)
885 1111...111101 (30 bits total)
889 In contrast, shifting the pattern of bits one place to the right with
890 @code{lsh} looks like this:
894 (lsh -6 -1) @result{} 536870909
895 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
896 1111...111010 (30 bits total)
898 0111...111101 (30 bits total)
902 Here are other examples:
904 @c !!! Check if lined up in smallbook format! XDVI shows problem
905 @c with smallbook but not with regular book! --rjc 16mar92
908 ; @r{ 30-bit binary values}
910 (lsh 5 2) ; 5 = @r{0000...000101}
911 @result{} 20 ; = @r{0000...010100}
916 (lsh -5 2) ; -5 = @r{1111...111011}
917 @result{} -20 ; = @r{1111...101100}
922 (lsh 5 -2) ; 5 = @r{0000...000101}
923 @result{} 1 ; = @r{0000...000001}
930 (lsh -5 -2) ; -5 = @r{1111...111011}
932 ; = @r{0011...111110}
935 (ash -5 -2) ; -5 = @r{1111...111011}
936 @result{} -2 ; = @r{1111...111110}
941 @defun logand &rest ints-or-markers
942 This function returns the ``logical and'' of the arguments: the
943 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
944 set in all the arguments. (``Set'' means that the value of the bit is 1
947 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
948 12 is 12: 1101 combined with 1100 produces 1100.
949 In both the binary numbers, the leftmost two bits are set (i.e., they
950 are 1's), so the leftmost two bits of the returned value are set.
951 However, for the rightmost two bits, each is zero in at least one of
952 the arguments, so the rightmost two bits of the returned value are 0's.
964 If @code{logand} is not passed any argument, it returns a value of
965 @minus{}1. This number is an identity element for @code{logand}
966 because its binary representation consists entirely of ones. If
967 @code{logand} is passed just one argument, it returns that argument.
971 ; @r{ 30-bit binary values}
973 (logand 14 13) ; 14 = @r{0000...001110}
974 ; 13 = @r{0000...001101}
975 @result{} 12 ; 12 = @r{0000...001100}
979 (logand 14 13 4) ; 14 = @r{0000...001110}
980 ; 13 = @r{0000...001101}
981 ; 4 = @r{0000...000100}
982 @result{} 4 ; 4 = @r{0000...000100}
987 @result{} -1 ; -1 = @r{1111...111111}
992 @defun logior &rest ints-or-markers
993 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
994 is set in the result if, and only if, the @var{n}th bit is set in at least
995 one of the arguments. If there are no arguments, the result is zero,
996 which is an identity element for this operation. If @code{logior} is
997 passed just one argument, it returns that argument.
1001 ; @r{ 30-bit binary values}
1003 (logior 12 5) ; 12 = @r{0000...001100}
1004 ; 5 = @r{0000...000101}
1005 @result{} 13 ; 13 = @r{0000...001101}
1009 (logior 12 5 7) ; 12 = @r{0000...001100}
1010 ; 5 = @r{0000...000101}
1011 ; 7 = @r{0000...000111}
1012 @result{} 15 ; 15 = @r{0000...001111}
1017 @defun logxor &rest ints-or-markers
1018 This function returns the ``exclusive or'' of its arguments: the
1019 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1020 set in an odd number of the arguments. If there are no arguments, the
1021 result is 0, which is an identity element for this operation. If
1022 @code{logxor} is passed just one argument, it returns that argument.
1026 ; @r{ 30-bit binary values}
1028 (logxor 12 5) ; 12 = @r{0000...001100}
1029 ; 5 = @r{0000...000101}
1030 @result{} 9 ; 9 = @r{0000...001001}
1034 (logxor 12 5 7) ; 12 = @r{0000...001100}
1035 ; 5 = @r{0000...000101}
1036 ; 7 = @r{0000...000111}
1037 @result{} 14 ; 14 = @r{0000...001110}
1042 @defun lognot integer
1043 This function returns the logical complement of its argument: the @var{n}th
1044 bit is one in the result if, and only if, the @var{n}th bit is zero in
1045 @var{integer}, and vice-versa.
1050 ;; 5 = @r{0000...000101} (30 bits total)
1052 ;; -6 = @r{1111...111010} (30 bits total)
1056 @node Math Functions
1057 @section Standard Mathematical Functions
1058 @cindex transcendental functions
1059 @cindex mathematical functions
1060 @cindex floating-point functions
1062 These mathematical functions allow integers as well as floating point
1063 numbers as arguments.
1068 These are the ordinary trigonometric functions, with argument measured
1073 The value of @code{(asin @var{arg})} is a number between
1087 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1088 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1092 The value of @code{(acos @var{arg})} is a number between 0 and
1099 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1100 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1103 @defun atan y &optional x
1104 The value of @code{(atan @var{y})} is a number between
1118 (exclusive) whose tangent is @var{y}. If the optional second
1119 argument @var{x} is given, the value of @code{(atan y x)} is the
1120 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1125 This is the exponential function; it returns
1132 to the power @var{arg}.
1139 is a fundamental mathematical constant also called the base of natural
1143 @defun log arg &optional base
1144 This function returns the logarithm of @var{arg}, with base @var{base}.
1145 If you don't specify @var{base}, the base
1152 is used. If @var{arg} is negative, it signals a @code{domain-error}
1158 This function returns @code{(1- (exp @var{arg}))}, but it is more
1159 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1164 This function returns @code{(log (1+ @var{arg}))}, but it is more
1165 accurate than that when @var{arg} is so small that adding 1 to it would
1171 This function returns the logarithm of @var{arg}, with base 10. If
1172 @var{arg} is negative, it signals a @code{domain-error} error.
1173 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1178 This function returns @var{x} raised to power @var{y}. If both
1179 arguments are integers and @var{y} is positive, the result is an
1180 integer; in this case, overflow causes truncation, so watch out.
1184 This returns the square root of @var{arg}. If @var{arg} is negative,
1185 it signals a @code{domain-error} error.
1188 @node Random Numbers
1189 @section Random Numbers
1190 @cindex random numbers
1192 A deterministic computer program cannot generate true random numbers.
1193 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1194 pseudo-random numbers is generated in a deterministic fashion. The
1195 numbers are not truly random, but they have certain properties that
1196 mimic a random series. For example, all possible values occur equally
1197 often in a pseudo-random series.
1199 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1200 Starting from any given seed, the @code{random} function always
1201 generates the same sequence of numbers. Emacs always starts with the
1202 same seed value, so the sequence of values of @code{random} is actually
1203 the same in each Emacs run! For example, in one operating system, the
1204 first call to @code{(random)} after you start Emacs always returns
1205 @minus{}1457731, and the second one always returns @minus{}7692030. This
1206 repeatability is helpful for debugging.
1208 If you want random numbers that don't always come out the same, execute
1209 @code{(random t)}. This chooses a new seed based on the current time of
1210 day and on Emacs's process @acronym{ID} number.
1212 @defun random &optional limit
1213 This function returns a pseudo-random integer. Repeated calls return a
1214 series of pseudo-random integers.
1216 If @var{limit} is a positive integer, the value is chosen to be
1217 nonnegative and less than @var{limit}.
1219 If @var{limit} is @code{t}, it means to choose a new seed based on the
1220 current time of day and on Emacs's process @acronym{ID} number.
1221 @c "Emacs'" is incorrect usage!
1223 On some machines, any integer representable in Lisp may be the result
1224 of @code{random}. On other machines, the result can never be larger
1225 than a certain maximum or less than a certain (negative) minimum.