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,
172 which 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{(/ 0.0 0.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
193 @code{=} consider them equal values).
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 eql value1 value2
312 This function compares two floating point numbers like @code{=}, and
313 compares two integers like @code{=}, and acts like @code{eq} in all
314 other cases. Thus, @code{(eql 1.0 1)} returns @code{nil}, but
315 @code{(eql 1.0 1.0)} and @code{(eql 1 1)} both return @code{t}.
318 @defun /= number-or-marker1 number-or-marker2
319 This function tests whether its arguments are numerically equal, and
320 returns @code{t} if they are not, and @code{nil} if they are.
323 @defun < number-or-marker1 number-or-marker2
324 This function tests whether its first argument is strictly less than
325 its second argument. It returns @code{t} if so, @code{nil} otherwise.
328 @defun <= number-or-marker1 number-or-marker2
329 This function tests whether its first argument is less than or equal
330 to its second argument. It returns @code{t} if so, @code{nil}
334 @defun > number-or-marker1 number-or-marker2
335 This function tests whether its first argument is strictly greater
336 than its second argument. It returns @code{t} if so, @code{nil}
340 @defun >= number-or-marker1 number-or-marker2
341 This function tests whether its first argument is greater than or
342 equal to its second argument. It returns @code{t} if so, @code{nil}
346 @defun max number-or-marker &rest numbers-or-markers
347 This function returns the largest of its arguments.
348 If any of the argument is floating-point, the value is returned
349 as floating point, even if it was given as an integer.
361 @defun min number-or-marker &rest numbers-or-markers
362 This function returns the smallest of its arguments.
363 If any of the argument is floating-point, the value is returned
364 as floating point, even if it was given as an integer.
373 This function returns the absolute value of @var{number}.
376 @node Numeric Conversions
377 @section Numeric Conversions
378 @cindex rounding in conversions
380 To convert an integer to floating point, use the function @code{float}.
383 This returns @var{number} converted to floating point.
384 If @var{number} is already a floating point number, @code{float} returns
388 There are four functions to convert floating point numbers to integers;
389 they differ in how they round. All accept an argument @var{number}
390 and an optional argument @var{divisor}. Both arguments may be
391 integers or floating point numbers. @var{divisor} may also be
392 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
393 functions convert @var{number} to an integer, or return it unchanged
394 if it already is an integer. If @var{divisor} is non-@code{nil}, they
395 divide @var{number} by @var{divisor} and convert the result to an
396 integer. An @code{arith-error} results if @var{divisor} is 0.
398 @defun truncate number &optional divisor
399 This returns @var{number}, converted to an integer by rounding towards
414 @defun floor number &optional divisor
415 This returns @var{number}, converted to an integer by rounding downward
416 (towards negative infinity).
418 If @var{divisor} is specified, this uses the kind of division
419 operation that corresponds to @code{mod}, rounding downward.
435 @defun ceiling number &optional divisor
436 This returns @var{number}, converted to an integer by rounding upward
437 (towards positive infinity).
451 @defun round number &optional divisor
452 This returns @var{number}, converted to an integer by rounding towards the
453 nearest integer. Rounding a value equidistant between two integers
454 may choose the integer closer to zero, or it may prefer an even integer,
455 depending on your machine.
469 @node Arithmetic Operations
470 @section Arithmetic Operations
472 Emacs Lisp provides the traditional four arithmetic operations:
473 addition, subtraction, multiplication, and division. Remainder and modulus
474 functions supplement the division functions. The functions to
475 add or subtract 1 are provided because they are traditional in Lisp and
478 All of these functions except @code{%} return a floating point value
479 if any argument is floating.
481 It is important to note that in Emacs Lisp, arithmetic functions
482 do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to
483 @minus{}268435456, depending on your hardware.
485 @defun 1+ number-or-marker
486 This function returns @var{number-or-marker} plus 1.
496 This function is not analogous to the C operator @code{++}---it does not
497 increment a variable. It just computes a sum. Thus, if we continue,
504 If you want to increment the variable, you must use @code{setq},
513 @defun 1- number-or-marker
514 This function returns @var{number-or-marker} minus 1.
517 @defun + &rest numbers-or-markers
518 This function adds its arguments together. When given no arguments,
531 @defun - &optional number-or-marker &rest more-numbers-or-markers
532 The @code{-} function serves two purposes: negation and subtraction.
533 When @code{-} has a single argument, the value is the negative of the
534 argument. When there are multiple arguments, @code{-} subtracts each of
535 the @var{more-numbers-or-markers} from @var{number-or-marker},
536 cumulatively. If there are no arguments, the result is 0.
548 @defun * &rest numbers-or-markers
549 This function multiplies its arguments together, and returns the
550 product. When given no arguments, @code{*} returns 1.
562 @defun / dividend divisor &rest divisors
563 This function divides @var{dividend} by @var{divisor} and returns the
564 quotient. If there are additional arguments @var{divisors}, then it
565 divides @var{dividend} by each divisor in turn. Each argument may be a
568 If all the arguments are integers, then the result is an integer too.
569 This means the result has to be rounded. On most machines, the result
570 is rounded towards zero after each division, but some machines may round
571 differently with negative arguments. This is because the Lisp function
572 @code{/} is implemented using the C division operator, which also
573 permits machine-dependent rounding. As a practical matter, all known
574 machines round in the standard fashion.
576 @cindex @code{arith-error} in division
577 If you divide an integer by 0, an @code{arith-error} error is signaled.
578 (@xref{Errors}.) Floating point division by zero returns either
579 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
580 otherwise, it signals an @code{arith-error} error.
601 The result of @code{(/ -17 6)} could in principle be -3 on some
605 @defun % dividend divisor
607 This function returns the integer remainder after division of @var{dividend}
608 by @var{divisor}. The arguments must be integers or markers.
610 For negative arguments, the remainder is in principle machine-dependent
611 since the quotient is; but in practice, all known machines behave alike.
613 An @code{arith-error} results if @var{divisor} is 0.
626 For any two integers @var{dividend} and @var{divisor},
630 (+ (% @var{dividend} @var{divisor})
631 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
636 always equals @var{dividend}.
639 @defun mod dividend divisor
641 This function returns the value of @var{dividend} modulo @var{divisor};
642 in other words, the remainder after division of @var{dividend}
643 by @var{divisor}, but with the same sign as @var{divisor}.
644 The arguments must be numbers or markers.
646 Unlike @code{%}, @code{mod} returns a well-defined result for negative
647 arguments. It also permits floating point arguments; it rounds the
648 quotient downward (towards minus infinity) to an integer, and uses that
649 quotient to compute the remainder.
651 An @code{arith-error} results if @var{divisor} is 0.
676 For any two numbers @var{dividend} and @var{divisor},
680 (+ (mod @var{dividend} @var{divisor})
681 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
686 always equals @var{dividend}, subject to rounding error if either
687 argument is floating point. For @code{floor}, see @ref{Numeric
691 @node Rounding Operations
692 @section Rounding Operations
693 @cindex rounding without conversion
695 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
696 @code{ftruncate} take a floating point argument and return a floating
697 point result whose value is a nearby integer. @code{ffloor} returns the
698 nearest integer below; @code{fceiling}, the nearest integer above;
699 @code{ftruncate}, the nearest integer in the direction towards zero;
700 @code{fround}, the nearest integer.
703 This function rounds @var{float} to the next lower integral value, and
704 returns that value as a floating point number.
707 @defun fceiling float
708 This function rounds @var{float} to the next higher integral value, and
709 returns that value as a floating point number.
712 @defun ftruncate float
713 This function rounds @var{float} towards zero to an integral value, and
714 returns that value as a floating point number.
718 This function rounds @var{float} to the nearest integral value,
719 and returns that value as a floating point number.
722 @node Bitwise Operations
723 @section Bitwise Operations on Integers
725 In a computer, an integer is represented as a binary number, a
726 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
727 operation acts on the individual bits of such a sequence. For example,
728 @dfn{shifting} moves the whole sequence left or right one or more places,
729 reproducing the same pattern ``moved over''.
731 The bitwise operations in Emacs Lisp apply only to integers.
733 @defun lsh integer1 count
734 @cindex logical shift
735 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
736 bits in @var{integer1} to the left @var{count} places, or to the right
737 if @var{count} is negative, bringing zeros into the vacated bits. If
738 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
739 (most-significant) bit, producing a positive result even if
740 @var{integer1} is negative. Contrast this with @code{ash}, below.
742 Here are two examples of @code{lsh}, shifting a pattern of bits one
743 place to the left. We show only the low-order eight bits of the binary
744 pattern; the rest are all zero.
750 ;; @r{Decimal 5 becomes decimal 10.}
751 00000101 @result{} 00001010
755 ;; @r{Decimal 7 becomes decimal 14.}
756 00000111 @result{} 00001110
761 As the examples illustrate, shifting the pattern of bits one place to
762 the left produces a number that is twice the value of the previous
765 Shifting a pattern of bits two places to the left produces results
766 like this (with 8-bit binary numbers):
772 ;; @r{Decimal 3 becomes decimal 12.}
773 00000011 @result{} 00001100
777 On the other hand, shifting one place to the right looks like this:
783 ;; @r{Decimal 6 becomes decimal 3.}
784 00000110 @result{} 00000011
790 ;; @r{Decimal 5 becomes decimal 2.}
791 00000101 @result{} 00000010
796 As the example illustrates, shifting one place to the right divides the
797 value of a positive integer by two, rounding downward.
799 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
800 not check for overflow, so shifting left can discard significant bits
801 and change the sign of the number. For example, left shifting
802 268,435,455 produces @minus{}2 on a 29-bit machine:
805 (lsh 268435455 1) ; @r{left shift}
809 In binary, in the 29-bit implementation, the argument looks like this:
813 ;; @r{Decimal 268,435,455}
814 0 1111 1111 1111 1111 1111 1111 1111
819 which becomes the following when left shifted:
823 ;; @r{Decimal @minus{}2}
824 1 1111 1111 1111 1111 1111 1111 1110
829 @defun ash integer1 count
830 @cindex arithmetic shift
831 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
832 to the left @var{count} places, or to the right if @var{count}
835 @code{ash} gives the same results as @code{lsh} except when
836 @var{integer1} and @var{count} are both negative. In that case,
837 @code{ash} puts ones in the empty bit positions on the left, while
838 @code{lsh} puts zeros in those bit positions.
840 Thus, with @code{ash}, shifting the pattern of bits one place to the right
845 (ash -6 -1) @result{} -3
846 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
847 1 1111 1111 1111 1111 1111 1111 1010
849 1 1111 1111 1111 1111 1111 1111 1101
853 In contrast, shifting the pattern of bits one place to the right with
854 @code{lsh} looks like this:
858 (lsh -6 -1) @result{} 268435453
859 ;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
860 1 1111 1111 1111 1111 1111 1111 1010
862 0 1111 1111 1111 1111 1111 1111 1101
866 Here are other examples:
868 @c !!! Check if lined up in smallbook format! XDVI shows problem
869 @c with smallbook but not with regular book! --rjc 16mar92
872 ; @r{ 29-bit binary values}
874 (lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
875 @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100}
880 (lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
881 @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100}
886 (lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
887 @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001}
894 (lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
895 @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110}
898 (ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
899 @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110}
904 @defun logand &rest ints-or-markers
907 This function returns the ``logical and'' of the arguments: the
908 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
909 set in all the arguments. (``Set'' means that the value of the bit is 1
912 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
913 12 is 12: 1101 combined with 1100 produces 1100.
914 In both the binary numbers, the leftmost two bits are set (i.e., they
915 are 1's), so the leftmost two bits of the returned value are set.
916 However, for the rightmost two bits, each is zero in at least one of
917 the arguments, so the rightmost two bits of the returned value are 0's.
929 If @code{logand} is not passed any argument, it returns a value of
930 @minus{}1. This number is an identity element for @code{logand}
931 because its binary representation consists entirely of ones. If
932 @code{logand} is passed just one argument, it returns that argument.
936 ; @r{ 29-bit binary values}
938 (logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
939 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
940 @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
944 (logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
945 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
946 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
947 @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
952 @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111}
957 @defun logior &rest ints-or-markers
958 @cindex logical inclusive or
960 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
961 is set in the result if, and only if, the @var{n}th bit is set in at least
962 one of the arguments. If there are no arguments, the result is zero,
963 which is an identity element for this operation. If @code{logior} is
964 passed just one argument, it returns that argument.
968 ; @r{ 29-bit binary values}
970 (logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
971 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
972 @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
976 (logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
977 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
978 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
979 @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111}
984 @defun logxor &rest ints-or-markers
985 @cindex bitwise exclusive or
986 @cindex logical exclusive or
987 This function returns the ``exclusive or'' of its arguments: the
988 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
989 set in an odd number of the arguments. If there are no arguments, the
990 result is 0, which is an identity element for this operation. If
991 @code{logxor} is passed just one argument, it returns that argument.
995 ; @r{ 29-bit binary values}
997 (logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
998 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
999 @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001}
1003 (logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
1004 ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
1005 ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
1006 @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
1011 @defun lognot integer
1014 This function returns the logical complement of its argument: the @var{n}th
1015 bit is one in the result if, and only if, the @var{n}th bit is zero in
1016 @var{integer}, and vice-versa.
1021 ;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
1023 ;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010}
1027 @node Math Functions
1028 @section Standard Mathematical Functions
1029 @cindex transcendental functions
1030 @cindex mathematical functions
1032 These mathematical functions allow integers as well as floating point
1033 numbers as arguments.
1038 These are the ordinary trigonometric functions, with argument measured
1043 The value of @code{(asin @var{arg})} is a number between
1057 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1058 range (outside [-1, 1]), it signals a @code{domain-error} error.
1062 The value of @code{(acos @var{arg})} is a number between 0 and
1069 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1070 of range (outside [-1, 1]), it signals a @code{domain-error} error.
1073 @defun atan y &optional x
1074 The value of @code{(atan @var{y})} is a number between
1088 (exclusive) whose tangent is @var{y}. If the optional second
1089 argument @var{x} is given, the value of @code{(atan y x)} is the
1090 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1095 This is the exponential function; it returns
1102 to the power @var{arg}.
1109 is a fundamental mathematical constant also called the base of natural
1113 @defun log arg &optional base
1114 This function returns the logarithm of @var{arg}, with base @var{base}.
1115 If you don't specify @var{base}, the base
1122 is used. If @var{arg} is negative, it signals a @code{domain-error}
1128 This function returns @code{(1- (exp @var{arg}))}, but it is more
1129 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1134 This function returns @code{(log (1+ @var{arg}))}, but it is more
1135 accurate than that when @var{arg} is so small that adding 1 to it would
1141 This function returns the logarithm of @var{arg}, with base 10. If
1142 @var{arg} is negative, it signals a @code{domain-error} error.
1143 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1148 This function returns @var{x} raised to power @var{y}. If both
1149 arguments are integers and @var{y} is positive, the result is an
1150 integer; in this case, it is truncated to fit the range of possible
1155 This returns the square root of @var{arg}. If @var{arg} is negative,
1156 it signals a @code{domain-error} error.
1159 @node Random Numbers
1160 @section Random Numbers
1161 @cindex random numbers
1163 A deterministic computer program cannot generate true random numbers.
1164 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1165 pseudo-random numbers is generated in a deterministic fashion. The
1166 numbers are not truly random, but they have certain properties that
1167 mimic a random series. For example, all possible values occur equally
1168 often in a pseudo-random series.
1170 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1171 Starting from any given seed, the @code{random} function always
1172 generates the same sequence of numbers. Emacs always starts with the
1173 same seed value, so the sequence of values of @code{random} is actually
1174 the same in each Emacs run! For example, in one operating system, the
1175 first call to @code{(random)} after you start Emacs always returns
1176 -1457731, and the second one always returns -7692030. This
1177 repeatability is helpful for debugging.
1179 If you want random numbers that don't always come out the same, execute
1180 @code{(random t)}. This chooses a new seed based on the current time of
1181 day and on Emacs's process @acronym{ID} number.
1183 @defun random &optional limit
1184 This function returns a pseudo-random integer. Repeated calls return a
1185 series of pseudo-random integers.
1187 If @var{limit} is a positive integer, the value is chosen to be
1188 nonnegative and less than @var{limit}.
1190 If @var{limit} is @code{t}, it means to choose a new seed based on the
1191 current time of day and on Emacs's process @acronym{ID} number.
1192 @c "Emacs'" is incorrect usage!
1194 On some machines, any integer representable in Lisp may be the result
1195 of @code{random}. On other machines, the result can never be larger
1196 than a certain maximum or less than a certain (negative) minimum.
1200 arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e