2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/numbers.info
8 @node Numbers, Strings and Characters, Lisp Data Types, Top
13 SXEmacs supports two numeric data types: @dfn{integers} and
14 @dfn{floating point numbers}. Integers are whole numbers such as
15 @minus{}3, 0, #b0111, #xFEED, #o744. Their values are exact. The
16 number prefixes `#b', `#o', and `#x' are supported to represent numbers
17 in binary, octal, and hexadecimal notation (or radix). Floating point
18 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
19 2.71828. They can also be expressed in exponential notation: 1.5e2
20 equals 150; in this example, @samp{e2} stands for ten to the second
21 power, and is multiplied by 1.5. Floating point values are not exact;
22 they have a fixed, limited amount of precision.
24 SXEmacs can be compiled to use a multi-precision arithmetic library
25 with the --enable-ent switch. Currently the MP-libraries GMP,
26 BSD-MP, MPFR and MPC are supported. We have a dedicated section for
27 this case, @xref{Enhanced Number Types}.
30 * Integer Basics:: Representation and range of integers.
31 * Float Basics:: Representation and range of floating point.
32 * Predicates on Numbers:: Testing for numbers.
33 * Comparison of Numbers:: Equality and inequality predicates.
34 * Numeric Conversions:: Converting float to integer and vice versa.
35 * Arithmetic Operations:: How to add, subtract, multiply and divide.
36 * Rounding Operations:: Explicitly rounding floating point numbers.
37 * Bitwise Operations:: Logical and, or, not, shifting.
38 * Math Functions:: Trig, exponential and logarithmic functions.
39 * Random Numbers:: Obtaining random integers, predictable or not.
44 @section Integer Basics
46 The range of values for an integer depends on the machine. The
47 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
61 but some machines may provide a wider range. Many examples in this
62 chapter assume an integer has 28 bits.
65 The Lisp reader reads an integer as a sequence of digits with optional
66 initial sign and optional final period.
69 1 ; @r{The integer 1.}
70 1. ; @r{The integer 1.}
71 +1 ; @r{Also the integer 1.}
72 -1 ; @r{The integer @minus{}1.}
73 268435457 ; @r{Also the integer 1, due to overflow.}
74 0 ; @r{The integer 0.}
75 -0 ; @r{The integer 0.}
78 To understand how various functions work on integers, especially the
79 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
80 view the numbers in their binary form.
82 In 28-bit binary, the decimal integer 5 looks like this:
85 0000 0000 0000 0000 0000 0000 0101
89 (We have inserted spaces between groups of 4 bits, and two spaces
90 between groups of 8 bits, to make the binary integer easier to read.)
92 The integer @minus{}1 looks like this:
95 1111 1111 1111 1111 1111 1111 1111
99 @cindex two's complement
100 @minus{}1 is represented as 28 ones. (This is called @dfn{two's
101 complement} notation.)
103 The negative integer, @minus{}5, is creating by subtracting 4 from
104 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
105 @minus{}5 looks like this:
108 1111 1111 1111 1111 1111 1111 1011
111 In this implementation, the largest 28-bit binary integer is the
112 decimal integer 134,217,727. In binary, it looks like this:
115 0111 1111 1111 1111 1111 1111 1111
118 Since the arithmetic functions do not check whether integers go
119 outside their range, when you add 1 to 134,217,727, the value is the
120 negative integer @minus{}134,217,728:
125 @result{} 1000 0000 0000 0000 0000 0000 0000
128 Many of the following functions accept markers for arguments as well
129 as integers. (@xref{Markers}.) More precisely, the actual arguments to
130 such functions may be either integers or markers, which is why we often
131 give these arguments the name @var{int-or-marker}. When the argument
132 value is a marker, its position value is used and its buffer is ignored.
135 In version 19, except where @emph{integer} is specified as an
136 argument, all of the functions for markers and integers also work for
137 floating point numbers.
142 @section Floating Point Basics
144 SXEmacs supports floating point numbers. The precise range of floating
145 point numbers is machine-specific; it is the same as the range of the C
146 data type @code{double} on the machine in question.
148 The printed representation for floating point numbers requires either
149 a decimal point (with at least one digit following), an exponent, or
150 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
151 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
152 number whose value is 1500. They are all equivalent. You can also use
153 a minus sign to write negative floating point numbers, as in
156 Please bear in mind that floating point numbers have a limited and
157 fixed precision although the printed output may suggest something
158 else. The precision varies (depending on the machine) between 12 and
159 38 digits. Also note, that internally numbers are processed in a
160 2-adic arithmetic, hence some real numbers cannot be represented
161 precisely and are rounded to the next precisely representable float
164 @cindex IEEE floating point
165 @cindex positive infinity
166 @cindex negative infinity
170 Most modern computers support the IEEE floating point standard, which
171 provides for positive infinity and negative infinity as floating point
172 values. It also provides for a class of values called NaN or
173 ``not-a-number''; numerical functions return such values in cases where
174 there is no correct answer. For example, @code{(sqrt -1.0)} returns a
175 NaN. For practical purposes, there's no significant difference between
176 different NaN values in SXEmacs Lisp, and there's no rule for precisely
177 which NaN value should be used in a particular case, so this manual
178 doesn't try to distinguish them. SXEmacs Lisp has no read syntax for NaNs
179 or infinities; perhaps we should create a syntax in the future.
181 You can use @code{logb} to extract the binary exponent of a floating
182 point number (or estimate the logarithm of an integer):
185 This function returns the binary exponent of @var{number}. More
186 precisely, the value is the logarithm of @var{number} base 2, rounded
191 @node Predicates on Numbers
192 @section Type Predicates for Numbers
194 The functions in this section test whether the argument is a number or
195 whether it is a certain sort of number. The functions @code{integerp}
196 and @code{floatp} can take any type of Lisp object as argument (the
197 predicates would not be of much use otherwise); but the @code{zerop}
198 predicate requires a number as its argument. See also
199 @code{integer-or-marker-p}, @code{integer-char-or-marker-p},
200 @code{number-or-marker-p} and @code{number-char-or-marker-p}, in
201 @ref{Predicates on Markers}.
204 This predicate tests whether its argument is a floating point
205 number and returns @code{t} if so, @code{nil} otherwise.
207 @code{floatp} does not exist in Emacs versions 18 and earlier.
210 @defun integerp object
211 This predicate tests whether its argument is an integer, and returns
212 @code{t} if so, @code{nil} otherwise.
215 @defun numberp object
216 This predicate tests whether its argument is a number (either integer or
217 floating point), and returns @code{t} if so, @code{nil} otherwise.
220 @defun natnump object
221 @cindex natural numbers
222 The @code{natnump} predicate (whose name comes from the phrase
223 ``natural-number-p'') tests to see whether its argument is a nonnegative
224 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
225 considered non-negative.
229 This predicate tests whether its argument is zero, and returns @code{t}
230 if so, @code{nil} otherwise. The argument must be a number.
232 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
236 @node Comparison of Numbers
237 @section Comparison of Numbers
238 @cindex number equality
240 To test numbers for numerical equality, you should normally use
241 @code{=}, not @code{eq}. There can be many distinct floating point
242 number objects with the same numeric value. If you use @code{eq} to
243 compare them, then you test whether two values are the same
244 @emph{object}. By contrast, @code{=} compares only the numeric values
247 At present, each integer value has a unique Lisp object in SXEmacs Lisp.
248 Therefore, @code{eq} is equivalent to @code{=} where integers are
249 concerned. It is sometimes convenient to use @code{eq} for comparing an
250 unknown value with an integer, because @code{eq} does not report an
251 error if the unknown value is not a number---it accepts arguments of any
252 type. By contrast, @code{=} signals an error if the arguments are not
253 numbers or markers. However, it is a good idea to use @code{=} if you
254 can, even for comparing integers, just in case we change the
255 representation of integers in a future SXEmacs version.
257 There is another wrinkle: because floating point arithmetic is not
258 exact, it is often a bad idea to check for equality of two floating
259 point values. Usually it is better to test for approximate equality.
260 Here's a function to do this:
263 (defconst fuzz-factor 1.0e-6)
264 (defun approx-equal (x y)
265 (or (and (= x 0) (= y 0))
267 (max (abs x) (abs y)))
271 @cindex CL note---integers vrs @code{eq}
273 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
274 @code{=} because Common Lisp implements multi-word integers, and two
275 distinct integer objects can have the same numeric value. SXEmacs Lisp
276 can have just one integer object for any given value because it has a
277 limited range of integer values.
280 In addition to numbers, all of the following functions also accept
281 characters and markers as arguments, and treat them as their number
284 @defun = number &rest more-numbers
285 This function returns @code{t} if all of its arguments are numerically
286 equal, @code{nil} otherwise.
300 @defun /= number &rest more-numbers
301 This function returns @code{t} if no two arguments are numerically
302 equal, @code{nil} otherwise.
314 @defun < number &rest more-numbers
315 This function returns @code{t} if the sequence of its arguments is
316 monotonically increasing, @code{nil} otherwise.
328 @defun <= number &rest more-numbers
329 This function returns @code{t} if the sequence of its arguments is
330 monotonically nondecreasing, @code{nil} otherwise.
342 @defun > number &rest more-numbers
343 This function returns @code{t} if the sequence of its arguments is
344 monotonically decreasing, @code{nil} otherwise.
347 @defun >= number &rest more-numbers
348 This function returns @code{t} if the sequence of its arguments is
349 monotonically nonincreasing, @code{nil} otherwise.
352 @defun max number &rest more-numbers
353 This function returns the largest of its arguments.
365 @defun min number &rest more-numbers
366 This function returns the smallest of its arguments.
375 @node Numeric Conversions
376 @section Numeric Conversions
377 @cindex rounding in conversions
379 To convert an integer to floating point, use the function @code{float}.
382 This returns @var{number} converted to floating point.
383 If @var{number} is already a floating point number, @code{float} returns
387 There are four functions to convert floating point numbers to integers;
388 they differ in how they round. These functions accept integer arguments
389 also, and return such arguments unchanged.
391 @defun truncate number
392 This returns @var{number}, converted to an integer by rounding towards
396 @defun floor number &optional divisor
397 This returns @var{number}, converted to an integer by rounding downward
398 (towards negative infinity).
400 If @var{divisor} is specified, @var{number} is divided by @var{divisor}
401 before the floor is taken; this is the division operation that
402 corresponds to @code{mod}. An @code{arith-error} results if
406 @defun ceiling number
407 This returns @var{number}, converted to an integer by rounding upward
408 (towards positive infinity).
412 This returns @var{number}, converted to an integer by rounding towards the
413 nearest integer. Rounding a value equidistant between two integers
414 may choose the integer closer to zero, or it may prefer an even integer,
415 depending on your machine.
419 @node Arithmetic Operations
420 @section Arithmetic Operations
422 SXEmacs Lisp provides the traditional four arithmetic operations:
423 addition, subtraction, multiplication, and division. Remainder and modulus
424 functions supplement the division functions. The functions to
425 add or subtract 1 are provided because they are traditional in Lisp and
428 All of these functions except @code{%} return a floating point value
429 if any argument is floating.
431 It is important to note that in SXEmacs Lisp, arithmetic functions
432 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
433 @minus{}134217728, depending on your hardware.
436 This function returns @var{number} plus one. @var{number} may be a
437 number, character or marker. Markers and characters are converted to
449 This function is not analogous to the C operator @code{++}---it does not
450 increment a variable. It just computes a sum. Thus, if we continue,
457 If you want to increment the variable, you must use @code{setq},
465 Now that the @code{cl} package is always available from lisp code, a
466 more convenient and natural way to increment a variable is
467 @w{@code{(incf foo)}}.
471 This function returns @var{number} minus one. @var{number} may be a
472 number, character or marker. Markers and characters are converted to
477 This returns the absolute value of @var{number}.
480 @defun + &rest numbers
481 This function adds its arguments together. When given no arguments,
484 If any of the arguments are characters or markers, they are first
485 converted to integers.
497 @defun - &optional number &rest other-numbers
498 The @code{-} function serves two purposes: negation and subtraction.
499 When @code{-} has a single argument, the value is the negative of the
500 argument. When there are multiple arguments, @code{-} subtracts each of
501 the @var{other-numbers} from @var{number}, cumulatively. If there are
502 no arguments, an error is signaled.
504 If any of the arguments are characters or markers, they are first
505 converted to integers.
517 @defun * &rest numbers
518 This function multiplies its arguments together, and returns the
519 product. When given no arguments, @code{*} returns 1.
521 If any of the arguments are characters or markers, they are first
522 converted to integers.
534 @defun / dividend &rest divisors
535 The @code{/} function serves two purposes: inversion and division. When
536 @code{/} has a single argument, the value is the inverse of the
537 argument. When there are multiple arguments, @code{/} divides
538 @var{dividend} by each of the @var{divisors}, cumulatively, returning
539 the quotient. If there are no arguments, an error is signaled.
541 If none of the arguments are floats, then the result is an integer.
542 This means the result has to be rounded. On most machines, the result
543 is rounded towards zero after each division, but some machines may round
544 differently with negative arguments. This is because the Lisp function
545 @code{/} is implemented using the C division operator, which also
546 permits machine-dependent rounding. As a practical matter, all known
547 machines round in the standard fashion.
549 If any of the arguments are characters or markers, they are first
550 converted to integers.
552 @cindex @code{arith-error} in division
553 If you divide by 0, an @code{arith-error} error is signaled.
566 @result{} 0.3333333333333333
571 The result of @code{(/ -17 6)} could in principle be -3 on some
575 @defun % dividend divisor
577 This function returns the integer remainder after division of @var{dividend}
578 by @var{divisor}. The arguments must be integers or markers.
580 For negative arguments, the remainder is in principle machine-dependent
581 since the quotient is; but in practice, all known machines behave alike.
583 An @code{arith-error} results if @var{divisor} is 0.
596 For any two integers @var{dividend} and @var{divisor},
600 (+ (% @var{dividend} @var{divisor})
601 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
606 always equals @var{dividend}.
609 @defun mod dividend divisor
611 This function returns the value of @var{dividend} modulo @var{divisor};
612 in other words, the remainder after division of @var{dividend}
613 by @var{divisor}, but with the same sign as @var{divisor}.
614 The arguments must be numbers or markers.
616 Unlike @code{%}, @code{mod} returns a well-defined result for negative
617 arguments. It also permits floating point arguments; it rounds the
618 quotient downward (towards minus infinity) to an integer, and uses that
619 quotient to compute the remainder.
621 An @code{arith-error} results if @var{divisor} is 0.
646 For any two numbers @var{dividend} and @var{divisor},
650 (+ (mod @var{dividend} @var{divisor})
651 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
656 always equals @var{dividend}, subject to rounding error if either
657 argument is floating point. For @code{floor}, see @ref{Numeric
662 @node Rounding Operations
663 @section Rounding Operations
664 @cindex rounding without conversion
666 The functions @code{ffloor}, @code{fceiling}, @code{fround} and
667 @code{ftruncate} take a floating point argument and return a floating
668 point result whose value is a nearby integer. @code{ffloor} returns the
669 nearest integer below; @code{fceiling}, the nearest integer above;
670 @code{ftruncate}, the nearest integer in the direction towards zero;
671 @code{fround}, the nearest integer.
674 This function rounds @var{number} to the next lower integral value, and
675 returns that value as a floating point number.
678 @defun fceiling number
679 This function rounds @var{number} to the next higher integral value, and
680 returns that value as a floating point number.
683 @defun ftruncate number
684 This function rounds @var{number} towards zero to an integral value, and
685 returns that value as a floating point number.
689 This function rounds @var{number} to the nearest integral value,
690 and returns that value as a floating point number.
694 @node Bitwise Operations
695 @section Bitwise Operations on Integers
697 In a computer, an integer is represented as a binary number, a
698 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
699 operation acts on the individual bits of such a sequence. For example,
700 @dfn{shifting} moves the whole sequence left or right one or more places,
701 reproducing the same pattern ``moved over''.
703 The bitwise operations in SXEmacs Lisp apply only to integers.
705 @defun lsh integer1 count
706 @cindex logical shift
707 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
708 bits in @var{integer1} to the left @var{count} places, or to the right
709 if @var{count} is negative, bringing zeros into the vacated bits. If
710 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
711 (most-significant) bit, producing a positive result even if
712 @var{integer1} is negative. Contrast this with @code{ash}, below.
714 Here are two examples of @code{lsh}, shifting a pattern of bits one
715 place to the left. We show only the low-order eight bits of the binary
716 pattern; the rest are all zero.
722 ;; @r{Decimal 5 becomes decimal 10.}
723 00000101 @result{} 00001010
727 ;; @r{Decimal 7 becomes decimal 14.}
728 00000111 @result{} 00001110
733 As the examples illustrate, shifting the pattern of bits one place to
734 the left produces a number that is twice the value of the previous
737 Shifting a pattern of bits two places to the left produces results
738 like this (with 8-bit binary numbers):
744 ;; @r{Decimal 3 becomes decimal 12.}
745 00000011 @result{} 00001100
749 On the other hand, shifting one place to the right looks like this:
755 ;; @r{Decimal 6 becomes decimal 3.}
756 00000110 @result{} 00000011
762 ;; @r{Decimal 5 becomes decimal 2.}
763 00000101 @result{} 00000010
768 As the example illustrates, shifting one place to the right divides the
769 value of a positive integer by two, rounding downward.
771 The function @code{lsh}, like all SXEmacs Lisp arithmetic functions, does
772 not check for overflow, so shifting left can discard significant bits
773 and change the sign of the number. For example, left shifting
774 134,217,727 produces @minus{}2 on a 28-bit machine:
777 (lsh 134217727 1) ; @r{left shift}
781 In binary, in the 28-bit implementation, the argument looks like this:
785 ;; @r{Decimal 134,217,727}
786 0111 1111 1111 1111 1111 1111 1111
791 which becomes the following when left shifted:
795 ;; @r{Decimal @minus{}2}
796 1111 1111 1111 1111 1111 1111 1110
801 @defun ash integer1 count
802 @cindex arithmetic shift
803 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
804 to the left @var{count} places, or to the right if @var{count}
807 @code{ash} gives the same results as @code{lsh} except when
808 @var{integer1} and @var{count} are both negative. In that case,
809 @code{ash} puts ones in the empty bit positions on the left, while
810 @code{lsh} puts zeros in those bit positions.
812 Thus, with @code{ash}, shifting the pattern of bits one place to the right
817 (ash -6 -1) @result{} -3
818 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
819 1111 1111 1111 1111 1111 1111 1010
821 1111 1111 1111 1111 1111 1111 1101
825 In contrast, shifting the pattern of bits one place to the right with
826 @code{lsh} looks like this:
830 (lsh -6 -1) @result{} 134217725
831 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
832 1111 1111 1111 1111 1111 1111 1010
834 0111 1111 1111 1111 1111 1111 1101
838 Here are other examples:
840 @c !!! Check if lined up in smallbook format! XDVI shows problem
841 @c with smallbook but not with regular book! --rjc 16mar92
844 ; @r{ 28-bit binary values}
846 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
847 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100}
852 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
853 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100}
858 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
859 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001}
866 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
867 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110}
870 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
871 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110}
876 @defun logand &rest ints-or-markers
879 This function returns the ``logical and'' of the arguments: the
880 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
881 set in all the arguments. (``Set'' means that the value of the bit is 1
884 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
885 12 is 12: 1101 combined with 1100 produces 1100.
886 In both the binary numbers, the leftmost two bits are set (i.e., they
887 are 1's), so the leftmost two bits of the returned value are set.
888 However, for the rightmost two bits, each is zero in at least one of
889 the arguments, so the rightmost two bits of the returned value are 0's.
901 If @code{logand} is not passed any argument, it returns a value of
902 @minus{}1. This number is an identity element for @code{logand}
903 because its binary representation consists entirely of ones. If
904 @code{logand} is passed just one argument, it returns that argument.
908 ; @r{ 28-bit binary values}
910 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
911 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
912 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
916 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
917 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
918 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
919 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
924 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111}
929 @defun logior &rest ints-or-markers
930 @cindex logical inclusive or
932 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
933 is set in the result if, and only if, the @var{n}th bit is set in at least
934 one of the arguments. If there are no arguments, the result is zero,
935 which is an identity element for this operation. If @code{logior} is
936 passed just one argument, it returns that argument.
940 ; @r{ 28-bit binary values}
942 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
943 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
944 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
948 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
949 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
950 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
951 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111}
956 @defun logxor &rest ints-or-markers
957 @cindex bitwise exclusive or
958 @cindex logical exclusive or
959 This function returns the ``exclusive or'' of its arguments: the
960 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
961 set in an odd number of the arguments. If there are no arguments, the
962 result is 0, which is an identity element for this operation. If
963 @code{logxor} is passed just one argument, it returns that argument.
967 ; @r{ 28-bit binary values}
969 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
970 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
971 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001}
975 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
976 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
977 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
978 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
983 @defun lognot integer
986 This function returns the logical complement of its argument: the @var{n}th
987 bit is one in the result if, and only if, the @var{n}th bit is zero in
988 @var{integer}, and vice-versa.
993 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
995 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
1000 @node Math Functions
1001 @section Standard Mathematical Functions
1002 @cindex transcendental functions
1003 @cindex mathematical functions
1005 These mathematical functions are available if floating point is
1006 supported (which is the normal state of affairs). They allow integers
1007 as well as floating point numbers as arguments.
1012 These are the ordinary trigonometric functions, with argument measured
1017 The value of @code{(asin @var{number})} is a number between @minus{}pi/2
1018 and pi/2 (inclusive) whose sine is @var{number}; if, however, @var{number}
1019 is out of range (outside [-1, 1]), then the result is a NaN.
1023 The value of @code{(acos @var{number})} is a number between 0 and pi
1024 (inclusive) whose cosine is @var{number}; if, however, @var{number}
1025 is out of range (outside [-1, 1]), then the result is a NaN.
1028 @defun atan number &optional number2
1029 The value of @code{(atan @var{number})} is a number between @minus{}pi/2
1030 and pi/2 (exclusive) whose tangent is @var{number}.
1032 If optional argument @var{number2} is supplied, the function returns
1033 @code{atan2(@var{number},@var{number2})}.
1039 These are the ordinary hyperbolic trigonometric functions.
1043 @defunx acosh number
1044 @defunx atanh number
1045 These are the inverse hyperbolic trigonometric functions.
1049 This is the exponential function; it returns @i{e} to the power
1050 @var{number}. @i{e} is a fundamental mathematical constant also called the
1051 base of natural logarithms.
1054 @defun log number &optional base
1055 This function returns the logarithm of @var{number}, with base @var{base}.
1056 If you don't specify @var{base}, the base @code{e} is used. If @var{number}
1057 is negative, the result is a NaN.
1061 This function returns the logarithm of @var{number}, with base 10. If
1062 @var{number} is negative, the result is a NaN. @code{(log10 @var{x})}
1063 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1067 This function returns @var{x} raised to power @var{y}. If both
1068 arguments are integers and @var{y} is positive, the result is an
1069 integer; in this case, it is truncated to fit the range of possible
1074 This returns the square root of @var{number}. If @var{number} is negative,
1078 @defun cube-root number
1079 This returns the cube root of @var{number}.
1083 @node Random Numbers
1084 @section Random Numbers
1085 @cindex random numbers
1087 A deterministic computer program cannot generate true random numbers.
1088 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1089 pseudo-random numbers is generated in a deterministic fashion. The
1090 numbers are not truly random, but they have certain properties that
1091 mimic a random series. For example, all possible values occur equally
1092 often in a pseudo-random series.
1094 In SXEmacs, pseudo-random numbers are generated from a ``seed'' number.
1095 Starting from any given seed, the @code{random} function always
1096 generates the same sequence of numbers. SXEmacs always starts with the
1097 same seed value, so the sequence of values of @code{random} is actually
1098 the same in each SXEmacs run! For example, in one operating system, the
1099 first call to @code{(random)} after you start SXEmacs always returns
1100 -1457731, and the second one always returns -7692030. This
1101 repeatability is helpful for debugging.
1103 If you want truly unpredictable random numbers, execute @code{(random
1104 t)}. This chooses a new seed based on the current time of day and on
1105 XEmacs's process @sc{id} number.
1107 @defun random &optional limit
1108 This function returns a pseudo-random integer. Repeated calls return a
1109 series of pseudo-random integers.
1111 If @var{limit} is a positive integer, the value is chosen to be
1112 nonnegative and less than @var{limit}.
1114 If @var{limit} is @code{t}, it means to choose a new seed based on the
1115 current time of day and on SXEmacs's process @sc{id} number.
1116 @c "SXEmacs'" is incorrect usage!
1118 On some machines, any integer representable in Lisp may be the result
1119 of @code{random}. On other machines, the result can never be larger
1120 than a certain maximum or less than a certain (negative) minimum.