2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
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{}268435456 to 268435455 (29 bits; i.e.,
53 but some machines may provide a wider range. Many examples in this
54 chapter assume an integer has 29 bits.
57 The Lisp reader reads an integer as a sequence of digits with optional
58 initial sign and optional final period.
61 1 ; @r{The integer 1.}
62 1. ; @r{The integer 1.}
63 +1 ; @r{Also the integer 1.}
64 -1 ; @r{The integer @minus{}1.}
65 536870913 ; @r{Also the integer 1, due to overflow.}
66 0 ; @r{The integer 0.}
67 -0 ; @r{The integer 0.}
70 @cindex integers in specific radix
71 @cindex radix for reading an integer
72 @cindex base for reading an integer
75 @cindex reading numbers in hex, octal, and binary
76 In addition, the Lisp reader recognizes a syntax for integers in
77 bases other than 10: @samp{#B@var{integer}} reads @var{integer} in
78 binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal
79 (radix 8), @samp{#X@var{integer}} reads @var{integer} in hexadecimal
80 (radix 16), and @samp{#@var{radix}r@var{integer}} reads @var{integer}
81 in radix @var{radix} (where @var{radix} is between 2 and 36,
82 inclusively). Case is not significant for the letter after @samp{#}
83 (@samp{B}, @samp{O}, etc.) that denotes the radix.
85 To understand how various functions work on integers, especially the
86 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
87 view the numbers in their binary form.
89 In 29-bit binary, the decimal integer 5 looks like this:
92 0 0000 0000 0000 0000 0000 0000 0101
96 (We have inserted spaces between groups of 4 bits, and two spaces
97 between groups of 8 bits, to make the binary integer easier to read.)
99 The integer @minus{}1 looks like this:
102 1 1111 1111 1111 1111 1111 1111 1111
106 @cindex two's complement
107 @minus{}1 is represented as 29 ones. (This is called @dfn{two's
108 complement} notation.)
110 The negative integer, @minus{}5, is creating by subtracting 4 from
111 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
112 @minus{}5 looks like this:
115 1 1111 1111 1111 1111 1111 1111 1011
118 In this implementation, the largest 29-bit binary integer value is
119 268,435,455 in decimal. In binary, it looks like this:
122 0 1111 1111 1111 1111 1111 1111 1111
125 Since the arithmetic functions do not check whether integers go
126 outside their range, when you add 1 to 268,435,455, the value is the
127 negative integer @minus{}268,435,456:
132 @result{} 1 0000 0000 0000 0000 0000 0000 0000
135 Many of the functions described in this chapter accept markers for
136 arguments in place of numbers. (@xref{Markers}.) Since the actual
137 arguments to such functions may be either numbers or markers, we often
138 give these arguments the name @var{number-or-marker}. When the argument
139 value is a marker, its position value is used and its buffer is ignored.
141 @defvar most-positive-fixnum
142 The value of this variable is the largest integer that Emacs Lisp
146 @defvar most-negative-fixnum
147 The value of this variable is the smallest integer that Emacs Lisp can
148 handle. It is negative.
152 @section Floating Point Basics
154 Floating point numbers are useful for representing numbers that are
155 not integral. The precise range of floating point numbers is
156 machine-specific; it is the same as the range of the C data type
157 @code{double} on the machine you are using.
159 The read-syntax for floating point numbers requires either a decimal
160 point (with at least one digit following), an exponent, or both. For
161 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
162 @samp{.15e4} are five ways of writing a floating point number whose
163 value is 1500. They are all equivalent. You can also use a minus sign
164 to write negative floating point numbers, as in @samp{-1.0}.
166 @cindex @acronym{IEEE} floating point
167 @cindex positive infinity
168 @cindex negative infinity
171 Most modern computers support the @acronym{IEEE} floating point standard, which
172 provides for positive infinity and negative infinity as floating point
173 values. It also provides for a class of values called NaN or
174 ``not-a-number''; numerical functions return such values in cases where
175 there is no correct answer. For example, @code{(sqrt -1.0)} returns a
176 NaN. For practical purposes, there's no significant difference between
177 different NaN values in Emacs Lisp, and there's no rule for precisely
178 which NaN value should be used in a particular case, so Emacs Lisp
179 doesn't try to distinguish them. Here are the read syntaxes for
180 these special floating point values:
183 @item positive infinity
185 @item negative infinity
191 In addition, the value @code{-0.0} is distinguishable from ordinary
192 zero in @acronym{IEEE} floating point (although @code{equal} and @code{=} consider
195 You can use @code{logb} to extract the binary exponent of a floating
196 point number (or estimate the logarithm of an integer):
199 This function returns the binary exponent of @var{number}. More
200 precisely, the value is the logarithm of @var{number} base 2, rounded
211 @node Predicates on Numbers
212 @section Type Predicates for Numbers
214 The functions in this section test whether the argument is a number or
215 whether it is a certain sort of number. The functions @code{integerp}
216 and @code{floatp} can take any type of Lisp object as argument (the
217 predicates would not be of much use otherwise); but the @code{zerop}
218 predicate requires a number as its argument. See also
219 @code{integer-or-marker-p} and @code{number-or-marker-p}, in
220 @ref{Predicates on Markers}.
223 This predicate tests whether its argument is a floating point
224 number and returns @code{t} if so, @code{nil} otherwise.
226 @code{floatp} does not exist in Emacs versions 18 and earlier.
229 @defun integerp object
230 This predicate tests whether its argument is an integer, and returns
231 @code{t} if so, @code{nil} otherwise.
234 @defun numberp object
235 This predicate tests whether its argument is a number (either integer or
236 floating point), and returns @code{t} if so, @code{nil} otherwise.
239 @defun wholenump object
240 @cindex natural numbers
241 The @code{wholenump} predicate (whose name comes from the phrase
242 ``whole-number-p'') tests to see whether its argument is a nonnegative
243 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
244 considered non-negative.
247 @code{natnump} is an obsolete synonym for @code{wholenump}.
251 This predicate tests whether its argument is zero, and returns @code{t}
252 if so, @code{nil} otherwise. The argument must be a number.
254 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
257 @node Comparison of Numbers
258 @section Comparison of Numbers
259 @cindex number equality
261 To test numbers for numerical equality, you should normally use
262 @code{=}, not @code{eq}. There can be many distinct floating point
263 number objects with the same numeric value. If you use @code{eq} to
264 compare them, then you test whether two values are the same
265 @emph{object}. By contrast, @code{=} compares only the numeric values
268 At present, each integer value has a unique Lisp object in Emacs Lisp.
269 Therefore, @code{eq} is equivalent to @code{=} where integers are
270 concerned. It is sometimes convenient to use @code{eq} for comparing an
271 unknown value with an integer, because @code{eq} does not report an
272 error if the unknown value is not a number---it accepts arguments of any
273 type. By contrast, @code{=} signals an error if the arguments are not
274 numbers or markers. However, it is a good idea to use @code{=} if you
275 can, even for comparing integers, just in case we change the
276 representation of integers in a future Emacs version.
278 Sometimes it is useful to compare numbers with @code{equal}; it treats
279 two numbers as equal if they have the same data type (both integers, or
280 both floating point) and the same value. By contrast, @code{=} can
281 treat an integer and a floating point number as equal.
283 There is another wrinkle: because floating point arithmetic is not
284 exact, it is often a bad idea to check for equality of two floating
285 point values. Usually it is better to test for approximate equality.
286 Here's a function to do this:
289 (defvar fuzz-factor 1.0e-6)
290 (defun approx-equal (x y)
291 (or (and (= x 0) (= y 0))
293 (max (abs x) (abs y)))
297 @cindex CL note---integers vrs @code{eq}
299 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
300 @code{=} because Common Lisp implements multi-word integers, and two
301 distinct integer objects can have the same numeric value. Emacs Lisp
302 can have just one integer object for any given value because it has a
303 limited range of integer values.
306 @defun = number-or-marker1 number-or-marker2
307 This function tests whether its arguments are numerically equal, and
308 returns @code{t} if so, @code{nil} otherwise.
311 @defun /= number-or-marker1 number-or-marker2
312 This function tests whether its arguments are numerically equal, and
313 returns @code{t} if they are not, and @code{nil} if they are.
316 @defun < number-or-marker1 number-or-marker2
317 This function tests whether its first argument is strictly less than
318 its second argument. It returns @code{t} if so, @code{nil} otherwise.
321 @defun <= number-or-marker1 number-or-marker2
322 This function tests whether its first argument is less than or equal
323 to its second argument. It returns @code{t} if so, @code{nil}
327 @defun > number-or-marker1 number-or-marker2
328 This function tests whether its first argument is strictly greater
329 than its second argument. It returns @code{t} if so, @code{nil}
333 @defun >= number-or-marker1 number-or-marker2
334 This function tests whether its first argument is greater than or
335 equal to its second argument. It returns @code{t} if so, @code{nil}
339 @defun max number-or-marker &rest numbers-or-markers
340 This function returns the largest of its arguments.
341 If any of the argument is floating-point, the value is returned
342 as floating point, even if it was given as an integer.
354 @defun min number-or-marker &rest numbers-or-markers
355 This function returns the smallest of its arguments.
356 If any of the argument is floating-point, the value is returned
357 as floating point, even if it was given as an integer.
366 This function returns the absolute value of @var{number}.
369 @node Numeric Conversions
370 @section Numeric Conversions
371 @cindex rounding in conversions
373 To convert an integer to floating point, use the function @code{float}.
376 This returns @var{number} converted to floating point.
377 If @var{number} is already a floating point number, @code{float} returns
381 There are four functions to convert floating point numbers to integers;
382 they differ in how they round. These functions accept integer arguments
383 also, and return such arguments unchanged.
385 @defun truncate number
386 This returns @var{number}, converted to an integer by rounding towards
401 @defun floor number &optional divisor
402 This returns @var{number}, converted to an integer by rounding downward
403 (towards negative infinity).
405 If @var{divisor} is specified, @code{floor} divides @var{number} by
406 @var{divisor} and then converts to an integer; this uses the kind of
407 division operation that corresponds to @code{mod}, rounding downward.
408 An @code{arith-error} results if @var{divisor} is 0.
424 @defun ceiling number
425 This returns @var{number}, converted to an integer by rounding upward
426 (towards positive infinity).
441 This returns @var{number}, converted to an integer by rounding towards the
442 nearest integer. Rounding a value equidistant between two integers
443 may choose the integer closer to zero, or it may prefer an even integer,
444 depending on your machine.
458 @node Arithmetic Operations
459 @section Arithmetic Operations
461 Emacs Lisp provides the traditional four arithmetic operations:
462 addition, subtraction, multiplication, and division. Remainder and modulus
463 functions supplement the division functions. The functions to
464 add or subtract 1 are provided because they are traditional in Lisp and
467 All of these functions except @code{%} return a floating point value
468 if any argument is floating.
470 It is important to note that in Emacs Lisp, arithmetic functions
471 do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to
472 @minus{}268435456, depending on your hardware.
474 @defun 1+ number-or-marker
475 This function returns @var{number-or-marker} plus 1.
485 This function is not analogous to the C operator @code{++}---it does not
486 increment a variable. It just computes a sum. Thus, if we continue,
493 If you want to increment the variable, you must use @code{setq},
502 @defun 1- number-or-marker
503 This function returns @var{number-or-marker} minus 1.
506 @defun + &rest numbers-or-markers
507 This function adds its arguments together. When given no arguments,
520 @defun - &optional number-or-marker &rest more-numbers-or-markers
521 The @code{-} function serves two purposes: negation and subtraction.
522 When @code{-} has a single argument, the value is the negative of the
523 argument. When there are multiple arguments, @code{-} subtracts each of
524 the @var{more-numbers-or-markers} from @var{number-or-marker},
525 cumulatively. If there are no arguments, the result is 0.
537 @defun * &rest numbers-or-markers
538 This function multiplies its arguments together, and returns the
539 product. When given no arguments, @code{*} returns 1.
551 @defun / dividend divisor &rest divisors
552 This function divides @var{dividend} by @var{divisor} and returns the
553 quotient. If there are additional arguments @var{divisors}, then it
554 divides @var{dividend} by each divisor in turn. Each argument may be a
557 If all the arguments are integers, then the result is an integer too.
558 This means the result has to be rounded. On most machines, the result
559 is rounded towards zero after each division, but some machines may round
560 differently with negative arguments. This is because the Lisp function
561 @code{/} is implemented using the C division operator, which also
562 permits machine-dependent rounding. As a practical matter, all known
563 machines round in the standard fashion.
565 @cindex @code{arith-error} in division
566 If you divide an integer by 0, an @code{arith-error} error is signaled.
567 (@xref{Errors}.) Floating point division by zero returns either
568 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
569 otherwise, it signals an @code{arith-error} error.
590 The result of @code{(/ -17 6)} could in principle be -3 on some
594 @defun % dividend divisor
596 This function returns the integer remainder after division of @var{dividend}
597 by @var{divisor}. The arguments must be integers or markers.
599 For negative arguments, the remainder is in principle machine-dependent
600 since the quotient is; but in practice, all known machines behave alike.
602 An @code{arith-error} results if @var{divisor} is 0.
615 For any two integers @var{dividend} and @var{divisor},
619 (+ (% @var{dividend} @var{divisor})
620 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
625 always equals @var{dividend}.
628 @defun mod dividend divisor
630 This function returns the value of @var{dividend} modulo @var{divisor};
631 in other words, the remainder after division of @var{dividend}
632 by @var{divisor}, but with the same sign as @var{divisor}.
633 The arguments must be numbers or markers.
635 Unlike @code{%}, @code{mod} returns a well-defined result for negative
636 arguments. It also permits floating point arguments; it rounds the
637 quotient downward (towards minus infinity) to an integer, and uses that
638 quotient to compute the remainder.
640 An @code{arith-error} results if @var{divisor} is 0.
665 For any two numbers @var{dividend} and @var{divisor},
669 (+ (mod @var{dividend} @var{divisor})
670 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
675 always equals @var{dividend}, subject to rounding error if either
676 argument is floating point. For @code{floor}, see @ref{Numeric
680 @node Rounding Operations
681 @section Rounding Operations
682 @cindex rounding without conversion
684 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
685 @code{ftruncate} take a floating point argument and return a floating
686 point result whose value is a nearby integer. @code{ffloor} returns the
687 nearest integer below; @code{fceiling}, the nearest integer above;
688 @code{ftruncate}, the nearest integer in the direction towards zero;
689 @code{fround}, the nearest integer.
692 This function rounds @var{float} to the next lower integral value, and
693 returns that value as a floating point number.
696 @defun fceiling float
697 This function rounds @var{float} to the next higher integral value, and
698 returns that value as a floating point number.
701 @defun ftruncate float
702 This function rounds @var{float} towards zero to an integral value, and
703 returns that value as a floating point number.
707 This function rounds @var{float} to the nearest integral value,
708 and returns that value as a floating point number.
711 @node Bitwise Operations
712 @section Bitwise Operations on Integers
714 In a computer, an integer is represented as a binary number, a
715 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
716 operation acts on the individual bits of such a sequence. For example,
717 @dfn{shifting} moves the whole sequence left or right one or more places,
718 reproducing the same pattern ``moved over''.
720 The bitwise operations in Emacs Lisp apply only to integers.
722 @defun lsh integer1 count
723 @cindex logical shift
724 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
725 bits in @var{integer1} to the left @var{count} places, or to the right
726 if @var{count} is negative, bringing zeros into the vacated bits. If
727 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
728 (most-significant) bit, producing a positive result even if
729 @var{integer1} is negative. Contrast this with @code{ash}, below.
731 Here are two examples of @code{lsh}, shifting a pattern of bits one
732 place to the left. We show only the low-order eight bits of the binary
733 pattern; the rest are all zero.
739 ;; @r{Decimal 5 becomes decimal 10.}
740 00000101 @result{} 00001010
744 ;; @r{Decimal 7 becomes decimal 14.}
745 00000111 @result{} 00001110
750 As the examples illustrate, shifting the pattern of bits one place to
751 the left produces a number that is twice the value of the previous
754 Shifting a pattern of bits two places to the left produces results
755 like this (with 8-bit binary numbers):
761 ;; @r{Decimal 3 becomes decimal 12.}
762 00000011 @result{} 00001100
766 On the other hand, shifting one place to the right looks like this:
772 ;; @r{Decimal 6 becomes decimal 3.}
773 00000110 @result{} 00000011
779 ;; @r{Decimal 5 becomes decimal 2.}
780 00000101 @result{} 00000010
785 As the example illustrates, shifting one place to the right divides the
786 value of a positive integer by two, rounding downward.
788 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
789 not check for overflow, so shifting left can discard significant bits
790 and change the sign of the number. For example, left shifting
791 268,435,455 produces @minus{}2 on a 29-bit machine:
794 (lsh 268435455 1) ; @r{left shift}
798 In binary, in the 29-bit implementation, the argument looks like this:
802 ;; @r{Decimal 268,435,455}
803 0 1111 1111 1111 1111 1111 1111 1111
808 which becomes the following when left shifted:
812 ;; @r{Decimal @minus{}2}
813 1 1111 1111 1111 1111 1111 1111 1110
818 @defun ash integer1 count
819 @cindex arithmetic shift
820 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
821 to the left @var{count} places, or to the right if @var{count}
824 @code{ash} gives the same results as @code{lsh} except when
825 @var{integer1} and @var{count} are both negative. In that case,
826 @code{ash} puts ones in the empty bit positions on the left, while
827 @code{lsh} puts zeros in those bit positions.
829 Thus, with @code{ash}, shifting the pattern of bits one place to the right
834 (ash -6 -1) @result{} -3
835 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
836 1 1111 1111 1111 1111 1111 1111 1010
838 1 1111 1111 1111 1111 1111 1111 1101
842 In contrast, shifting the pattern of bits one place to the right with
843 @code{lsh} looks like this:
847 (lsh -6 -1) @result{} 268435453
848 ;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
849 1 1111 1111 1111 1111 1111 1111 1010
851 0 1111 1111 1111 1111 1111 1111 1101
855 Here are other examples:
857 @c !!! Check if lined up in smallbook format! XDVI shows problem
858 @c with smallbook but not with regular book! --rjc 16mar92
861 ; @r{ 29-bit binary values}
863 (lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
864 @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100}
869 (lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
870 @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100}
875 (lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
876 @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001}
883 (lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
884 @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110}
887 (ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
888 @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110}
893 @defun logand &rest ints-or-markers
896 This function returns the ``logical and'' of the arguments: the
897 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
898 set in all the arguments. (``Set'' means that the value of the bit is 1
901 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
902 12 is 12: 1101 combined with 1100 produces 1100.
903 In both the binary numbers, the leftmost two bits are set (i.e., they
904 are 1's), so the leftmost two bits of the returned value are set.
905 However, for the rightmost two bits, each is zero in at least one of
906 the arguments, so the rightmost two bits of the returned value are 0's.
918 If @code{logand} is not passed any argument, it returns a value of
919 @minus{}1. This number is an identity element for @code{logand}
920 because its binary representation consists entirely of ones. If
921 @code{logand} is passed just one argument, it returns that argument.
925 ; @r{ 29-bit binary values}
927 (logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
928 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
929 @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
933 (logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
934 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
935 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
936 @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
941 @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111}
946 @defun logior &rest ints-or-markers
947 @cindex logical inclusive or
949 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
950 is set in the result if, and only if, the @var{n}th bit is set in at least
951 one of the arguments. If there are no arguments, the result is zero,
952 which is an identity element for this operation. If @code{logior} is
953 passed just one argument, it returns that argument.
957 ; @r{ 29-bit binary values}
959 (logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
960 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
961 @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
965 (logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
966 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
967 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
968 @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111}
973 @defun logxor &rest ints-or-markers
974 @cindex bitwise exclusive or
975 @cindex logical exclusive or
976 This function returns the ``exclusive or'' of its arguments: the
977 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
978 set in an odd number of the arguments. If there are no arguments, the
979 result is 0, which is an identity element for this operation. If
980 @code{logxor} is passed just one argument, it returns that argument.
984 ; @r{ 29-bit binary values}
986 (logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
987 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
988 @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001}
992 (logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
993 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
994 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
995 @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
1000 @defun lognot integer
1003 This function returns the logical complement of its argument: the @var{n}th
1004 bit is one in the result if, and only if, the @var{n}th bit is zero in
1005 @var{integer}, and vice-versa.
1010 ;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
1012 ;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010}
1016 @node Math Functions
1017 @section Standard Mathematical Functions
1018 @cindex transcendental functions
1019 @cindex mathematical functions
1021 These mathematical functions allow integers as well as floating point
1022 numbers as arguments.
1027 These are the ordinary trigonometric functions, with argument measured
1032 The value of @code{(asin @var{arg})} is a number between
1046 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
1047 is out of range (outside [-1, 1]), then the result is a NaN.
1051 The value of @code{(acos @var{arg})} is a number between 0 and
1058 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
1059 is out of range (outside [-1, 1]), then the result is a NaN.
1062 @defun atan y &optional x
1063 The value of @code{(atan @var{y})} is a number between
1077 (exclusive) whose tangent is @var{y}. If the optional second
1078 argument @var{x} is given, the value of @code{(atan y x)} is the
1079 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1084 This is the exponential function; it returns
1091 to the power @var{arg}.
1098 is a fundamental mathematical constant also called the base of natural
1102 @defun log arg &optional base
1103 This function returns the logarithm of @var{arg}, with base @var{base}.
1104 If you don't specify @var{base}, the base
1111 is used. If @var{arg}
1112 is negative, the result is a NaN.
1117 This function returns @code{(1- (exp @var{arg}))}, but it is more
1118 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1123 This function returns @code{(log (1+ @var{arg}))}, but it is more
1124 accurate than that when @var{arg} is so small that adding 1 to it would
1130 This function returns the logarithm of @var{arg}, with base 10. If
1131 @var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
1132 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1136 This function returns @var{x} raised to power @var{y}. If both
1137 arguments are integers and @var{y} is positive, the result is an
1138 integer; in this case, it is truncated to fit the range of possible
1143 This returns the square root of @var{arg}. If @var{arg} is negative,
1147 @node Random Numbers
1148 @section Random Numbers
1149 @cindex random numbers
1151 A deterministic computer program cannot generate true random numbers.
1152 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1153 pseudo-random numbers is generated in a deterministic fashion. The
1154 numbers are not truly random, but they have certain properties that
1155 mimic a random series. For example, all possible values occur equally
1156 often in a pseudo-random series.
1158 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1159 Starting from any given seed, the @code{random} function always
1160 generates the same sequence of numbers. Emacs always starts with the
1161 same seed value, so the sequence of values of @code{random} is actually
1162 the same in each Emacs run! For example, in one operating system, the
1163 first call to @code{(random)} after you start Emacs always returns
1164 -1457731, and the second one always returns -7692030. This
1165 repeatability is helpful for debugging.
1167 If you want random numbers that don't always come out the same, execute
1168 @code{(random t)}. This chooses a new seed based on the current time of
1169 day and on Emacs's process @acronym{ID} number.
1171 @defun random &optional limit
1172 This function returns a pseudo-random integer. Repeated calls return a
1173 series of pseudo-random integers.
1175 If @var{limit} is a positive integer, the value is chosen to be
1176 nonnegative and less than @var{limit}.
1178 If @var{limit} is @code{t}, it means to choose a new seed based on the
1179 current time of day and on Emacs's process @acronym{ID} number.
1180 @c "Emacs'" is incorrect usage!
1182 On some machines, any integer representable in Lisp may be the result
1183 of @code{random}. On other machines, the result can never be larger
1184 than a certain maximum or less than a certain (negative) minimum.
1188 arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e