2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
11 GNU Emacs supports two numeric data types: @dfn{integers} and
12 @dfn{floating point numbers}. Integers are whole numbers such as
13 @minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
14 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
15 2.71828. They can also be expressed in exponential notation: 1.5e2
16 equals 150; in this example, @samp{e2} stands for ten to the second
17 power, and that is multiplied by 1.5. Floating point values are not
18 exact; they have a fixed, limited amount of precision.
21 * Integer Basics:: Representation and range of integers.
22 * Float Basics:: Representation and range of floating point.
23 * Predicates on Numbers:: Testing for numbers.
24 * Comparison of Numbers:: Equality and inequality predicates.
25 * Numeric Conversions:: Converting float to integer and vice versa.
26 * Arithmetic Operations:: How to add, subtract, multiply and divide.
27 * Rounding Operations:: Explicitly rounding floating point numbers.
28 * Bitwise Operations:: Logical and, or, not, shifting.
29 * Math Functions:: Trig, exponential and logarithmic functions.
30 * Random Numbers:: Obtaining random integers, predictable or not.
34 @section Integer Basics
36 The range of values for an integer depends on the machine. The
37 minimum range is @minus{}536870912 to 536870911 (30 bits; i.e.,
51 but some machines provide a wider range. Many examples in this
52 chapter assume that an integer has 30 bits and that floating point
53 numbers are IEEE double precision.
56 The Lisp reader reads an integer as a sequence of digits with optional
57 initial sign and optional final period. An integer that is out of the
58 Emacs range is treated as a floating-point number.
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 1073741825 ; @r{The floating point number 1073741825.0.}
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 The syntax for integers in bases other than 10 uses @samp{#}
77 followed by a letter that specifies the radix: @samp{b} for binary,
78 @samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
79 specify radix @var{radix}. Case is not significant for the letter
80 that specifies the radix. Thus, @samp{#b@var{integer}} reads
81 @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
82 @var{integer} in radix @var{radix}. Allowed values of @var{radix} run
83 from 2 to 36. For example:
92 To understand how various functions work on integers, especially the
93 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
94 view the numbers in their binary form.
96 In 30-bit binary, the decimal integer 5 looks like this:
99 0000...000101 (30 bits total)
103 (The @samp{...} stands for enough bits to fill out a 30-bit word; in
104 this case, @samp{...} stands for twenty 0 bits. Later examples also
105 use the @samp{...} notation to make binary integers easier to read.)
107 The integer @minus{}1 looks like this:
110 1111...111111 (30 bits total)
114 @cindex two's complement
115 @minus{}1 is represented as 30 ones. (This is called @dfn{two's
116 complement} notation.)
118 The negative integer, @minus{}5, is creating by subtracting 4 from
119 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
120 @minus{}5 looks like this:
123 1111...111011 (30 bits total)
126 In this implementation, the largest 30-bit binary integer value is
127 536,870,911 in decimal. In binary, it looks like this:
130 0111...111111 (30 bits total)
133 Since the arithmetic functions do not check whether integers go
134 outside their range, when you add 1 to 536,870,911, the value is the
135 negative integer @minus{}536,870,912:
140 @result{} 1000...000000 (30 bits total)
143 Many of the functions described in this chapter accept markers for
144 arguments in place of numbers. (@xref{Markers}.) Since the actual
145 arguments to such functions may be either numbers or markers, we often
146 give these arguments the name @var{number-or-marker}. When the argument
147 value is a marker, its position value is used and its buffer is ignored.
149 @cindex largest Lisp integer number
150 @cindex maximum Lisp integer number
151 @defvar most-positive-fixnum
152 The value of this variable is the largest integer that Emacs Lisp
156 @cindex smallest Lisp integer number
157 @cindex minimum Lisp integer number
158 @defvar most-negative-fixnum
159 The value of this variable is the smallest integer that Emacs Lisp can
160 handle. It is negative.
163 @xref{Character Codes, max-char}, for the maximum value of a valid
167 @section Floating Point Basics
169 @cindex @acronym{IEEE} floating point
170 Floating point numbers are useful for representing numbers that are
171 not integral. The precise range of floating point numbers is
172 machine-specific; it is the same as the range of the C data type
173 @code{double} on the machine you are using. Emacs uses the
174 @acronym{IEEE} floating point standard where possible (the standard is
175 supported by most modern computers).
177 The read syntax for floating point numbers requires either a decimal
178 point (with at least one digit following), an exponent, or both. For
179 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
180 @samp{.15e4} are five ways of writing a floating point number whose
181 value is 1500. They are all equivalent. You can also use a minus
182 sign to write negative floating point numbers, as in @samp{-1.0}.
184 Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with
185 respect to @code{equal} and @code{=}), even though the two are
186 distinguishable in the @acronym{IEEE} floating point standard.
188 @cindex positive infinity
189 @cindex negative infinity
192 The @acronym{IEEE} floating point standard supports positive
193 infinity and negative infinity as floating point values. It also
194 provides for a class of values called NaN or ``not-a-number'';
195 numerical functions return such values in cases where there is no
196 correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN. (NaN
197 values can also carry a sign, but for practical purposes there's no
198 significant difference between different NaN values in Emacs Lisp.)
200 When a function is documented to return a NaN, it returns an
201 implementation-defined value when Emacs is running on one of the
202 now-rare platforms that do not use @acronym{IEEE} floating point. For
203 example, @code{(log -1.0)} typically returns a NaN, but on
204 non-@acronym{IEEE} platforms it returns an implementation-defined
207 Here are the read syntaxes for these special floating point values:
210 @item positive infinity
212 @item negative infinity
215 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
219 This predicate tests whether its argument is NaN, and returns @code{t}
220 if so, @code{nil} otherwise. The argument must be a number.
223 The following functions are specialized for handling floating point
227 This function returns a cons cell @code{(@var{sig} . @var{exp})},
228 where @var{sig} and @var{exp} are respectively the significand and
229 exponent of the floating point number @var{x}:
232 @var{x} = @var{sig} * 2^@var{exp}
235 @var{sig} is a floating point number between 0.5 (inclusive) and 1.0
236 (exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}.
239 @defun ldexp sig &optional exp
240 This function returns a floating point number corresponding to the
241 significand @var{sig} and exponent @var{exp}.
244 @defun copysign x1 x2
245 This function copies the sign of @var{x2} to the value of @var{x1},
246 and returns the result. @var{x1} and @var{x2} must be floating point
251 This function returns the binary exponent of @var{number}. More
252 precisely, the value is the logarithm of |@var{number}| base 2, rounded
263 @node Predicates on Numbers
264 @section Type Predicates for Numbers
265 @cindex predicates for numbers
267 The functions in this section test for numbers, or for a specific
268 type of number. The functions @code{integerp} and @code{floatp} can
269 take any type of Lisp object as argument (they would not be of much
270 use otherwise), but the @code{zerop} predicate requires a number as
271 its argument. See also @code{integer-or-marker-p} and
272 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
275 This predicate tests whether its argument is a floating point
276 number and returns @code{t} if so, @code{nil} otherwise.
279 @defun integerp object
280 This predicate tests whether its argument is an integer, and returns
281 @code{t} if so, @code{nil} otherwise.
284 @defun numberp object
285 This predicate tests whether its argument is a number (either integer or
286 floating point), and returns @code{t} if so, @code{nil} otherwise.
289 @defun natnump object
290 @cindex natural numbers
291 This predicate (whose name comes from the phrase ``natural number'')
292 tests to see whether its argument is a nonnegative integer, and
293 returns @code{t} if so, @code{nil} otherwise. 0 is considered
296 @findex wholenump number
297 This is a synonym for @code{natnump}.
301 This predicate tests whether its argument is zero, and returns @code{t}
302 if so, @code{nil} otherwise. The argument must be a number.
304 @code{(zerop x)} is equivalent to @code{(= x 0)}.
307 @node Comparison of Numbers
308 @section Comparison of Numbers
309 @cindex number comparison
310 @cindex comparing numbers
312 To test numbers for numerical equality, you should normally use
313 @code{=}, not @code{eq}. There can be many distinct floating point
314 number objects with the same numeric value. If you use @code{eq} to
315 compare them, then you test whether two values are the same
316 @emph{object}. By contrast, @code{=} compares only the numeric values
319 At present, each integer value has a unique Lisp object in Emacs Lisp.
320 Therefore, @code{eq} is equivalent to @code{=} where integers are
321 concerned. It is sometimes convenient to use @code{eq} for comparing an
322 unknown value with an integer, because @code{eq} does not report an
323 error if the unknown value is not a number---it accepts arguments of any
324 type. By contrast, @code{=} signals an error if the arguments are not
325 numbers or markers. However, it is a good idea to use @code{=} if you
326 can, even for comparing integers, just in case we change the
327 representation of integers in a future Emacs version.
329 Sometimes it is useful to compare numbers with @code{equal}; it
330 treats two numbers as equal if they have the same data type (both
331 integers, or both floating point) and the same value. By contrast,
332 @code{=} can treat an integer and a floating point number as equal.
333 @xref{Equality Predicates}.
335 There is another wrinkle: because floating point arithmetic is not
336 exact, it is often a bad idea to check for equality of two floating
337 point values. Usually it is better to test for approximate equality.
338 Here's a function to do this:
341 (defvar fuzz-factor 1.0e-6)
342 (defun approx-equal (x y)
343 (or (and (= x 0) (= y 0))
345 (max (abs x) (abs y)))
349 @cindex CL note---integers vrs @code{eq}
351 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
352 @code{=} because Common Lisp implements multi-word integers, and two
353 distinct integer objects can have the same numeric value. Emacs Lisp
354 can have just one integer object for any given value because it has a
355 limited range of integer values.
358 @defun = number-or-marker1 number-or-marker2
359 This function tests whether its arguments are numerically equal, and
360 returns @code{t} if so, @code{nil} otherwise.
363 @defun eql value1 value2
364 This function acts like @code{eq} except when both arguments are
365 numbers. It compares numbers by type and numeric value, so that
366 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
367 @code{(eql 1 1)} both return @code{t}.
370 @defun /= number-or-marker1 number-or-marker2
371 This function tests whether its arguments are numerically equal, and
372 returns @code{t} if they are not, and @code{nil} if they are.
375 @defun < number-or-marker1 number-or-marker2
376 This function tests whether its first argument is strictly less than
377 its second argument. It returns @code{t} if so, @code{nil} otherwise.
380 @defun <= number-or-marker1 number-or-marker2
381 This function tests whether its first argument is less than or equal
382 to its second argument. It returns @code{t} if so, @code{nil}
386 @defun > number-or-marker1 number-or-marker2
387 This function tests whether its first argument is strictly greater
388 than its second argument. It returns @code{t} if so, @code{nil}
392 @defun >= number-or-marker1 number-or-marker2
393 This function tests whether its first argument is greater than or
394 equal to its second argument. It returns @code{t} if so, @code{nil}
398 @defun max number-or-marker &rest numbers-or-markers
399 This function returns the largest of its arguments.
400 If any of the arguments is floating-point, the value is returned
401 as floating point, even if it was given as an integer.
413 @defun min number-or-marker &rest numbers-or-markers
414 This function returns the smallest of its arguments.
415 If any of the arguments is floating-point, the value is returned
416 as floating point, even if it was given as an integer.
425 This function returns the absolute value of @var{number}.
428 @node Numeric Conversions
429 @section Numeric Conversions
430 @cindex rounding in conversions
431 @cindex number conversions
432 @cindex converting numbers
434 To convert an integer to floating point, use the function @code{float}.
437 This returns @var{number} converted to floating point.
438 If @var{number} is already a floating point number, @code{float} returns
442 There are four functions to convert floating point numbers to integers;
443 they differ in how they round. All accept an argument @var{number}
444 and an optional argument @var{divisor}. Both arguments may be
445 integers or floating point numbers. @var{divisor} may also be
446 @code{nil}. If @var{divisor} is @code{nil} or omitted, these
447 functions convert @var{number} to an integer, or return it unchanged
448 if it already is an integer. If @var{divisor} is non-@code{nil}, they
449 divide @var{number} by @var{divisor} and convert the result to an
450 integer. An @code{arith-error} results if @var{divisor} is 0.
452 @defun truncate number &optional divisor
453 This returns @var{number}, converted to an integer by rounding towards
468 @defun floor number &optional divisor
469 This returns @var{number}, converted to an integer by rounding downward
470 (towards negative infinity).
472 If @var{divisor} is specified, this uses the kind of division
473 operation that corresponds to @code{mod}, rounding downward.
489 @defun ceiling number &optional divisor
490 This returns @var{number}, converted to an integer by rounding upward
491 (towards positive infinity).
505 @defun round number &optional divisor
506 This returns @var{number}, converted to an integer by rounding towards the
507 nearest integer. Rounding a value equidistant between two integers
508 may choose the integer closer to zero, or it may prefer an even integer,
509 depending on your machine.
523 @node Arithmetic Operations
524 @section Arithmetic Operations
525 @cindex arithmetic operations
527 Emacs Lisp provides the traditional four arithmetic operations:
528 addition, subtraction, multiplication, and division. Remainder and modulus
529 functions supplement the division functions. The functions to
530 add or subtract 1 are provided because they are traditional in Lisp and
533 All of these functions except @code{%} return a floating point value
534 if any argument is floating.
536 It is important to note that in Emacs Lisp, arithmetic functions
537 do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to
538 @minus{}536870912, depending on your hardware.
540 @defun 1+ number-or-marker
541 This function returns @var{number-or-marker} plus 1.
551 This function is not analogous to the C operator @code{++}---it does not
552 increment a variable. It just computes a sum. Thus, if we continue,
559 If you want to increment the variable, you must use @code{setq},
568 @defun 1- number-or-marker
569 This function returns @var{number-or-marker} minus 1.
572 @defun + &rest numbers-or-markers
573 This function adds its arguments together. When given no arguments,
586 @defun - &optional number-or-marker &rest more-numbers-or-markers
587 The @code{-} function serves two purposes: negation and subtraction.
588 When @code{-} has a single argument, the value is the negative of the
589 argument. When there are multiple arguments, @code{-} subtracts each of
590 the @var{more-numbers-or-markers} from @var{number-or-marker},
591 cumulatively. If there are no arguments, the result is 0.
603 @defun * &rest numbers-or-markers
604 This function multiplies its arguments together, and returns the
605 product. When given no arguments, @code{*} returns 1.
617 @defun / dividend divisor &rest divisors
618 This function divides @var{dividend} by @var{divisor} and returns the
619 quotient. If there are additional arguments @var{divisors}, then it
620 divides @var{dividend} by each divisor in turn. Each argument may be a
623 If all the arguments are integers, then the result is an integer too.
624 This means the result has to be rounded. On most machines, the result
625 is rounded towards zero after each division, but some machines may round
626 differently with negative arguments. This is because the Lisp function
627 @code{/} is implemented using the C division operator, which also
628 permits machine-dependent rounding. As a practical matter, all known
629 machines round in the standard fashion.
631 @cindex @code{arith-error} in division
632 If you divide an integer by 0, an @code{arith-error} error is signaled.
633 (@xref{Errors}.) Floating point division by zero returns either
634 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
635 otherwise, it signals an @code{arith-error} error.
654 @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
659 @defun % dividend divisor
661 This function returns the integer remainder after division of @var{dividend}
662 by @var{divisor}. The arguments must be integers or markers.
664 For negative arguments, the remainder is in principle machine-dependent
665 since the quotient is; but in practice, all known machines behave alike.
667 An @code{arith-error} results if @var{divisor} is 0.
680 For any two integers @var{dividend} and @var{divisor},
684 (+ (% @var{dividend} @var{divisor})
685 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
690 always equals @var{dividend}.
693 @defun mod dividend divisor
695 This function returns the value of @var{dividend} modulo @var{divisor};
696 in other words, the remainder after division of @var{dividend}
697 by @var{divisor}, but with the same sign as @var{divisor}.
698 The arguments must be numbers or markers.
700 Unlike @code{%}, @code{mod} returns a well-defined result for negative
701 arguments. It also permits floating point arguments; it rounds the
702 quotient downward (towards minus infinity) to an integer, and uses that
703 quotient to compute the remainder.
705 If @var{divisor} is zero, @code{mod} signals an @code{arith-error}
706 error if both arguments are integers, and returns a NaN otherwise.
731 For any two numbers @var{dividend} and @var{divisor},
735 (+ (mod @var{dividend} @var{divisor})
736 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
741 always equals @var{dividend}, subject to rounding error if either
742 argument is floating point. For @code{floor}, see @ref{Numeric
746 @node Rounding Operations
747 @section Rounding Operations
748 @cindex rounding without conversion
750 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
751 @code{ftruncate} take a floating point argument and return a floating
752 point result whose value is a nearby integer. @code{ffloor} returns the
753 nearest integer below; @code{fceiling}, the nearest integer above;
754 @code{ftruncate}, the nearest integer in the direction towards zero;
755 @code{fround}, the nearest integer.
758 This function rounds @var{float} to the next lower integral value, and
759 returns that value as a floating point number.
762 @defun fceiling float
763 This function rounds @var{float} to the next higher integral value, and
764 returns that value as a floating point number.
767 @defun ftruncate float
768 This function rounds @var{float} towards zero to an integral value, and
769 returns that value as a floating point number.
773 This function rounds @var{float} to the nearest integral value,
774 and returns that value as a floating point number.
777 @node Bitwise Operations
778 @section Bitwise Operations on Integers
779 @cindex bitwise arithmetic
780 @cindex logical arithmetic
782 In a computer, an integer is represented as a binary number, a
783 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
784 operation acts on the individual bits of such a sequence. For example,
785 @dfn{shifting} moves the whole sequence left or right one or more places,
786 reproducing the same pattern ``moved over''.
788 The bitwise operations in Emacs Lisp apply only to integers.
790 @defun lsh integer1 count
791 @cindex logical shift
792 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
793 bits in @var{integer1} to the left @var{count} places, or to the right
794 if @var{count} is negative, bringing zeros into the vacated bits. If
795 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
796 (most-significant) bit, producing a positive result even if
797 @var{integer1} is negative. Contrast this with @code{ash}, below.
799 Here are two examples of @code{lsh}, shifting a pattern of bits one
800 place to the left. We show only the low-order eight bits of the binary
801 pattern; the rest are all zero.
807 ;; @r{Decimal 5 becomes decimal 10.}
808 00000101 @result{} 00001010
812 ;; @r{Decimal 7 becomes decimal 14.}
813 00000111 @result{} 00001110
818 As the examples illustrate, shifting the pattern of bits one place to
819 the left produces a number that is twice the value of the previous
822 Shifting a pattern of bits two places to the left produces results
823 like this (with 8-bit binary numbers):
829 ;; @r{Decimal 3 becomes decimal 12.}
830 00000011 @result{} 00001100
834 On the other hand, shifting one place to the right looks like this:
840 ;; @r{Decimal 6 becomes decimal 3.}
841 00000110 @result{} 00000011
847 ;; @r{Decimal 5 becomes decimal 2.}
848 00000101 @result{} 00000010
853 As the example illustrates, shifting one place to the right divides the
854 value of a positive integer by two, rounding downward.
856 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
857 not check for overflow, so shifting left can discard significant bits
858 and change the sign of the number. For example, left shifting
859 536,870,911 produces @minus{}2 in the 30-bit implementation:
862 (lsh 536870911 1) ; @r{left shift}
866 In binary, the argument looks like this:
870 ;; @r{Decimal 536,870,911}
871 0111...111111 (30 bits total)
876 which becomes the following when left shifted:
880 ;; @r{Decimal @minus{}2}
881 1111...111110 (30 bits total)
886 @defun ash integer1 count
887 @cindex arithmetic shift
888 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
889 to the left @var{count} places, or to the right if @var{count}
892 @code{ash} gives the same results as @code{lsh} except when
893 @var{integer1} and @var{count} are both negative. In that case,
894 @code{ash} puts ones in the empty bit positions on the left, while
895 @code{lsh} puts zeros in those bit positions.
897 Thus, with @code{ash}, shifting the pattern of bits one place to the right
902 (ash -6 -1) @result{} -3
903 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
904 1111...111010 (30 bits total)
906 1111...111101 (30 bits total)
910 In contrast, shifting the pattern of bits one place to the right with
911 @code{lsh} looks like this:
915 (lsh -6 -1) @result{} 536870909
916 ;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
917 1111...111010 (30 bits total)
919 0111...111101 (30 bits total)
923 Here are other examples:
925 @c !!! Check if lined up in smallbook format! XDVI shows problem
926 @c with smallbook but not with regular book! --rjc 16mar92
929 ; @r{ 30-bit binary values}
931 (lsh 5 2) ; 5 = @r{0000...000101}
932 @result{} 20 ; = @r{0000...010100}
937 (lsh -5 2) ; -5 = @r{1111...111011}
938 @result{} -20 ; = @r{1111...101100}
943 (lsh 5 -2) ; 5 = @r{0000...000101}
944 @result{} 1 ; = @r{0000...000001}
951 (lsh -5 -2) ; -5 = @r{1111...111011}
953 ; = @r{0011...111110}
956 (ash -5 -2) ; -5 = @r{1111...111011}
957 @result{} -2 ; = @r{1111...111110}
962 @defun logand &rest ints-or-markers
963 This function returns the ``logical and'' of the arguments: the
964 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
965 set in all the arguments. (``Set'' means that the value of the bit is 1
968 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
969 12 is 12: 1101 combined with 1100 produces 1100.
970 In both the binary numbers, the leftmost two bits are set (i.e., they
971 are 1's), so the leftmost two bits of the returned value are set.
972 However, for the rightmost two bits, each is zero in at least one of
973 the arguments, so the rightmost two bits of the returned value are 0's.
985 If @code{logand} is not passed any argument, it returns a value of
986 @minus{}1. This number is an identity element for @code{logand}
987 because its binary representation consists entirely of ones. If
988 @code{logand} is passed just one argument, it returns that argument.
992 ; @r{ 30-bit binary values}
994 (logand 14 13) ; 14 = @r{0000...001110}
995 ; 13 = @r{0000...001101}
996 @result{} 12 ; 12 = @r{0000...001100}
1000 (logand 14 13 4) ; 14 = @r{0000...001110}
1001 ; 13 = @r{0000...001101}
1002 ; 4 = @r{0000...000100}
1003 @result{} 4 ; 4 = @r{0000...000100}
1008 @result{} -1 ; -1 = @r{1111...111111}
1013 @defun logior &rest ints-or-markers
1014 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
1015 is set in the result if, and only if, the @var{n}th bit is set in at least
1016 one of the arguments. If there are no arguments, the result is zero,
1017 which is an identity element for this operation. If @code{logior} is
1018 passed just one argument, it returns that argument.
1022 ; @r{ 30-bit binary values}
1024 (logior 12 5) ; 12 = @r{0000...001100}
1025 ; 5 = @r{0000...000101}
1026 @result{} 13 ; 13 = @r{0000...001101}
1030 (logior 12 5 7) ; 12 = @r{0000...001100}
1031 ; 5 = @r{0000...000101}
1032 ; 7 = @r{0000...000111}
1033 @result{} 15 ; 15 = @r{0000...001111}
1038 @defun logxor &rest ints-or-markers
1039 This function returns the ``exclusive or'' of its arguments: the
1040 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1041 set in an odd number of the arguments. If there are no arguments, the
1042 result is 0, which is an identity element for this operation. If
1043 @code{logxor} is passed just one argument, it returns that argument.
1047 ; @r{ 30-bit binary values}
1049 (logxor 12 5) ; 12 = @r{0000...001100}
1050 ; 5 = @r{0000...000101}
1051 @result{} 9 ; 9 = @r{0000...001001}
1055 (logxor 12 5 7) ; 12 = @r{0000...001100}
1056 ; 5 = @r{0000...000101}
1057 ; 7 = @r{0000...000111}
1058 @result{} 14 ; 14 = @r{0000...001110}
1063 @defun lognot integer
1064 This function returns the logical complement of its argument: the @var{n}th
1065 bit is one in the result if, and only if, the @var{n}th bit is zero in
1066 @var{integer}, and vice-versa.
1071 ;; 5 = @r{0000...000101} (30 bits total)
1073 ;; -6 = @r{1111...111010} (30 bits total)
1077 @node Math Functions
1078 @section Standard Mathematical Functions
1079 @cindex transcendental functions
1080 @cindex mathematical functions
1081 @cindex floating-point functions
1083 These mathematical functions allow integers as well as floating point
1084 numbers as arguments.
1089 These are the ordinary trigonometric functions, with argument measured
1094 The value of @code{(asin @var{arg})} is a number between
1108 (inclusive) whose sine is @var{arg}. If @var{arg} is out of range
1109 (outside [@minus{}1, 1]), @code{asin} returns a NaN.
1113 The value of @code{(acos @var{arg})} is a number between 0 and
1120 (inclusive) whose cosine is @var{arg}. If @var{arg} is out of range
1121 (outside [@minus{}1, 1]), @code{acos} returns a NaN.
1124 @defun atan y &optional x
1125 The value of @code{(atan @var{y})} is a number between
1139 (exclusive) whose tangent is @var{y}. If the optional second
1140 argument @var{x} is given, the value of @code{(atan y x)} is the
1141 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1146 This is the exponential function; it returns @math{e} to the power
1150 @defun log arg &optional base
1151 This function returns the logarithm of @var{arg}, with base
1152 @var{base}. If you don't specify @var{base}, the natural base
1153 @math{e} is used. If @var{arg} or @var{base} is negative, @code{log}
1159 This function returns @code{(1- (exp @var{arg}))}, but it is more
1160 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1165 This function returns @code{(log (1+ @var{arg}))}, but it is more
1166 accurate than that when @var{arg} is so small that adding 1 to it would
1172 This function returns the logarithm of @var{arg}, with base 10:
1173 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}.
1177 This function returns @var{x} raised to power @var{y}. If both
1178 arguments are integers and @var{y} is positive, the result is an
1179 integer; in this case, overflow causes truncation, so watch out.
1180 If @var{x} is a finite negative number and @var{y} is a finite
1181 non-integer, @code{expt} returns a NaN.
1185 This returns the square root of @var{arg}. If @var{arg} is negative,
1186 @code{sqrt} returns a NaN.
1189 In addition, Emacs defines the following common mathematical
1193 The mathematical constant @math{e} (2.71828@dots{}).
1197 The mathematical constant @math{pi} (3.14159@dots{}).
1200 @node Random Numbers
1201 @section Random Numbers
1202 @cindex random numbers
1204 A deterministic computer program cannot generate true random numbers.
1205 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1206 pseudo-random numbers is generated in a deterministic fashion. The
1207 numbers are not truly random, but they have certain properties that
1208 mimic a random series. For example, all possible values occur equally
1209 often in a pseudo-random series.
1211 In Emacs, pseudo-random numbers are generated from a ``seed''.
1212 Starting from any given seed, the @code{random} function always
1213 generates the same sequence of numbers. Emacs typically starts with a
1214 different seed each time, so the sequence of values of @code{random}
1215 typically differs in each Emacs run.
1217 Sometimes you want the random number sequence to be repeatable. For
1218 example, when debugging a program whose behavior depends on the random
1219 number sequence, it is helpful to get the same behavior in each
1220 program run. To make the sequence repeat, execute @code{(random "")}.
1221 This sets the seed to a constant value for your particular Emacs
1222 executable (though it may differ for other Emacs builds). You can use
1223 other strings to choose various seed values.
1225 @defun random &optional limit
1226 This function returns a pseudo-random integer. Repeated calls return a
1227 series of pseudo-random integers.
1229 If @var{limit} is a positive integer, the value is chosen to be
1230 nonnegative and less than @var{limit}. Otherwise, the value
1231 might be any integer representable in Lisp.
1233 If @var{limit} is @code{t}, it means to choose a new seed based on the
1234 current time of day and on Emacs's process @acronym{ID} number.
1236 If @var{limit} is a string, it means to choose a new seed based on the