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 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 @defvar most-positive-fixnum
152 The value of this variable is the largest integer that Emacs Lisp
156 @defvar most-negative-fixnum
157 The value of this variable is the smallest integer that Emacs Lisp can
158 handle. It is negative.
161 @xref{Character Codes, max-char}, for the maximum value of a valid
165 @section Floating Point Basics
167 Floating point numbers are useful for representing numbers that are
168 not integral. The precise range of floating point numbers is
169 machine-specific; it is the same as the range of the C data type
170 @code{double} on the machine you are using.
172 The read-syntax for floating point numbers requires either a decimal
173 point (with at least one digit following), an exponent, or both. For
174 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
175 @samp{.15e4} are five ways of writing a floating point number whose
176 value is 1500. They are all equivalent. You can also use a minus sign
177 to write negative floating point numbers, as in @samp{-1.0}.
179 @cindex @acronym{IEEE} floating point
180 @cindex positive infinity
181 @cindex negative infinity
184 Most modern computers support the @acronym{IEEE} floating point standard,
185 which provides for positive infinity and negative infinity as floating point
186 values. It also provides for a class of values called NaN or
187 ``not-a-number''; numerical functions return such values in cases where
188 there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a
189 NaN. For practical purposes, there's no significant difference between
190 different NaN values in Emacs Lisp, and there's no rule for precisely
191 which NaN value should be used in a particular case, so Emacs Lisp
192 doesn't try to distinguish them (but it does report the sign, if you
193 print it). Here are the read syntaxes for these special floating
197 @item positive infinity
199 @item negative infinity
202 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
205 To test whether a floating point value is a NaN, compare it with
206 itself using @code{=}. That returns @code{nil} for a NaN, and
207 @code{t} for any other floating point value.
209 The value @code{-0.0} is distinguishable from ordinary zero in
210 @acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
211 @code{=} consider them equal values.
213 You can use @code{logb} to extract the binary exponent of a floating
214 point number (or estimate the logarithm of an integer):
217 This function returns the binary exponent of @var{number}. More
218 precisely, the value is the logarithm of @var{number} base 2, rounded
230 The mathematical constant @math{e} (2.71828@dots{}).
234 The mathematical constant @math{pi} (3.14159@dots{}).
237 @node Predicates on Numbers
238 @section Type Predicates for Numbers
239 @cindex predicates for numbers
241 The functions in this section test for numbers, or for a specific
242 type of number. The functions @code{integerp} and @code{floatp} can
243 take any type of Lisp object as argument (they would not be of much
244 use otherwise), but the @code{zerop} predicate requires a number as
245 its argument. See also @code{integer-or-marker-p} and
246 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
249 This predicate tests whether its argument is a floating point
250 number and returns @code{t} if so, @code{nil} otherwise.
252 @code{floatp} does not exist in Emacs versions 18 and earlier.
255 @defun integerp object
256 This predicate tests whether its argument is an integer, and returns
257 @code{t} if so, @code{nil} otherwise.
260 @defun numberp object
261 This predicate tests whether its argument is a number (either integer or
262 floating point), and returns @code{t} if so, @code{nil} otherwise.
265 @defun wholenump object
266 @cindex natural numbers
267 The @code{wholenump} predicate (whose name comes from the phrase
268 ``whole-number-p'') tests to see whether its argument is a nonnegative
269 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
270 considered non-negative.
273 @code{natnump} is an obsolete synonym for @code{wholenump}.
277 This predicate tests whether its argument is zero, and returns @code{t}
278 if so, @code{nil} otherwise. The argument must be a number.
280 @code{(zerop x)} is equivalent to @code{(= x 0)}.
283 @node Comparison of Numbers
284 @section Comparison of Numbers
285 @cindex number comparison
286 @cindex comparing numbers
288 To test numbers for numerical equality, you should normally use
289 @code{=}, not @code{eq}. There can be many distinct floating point
290 number objects with the same numeric value. If you use @code{eq} to
291 compare them, then you test whether two values are the same
292 @emph{object}. By contrast, @code{=} compares only the numeric values
295 At present, each integer value has a unique Lisp object in Emacs Lisp.
296 Therefore, @code{eq} is equivalent to @code{=} where integers are
297 concerned. It is sometimes convenient to use @code{eq} for comparing an
298 unknown value with an integer, because @code{eq} does not report an
299 error if the unknown value is not a number---it accepts arguments of any
300 type. By contrast, @code{=} signals an error if the arguments are not
301 numbers or markers. However, it is a good idea to use @code{=} if you
302 can, even for comparing integers, just in case we change the
303 representation of integers in a future Emacs version.
305 Sometimes it is useful to compare numbers with @code{equal}; it
306 treats two numbers as equal if they have the same data type (both
307 integers, or both floating point) and the same value. By contrast,
308 @code{=} can treat an integer and a floating point number as equal.
309 @xref{Equality Predicates}.
311 There is another wrinkle: because floating point arithmetic is not
312 exact, it is often a bad idea to check for equality of two floating
313 point values. Usually it is better to test for approximate equality.
314 Here's a function to do this:
317 (defvar fuzz-factor 1.0e-6)
318 (defun approx-equal (x y)
319 (or (and (= x 0) (= y 0))
321 (max (abs x) (abs y)))
325 @cindex CL note---integers vrs @code{eq}
327 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
328 @code{=} because Common Lisp implements multi-word integers, and two
329 distinct integer objects can have the same numeric value. Emacs Lisp
330 can have just one integer object for any given value because it has a
331 limited range of integer values.
334 @defun = number-or-marker1 number-or-marker2
335 This function tests whether its arguments are numerically equal, and
336 returns @code{t} if so, @code{nil} otherwise.
339 @defun eql value1 value2
340 This function acts like @code{eq} except when both arguments are
341 numbers. It compares numbers by type and numeric value, so that
342 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
343 @code{(eql 1 1)} both return @code{t}.
346 @defun /= number-or-marker1 number-or-marker2
347 This function tests whether its arguments are numerically equal, and
348 returns @code{t} if they are not, and @code{nil} if they are.
351 @defun < number-or-marker1 number-or-marker2
352 This function tests whether its first argument is strictly less than
353 its second argument. It returns @code{t} if so, @code{nil} otherwise.
356 @defun <= number-or-marker1 number-or-marker2
357 This function tests whether its first argument is less than or equal
358 to its second argument. It returns @code{t} if so, @code{nil}
362 @defun > number-or-marker1 number-or-marker2
363 This function tests whether its first argument is strictly greater
364 than its second argument. It returns @code{t} if so, @code{nil}
368 @defun >= number-or-marker1 number-or-marker2
369 This function tests whether its first argument is greater than or
370 equal to its second argument. It returns @code{t} if so, @code{nil}
374 @defun max number-or-marker &rest numbers-or-markers
375 This function returns the largest of its arguments.
376 If any of the arguments is floating-point, the value is returned
377 as floating point, even if it was given as an integer.
389 @defun min number-or-marker &rest numbers-or-markers
390 This function returns the smallest of its arguments.
391 If any of the arguments is floating-point, the value is returned
392 as floating point, even if it was given as an integer.
401 This function returns the absolute value of @var{number}.
404 @node Numeric Conversions
405 @section Numeric Conversions
406 @cindex rounding in conversions
407 @cindex number conversions
408 @cindex converting numbers
410 To convert an integer to floating point, use the function @code{float}.
413 This returns @var{number} converted to floating point.
414 If @var{number} is already a floating point number, @code{float} returns
418 There are four functions to convert floating point numbers to integers;
419 they differ in how they round. All accept an argument @var{number}
420 and an optional argument @var{divisor}. Both arguments may be
421 integers or floating point numbers. @var{divisor} may also be
422 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
423 functions convert @var{number} to an integer, or return it unchanged
424 if it already is an integer. If @var{divisor} is non-@code{nil}, they
425 divide @var{number} by @var{divisor} and convert the result to an
426 integer. An @code{arith-error} results if @var{divisor} is 0.
428 @defun truncate number &optional divisor
429 This returns @var{number}, converted to an integer by rounding towards
444 @defun floor number &optional divisor
445 This returns @var{number}, converted to an integer by rounding downward
446 (towards negative infinity).
448 If @var{divisor} is specified, this uses the kind of division
449 operation that corresponds to @code{mod}, rounding downward.
465 @defun ceiling number &optional divisor
466 This returns @var{number}, converted to an integer by rounding upward
467 (towards positive infinity).
481 @defun round number &optional divisor
482 This returns @var{number}, converted to an integer by rounding towards the
483 nearest integer. Rounding a value equidistant between two integers
484 may choose the integer closer to zero, or it may prefer an even integer,
485 depending on your machine.
499 @node Arithmetic Operations
500 @section Arithmetic Operations
501 @cindex arithmetic operations
503 Emacs Lisp provides the traditional four arithmetic operations:
504 addition, subtraction, multiplication, and division. Remainder and modulus
505 functions supplement the division functions. The functions to
506 add or subtract 1 are provided because they are traditional in Lisp and
509 All of these functions except @code{%} return a floating point value
510 if any argument is floating.
512 It is important to note that in Emacs Lisp, arithmetic functions
513 do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to
514 @minus{}536870912, depending on your hardware.
516 @defun 1+ number-or-marker
517 This function returns @var{number-or-marker} plus 1.
527 This function is not analogous to the C operator @code{++}---it does not
528 increment a variable. It just computes a sum. Thus, if we continue,
535 If you want to increment the variable, you must use @code{setq},
544 @defun 1- number-or-marker
545 This function returns @var{number-or-marker} minus 1.
548 @defun + &rest numbers-or-markers
549 This function adds its arguments together. When given no arguments,
562 @defun - &optional number-or-marker &rest more-numbers-or-markers
563 The @code{-} function serves two purposes: negation and subtraction.
564 When @code{-} has a single argument, the value is the negative of the
565 argument. When there are multiple arguments, @code{-} subtracts each of
566 the @var{more-numbers-or-markers} from @var{number-or-marker},
567 cumulatively. If there are no arguments, the result is 0.
579 @defun * &rest numbers-or-markers
580 This function multiplies its arguments together, and returns the
581 product. When given no arguments, @code{*} returns 1.
593 @defun / dividend divisor &rest divisors
594 This function divides @var{dividend} by @var{divisor} and returns the
595 quotient. If there are additional arguments @var{divisors}, then it
596 divides @var{dividend} by each divisor in turn. Each argument may be a
599 If all the arguments are integers, then the result is an integer too.
600 This means the result has to be rounded. On most machines, the result
601 is rounded towards zero after each division, but some machines may round
602 differently with negative arguments. This is because the Lisp function
603 @code{/} is implemented using the C division operator, which also
604 permits machine-dependent rounding. As a practical matter, all known
605 machines round in the standard fashion.
607 @cindex @code{arith-error} in division
608 If you divide an integer by 0, an @code{arith-error} error is signaled.
609 (@xref{Errors}.) Floating point division by zero returns either
610 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
611 otherwise, it signals an @code{arith-error} error.
630 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
635 @defun % dividend divisor
637 This function returns the integer remainder after division of @var{dividend}
638 by @var{divisor}. The arguments must be integers or markers.
640 For negative arguments, the remainder is in principle machine-dependent
641 since the quotient is; but in practice, all known machines behave alike.
643 An @code{arith-error} results if @var{divisor} is 0.
656 For any two integers @var{dividend} and @var{divisor},
660 (+ (% @var{dividend} @var{divisor})
661 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
666 always equals @var{dividend}.
669 @defun mod dividend divisor
671 This function returns the value of @var{dividend} modulo @var{divisor};
672 in other words, the remainder after division of @var{dividend}
673 by @var{divisor}, but with the same sign as @var{divisor}.
674 The arguments must be numbers or markers.
676 Unlike @code{%}, @code{mod} returns a well-defined result for negative
677 arguments. It also permits floating point arguments; it rounds the
678 quotient downward (towards minus infinity) to an integer, and uses that
679 quotient to compute the remainder.
681 An @code{arith-error} results if @var{divisor} is 0.
706 For any two numbers @var{dividend} and @var{divisor},
710 (+ (mod @var{dividend} @var{divisor})
711 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
716 always equals @var{dividend}, subject to rounding error if either
717 argument is floating point. For @code{floor}, see @ref{Numeric
721 @node Rounding Operations
722 @section Rounding Operations
723 @cindex rounding without conversion
725 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
726 @code{ftruncate} take a floating point argument and return a floating
727 point result whose value is a nearby integer. @code{ffloor} returns the
728 nearest integer below; @code{fceiling}, the nearest integer above;
729 @code{ftruncate}, the nearest integer in the direction towards zero;
730 @code{fround}, the nearest integer.
733 This function rounds @var{float} to the next lower integral value, and
734 returns that value as a floating point number.
737 @defun fceiling float
738 This function rounds @var{float} to the next higher integral value, and
739 returns that value as a floating point number.
742 @defun ftruncate float
743 This function rounds @var{float} towards zero to an integral value, and
744 returns that value as a floating point number.
748 This function rounds @var{float} to the nearest integral value,
749 and returns that value as a floating point number.
752 @node Bitwise Operations
753 @section Bitwise Operations on Integers
754 @cindex bitwise arithmetic
755 @cindex logical arithmetic
757 In a computer, an integer is represented as a binary number, a
758 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
759 operation acts on the individual bits of such a sequence. For example,
760 @dfn{shifting} moves the whole sequence left or right one or more places,
761 reproducing the same pattern ``moved over.''
763 The bitwise operations in Emacs Lisp apply only to integers.
765 @defun lsh integer1 count
766 @cindex logical shift
767 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
768 bits in @var{integer1} to the left @var{count} places, or to the right
769 if @var{count} is negative, bringing zeros into the vacated bits. If
770 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
771 (most-significant) bit, producing a positive result even if
772 @var{integer1} is negative. Contrast this with @code{ash}, below.
774 Here are two examples of @code{lsh}, shifting a pattern of bits one
775 place to the left. We show only the low-order eight bits of the binary
776 pattern; the rest are all zero.
782 ;; @r{Decimal 5 becomes decimal 10.}
783 00000101 @result{} 00001010
787 ;; @r{Decimal 7 becomes decimal 14.}
788 00000111 @result{} 00001110
793 As the examples illustrate, shifting the pattern of bits one place to
794 the left produces a number that is twice the value of the previous
797 Shifting a pattern of bits two places to the left produces results
798 like this (with 8-bit binary numbers):
804 ;; @r{Decimal 3 becomes decimal 12.}
805 00000011 @result{} 00001100
809 On the other hand, shifting one place to the right looks like this:
815 ;; @r{Decimal 6 becomes decimal 3.}
816 00000110 @result{} 00000011
822 ;; @r{Decimal 5 becomes decimal 2.}
823 00000101 @result{} 00000010
828 As the example illustrates, shifting one place to the right divides the
829 value of a positive integer by two, rounding downward.
831 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
832 not check for overflow, so shifting left can discard significant bits
833 and change the sign of the number. For example, left shifting
834 536,870,911 produces @minus{}2 in the 30-bit implementation:
837 (lsh 536870911 1) ; @r{left shift}
841 In binary, the argument looks like this:
845 ;; @r{Decimal 536,870,911}
846 0111...111111 (30 bits total)
851 which becomes the following when left shifted:
855 ;; @r{Decimal @minus{}2}
856 1111...111110 (30 bits total)
861 @defun ash integer1 count
862 @cindex arithmetic shift
863 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
864 to the left @var{count} places, or to the right if @var{count}
867 @code{ash} gives the same results as @code{lsh} except when
868 @var{integer1} and @var{count} are both negative. In that case,
869 @code{ash} puts ones in the empty bit positions on the left, while
870 @code{lsh} puts zeros in those bit positions.
872 Thus, with @code{ash}, shifting the pattern of bits one place to the right
877 (ash -6 -1) @result{} -3
878 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
879 1111...111010 (30 bits total)
881 1111...111101 (30 bits total)
885 In contrast, shifting the pattern of bits one place to the right with
886 @code{lsh} looks like this:
890 (lsh -6 -1) @result{} 536870909
891 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
892 1111...111010 (30 bits total)
894 0111...111101 (30 bits total)
898 Here are other examples:
900 @c !!! Check if lined up in smallbook format! XDVI shows problem
901 @c with smallbook but not with regular book! --rjc 16mar92
904 ; @r{ 30-bit binary values}
906 (lsh 5 2) ; 5 = @r{0000...000101}
907 @result{} 20 ; = @r{0000...010100}
912 (lsh -5 2) ; -5 = @r{1111...111011}
913 @result{} -20 ; = @r{1111...101100}
918 (lsh 5 -2) ; 5 = @r{0000...000101}
919 @result{} 1 ; = @r{0000...000001}
926 (lsh -5 -2) ; -5 = @r{1111...111011}
928 ; = @r{0011...111110}
931 (ash -5 -2) ; -5 = @r{1111...111011}
932 @result{} -2 ; = @r{1111...111110}
937 @defun logand &rest ints-or-markers
938 This function returns the ``logical and'' of the arguments: the
939 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
940 set in all the arguments. (``Set'' means that the value of the bit is 1
943 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
944 12 is 12: 1101 combined with 1100 produces 1100.
945 In both the binary numbers, the leftmost two bits are set (i.e., they
946 are 1's), so the leftmost two bits of the returned value are set.
947 However, for the rightmost two bits, each is zero in at least one of
948 the arguments, so the rightmost two bits of the returned value are 0's.
960 If @code{logand} is not passed any argument, it returns a value of
961 @minus{}1. This number is an identity element for @code{logand}
962 because its binary representation consists entirely of ones. If
963 @code{logand} is passed just one argument, it returns that argument.
967 ; @r{ 30-bit binary values}
969 (logand 14 13) ; 14 = @r{0000...001110}
970 ; 13 = @r{0000...001101}
971 @result{} 12 ; 12 = @r{0000...001100}
975 (logand 14 13 4) ; 14 = @r{0000...001110}
976 ; 13 = @r{0000...001101}
977 ; 4 = @r{0000...000100}
978 @result{} 4 ; 4 = @r{0000...000100}
983 @result{} -1 ; -1 = @r{1111...111111}
988 @defun logior &rest ints-or-markers
989 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
990 is set in the result if, and only if, the @var{n}th bit is set in at least
991 one of the arguments. If there are no arguments, the result is zero,
992 which is an identity element for this operation. If @code{logior} is
993 passed just one argument, it returns that argument.
997 ; @r{ 30-bit binary values}
999 (logior 12 5) ; 12 = @r{0000...001100}
1000 ; 5 = @r{0000...000101}
1001 @result{} 13 ; 13 = @r{0000...001101}
1005 (logior 12 5 7) ; 12 = @r{0000...001100}
1006 ; 5 = @r{0000...000101}
1007 ; 7 = @r{0000...000111}
1008 @result{} 15 ; 15 = @r{0000...001111}
1013 @defun logxor &rest ints-or-markers
1014 This function returns the ``exclusive or'' of its arguments: the
1015 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1016 set in an odd number of the arguments. If there are no arguments, the
1017 result is 0, which is an identity element for this operation. If
1018 @code{logxor} is passed just one argument, it returns that argument.
1022 ; @r{ 30-bit binary values}
1024 (logxor 12 5) ; 12 = @r{0000...001100}
1025 ; 5 = @r{0000...000101}
1026 @result{} 9 ; 9 = @r{0000...001001}
1030 (logxor 12 5 7) ; 12 = @r{0000...001100}
1031 ; 5 = @r{0000...000101}
1032 ; 7 = @r{0000...000111}
1033 @result{} 14 ; 14 = @r{0000...001110}
1038 @defun lognot integer
1039 This function returns the logical complement of its argument: the @var{n}th
1040 bit is one in the result if, and only if, the @var{n}th bit is zero in
1041 @var{integer}, and vice-versa.
1046 ;; 5 = @r{0000...000101} (30 bits total)
1048 ;; -6 = @r{1111...111010} (30 bits total)
1052 @node Math Functions
1053 @section Standard Mathematical Functions
1054 @cindex transcendental functions
1055 @cindex mathematical functions
1056 @cindex floating-point functions
1058 These mathematical functions allow integers as well as floating point
1059 numbers as arguments.
1064 These are the ordinary trigonometric functions, with argument measured
1069 The value of @code{(asin @var{arg})} is a number between
1083 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1084 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1088 The value of @code{(acos @var{arg})} is a number between 0 and
1095 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1096 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1099 @defun atan y &optional x
1100 The value of @code{(atan @var{y})} is a number between
1114 (exclusive) whose tangent is @var{y}. If the optional second
1115 argument @var{x} is given, the value of @code{(atan y x)} is the
1116 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1121 This is the exponential function; it returns
1128 to the power @var{arg}.
1135 is a fundamental mathematical constant also called the base of natural
1139 @defun log arg &optional base
1140 This function returns the logarithm of @var{arg}, with base @var{base}.
1141 If you don't specify @var{base}, the base
1148 is used. If @var{arg} is negative, it signals a @code{domain-error}
1154 This function returns @code{(1- (exp @var{arg}))}, but it is more
1155 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1160 This function returns @code{(log (1+ @var{arg}))}, but it is more
1161 accurate than that when @var{arg} is so small that adding 1 to it would
1167 This function returns the logarithm of @var{arg}, with base 10. If
1168 @var{arg} is negative, it signals a @code{domain-error} error.
1169 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1174 This function returns @var{x} raised to power @var{y}. If both
1175 arguments are integers and @var{y} is positive, the result is an
1176 integer; in this case, overflow causes truncation, so watch out.
1180 This returns the square root of @var{arg}. If @var{arg} is negative,
1181 it signals a @code{domain-error} error.
1184 @node Random Numbers
1185 @section Random Numbers
1186 @cindex random numbers
1188 A deterministic computer program cannot generate true random numbers.
1189 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1190 pseudo-random numbers is generated in a deterministic fashion. The
1191 numbers are not truly random, but they have certain properties that
1192 mimic a random series. For example, all possible values occur equally
1193 often in a pseudo-random series.
1195 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1196 Starting from any given seed, the @code{random} function always
1197 generates the same sequence of numbers. Emacs always starts with the
1198 same seed value, so the sequence of values of @code{random} is actually
1199 the same in each Emacs run! For example, in one operating system, the
1200 first call to @code{(random)} after you start Emacs always returns
1201 @minus{}1457731, and the second one always returns @minus{}7692030. This
1202 repeatability is helpful for debugging.
1204 If you want random numbers that don't always come out the same, execute
1205 @code{(random t)}. This chooses a new seed based on the current time of
1206 day and on Emacs's process @acronym{ID} number.
1208 @defun random &optional limit
1209 This function returns a pseudo-random integer. Repeated calls return a
1210 series of pseudo-random integers.
1212 If @var{limit} is a positive integer, the value is chosen to be
1213 nonnegative and less than @var{limit}.
1215 If @var{limit} is @code{t}, it means to choose a new seed based on the
1216 current time of day and on Emacs's process @acronym{ID} number.
1217 @c "Emacs'" is incorrect usage!
1219 On some machines, any integer representable in Lisp may be the result
1220 of @code{random}. On other machines, the result can never be larger
1221 than a certain maximum or less than a certain (negative) minimum.