2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/numbers.info
6 @node Numbers, Strings and Characters, Lisp Data Types, Top
11 XEmacs supports two numeric data types: @dfn{integers} and
12 @dfn{floating point numbers}. Integers are whole numbers such as
13 @minus{}3, 0, #b0111, #xFEED, #o744. Their values are exact. The
14 number prefixes `#b', `#o', and `#x' are supported to represent numbers
15 in binary, octal, and hexadecimal notation (or radix). Floating point
16 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
17 2.71828. They can also be expressed in exponential notation: 1.5e2
18 equals 150; in this example, @samp{e2} stands for ten to the second
19 power, and is multiplied by 1.5. Floating point values are not exact;
20 they have a fixed, limited amount of precision.
23 * Integer Basics:: Representation and range of integers.
24 * Float Basics:: Representation and range of floating point.
25 * Predicates on Numbers:: Testing for numbers.
26 * Comparison of Numbers:: Equality and inequality predicates.
27 * Numeric Conversions:: Converting float to integer and vice versa.
28 * Arithmetic Operations:: How to add, subtract, multiply and divide.
29 * Rounding Operations:: Explicitly rounding floating point numbers.
30 * Bitwise Operations:: Logical and, or, not, shifting.
31 * Math Functions:: Trig, exponential and logarithmic functions.
32 * Random Numbers:: Obtaining random integers, predictable or not.
36 @section Integer Basics
38 The range of values for an integer depends on the machine. The
39 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
53 but some machines may provide a wider range. Many examples in this
54 chapter assume an integer has 28 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 268435457 ; @r{Also the integer 1, due to overflow.}
66 0 ; @r{The integer 0.}
67 -0 ; @r{The integer 0.}
70 To understand how various functions work on integers, especially the
71 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
72 view the numbers in their binary form.
74 In 28-bit binary, the decimal integer 5 looks like this:
77 0000 0000 0000 0000 0000 0000 0101
81 (We have inserted spaces between groups of 4 bits, and two spaces
82 between groups of 8 bits, to make the binary integer easier to read.)
84 The integer @minus{}1 looks like this:
87 1111 1111 1111 1111 1111 1111 1111
91 @cindex two's complement
92 @minus{}1 is represented as 28 ones. (This is called @dfn{two's
93 complement} notation.)
95 The negative integer, @minus{}5, is creating by subtracting 4 from
96 @minus{}1. In binary, the decimal integer 4 is 100. Consequently,
97 @minus{}5 looks like this:
100 1111 1111 1111 1111 1111 1111 1011
103 In this implementation, the largest 28-bit binary integer is the
104 decimal integer 134,217,727. In binary, it looks like this:
107 0111 1111 1111 1111 1111 1111 1111
110 Since the arithmetic functions do not check whether integers go
111 outside their range, when you add 1 to 134,217,727, the value is the
112 negative integer @minus{}134,217,728:
117 @result{} 1000 0000 0000 0000 0000 0000 0000
120 Many of the following functions accept markers for arguments as well
121 as integers. (@xref{Markers}.) More precisely, the actual arguments to
122 such functions may be either integers or markers, which is why we often
123 give these arguments the name @var{int-or-marker}. When the argument
124 value is a marker, its position value is used and its buffer is ignored.
127 In version 19, except where @emph{integer} is specified as an
128 argument, all of the functions for markers and integers also work for
129 floating point numbers.
133 @section Floating Point Basics
135 XEmacs supports floating point numbers. The precise range of floating
136 point numbers is machine-specific; it is the same as the range of the C
137 data type @code{double} on the machine in question.
139 The printed representation for floating point numbers requires either
140 a decimal point (with at least one digit following), an exponent, or
141 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
142 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
143 number whose value is 1500. They are all equivalent. You can also use
144 a minus sign to write negative floating point numbers, as in
147 @cindex IEEE floating point
148 @cindex positive infinity
149 @cindex negative infinity
152 Most modern computers support the IEEE floating point standard, which
153 provides for positive infinity and negative infinity as floating point
154 values. It also provides for a class of values called NaN or
155 ``not-a-number''; numerical functions return such values in cases where
156 there is no correct answer. For example, @code{(sqrt -1.0)} returns a
157 NaN. For practical purposes, there's no significant difference between
158 different NaN values in XEmacs Lisp, and there's no rule for precisely
159 which NaN value should be used in a particular case, so this manual
160 doesn't try to distinguish them. XEmacs Lisp has no read syntax for NaNs
161 or infinities; perhaps we should create a syntax in the future.
163 You can use @code{logb} to extract the binary exponent of a floating
164 point number (or estimate the logarithm of an integer):
167 This function returns the binary exponent of @var{number}. More
168 precisely, the value is the logarithm of @var{number} base 2, rounded
172 @node Predicates on Numbers
173 @section Type Predicates for Numbers
175 The functions in this section test whether the argument is a number or
176 whether it is a certain sort of number. The functions @code{integerp}
177 and @code{floatp} can take any type of Lisp object as argument (the
178 predicates would not be of much use otherwise); but the @code{zerop}
179 predicate requires a number as its argument. See also
180 @code{integer-or-marker-p}, @code{integer-char-or-marker-p},
181 @code{number-or-marker-p} and @code{number-char-or-marker-p}, in
182 @ref{Predicates on Markers}.
185 This predicate tests whether its argument is a floating point
186 number and returns @code{t} if so, @code{nil} otherwise.
188 @code{floatp} does not exist in Emacs versions 18 and earlier.
191 @defun integerp object
192 This predicate tests whether its argument is an integer, and returns
193 @code{t} if so, @code{nil} otherwise.
196 @defun numberp object
197 This predicate tests whether its argument is a number (either integer or
198 floating point), and returns @code{t} if so, @code{nil} otherwise.
201 @defun natnump object
202 @cindex natural numbers
203 The @code{natnump} predicate (whose name comes from the phrase
204 ``natural-number-p'') tests to see whether its argument is a nonnegative
205 integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
206 considered non-negative.
210 This predicate tests whether its argument is zero, and returns @code{t}
211 if so, @code{nil} otherwise. The argument must be a number.
213 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
216 @node Comparison of Numbers
217 @section Comparison of Numbers
218 @cindex number equality
220 To test numbers for numerical equality, you should normally use
221 @code{=}, not @code{eq}. There can be many distinct floating point
222 number objects with the same numeric value. If you use @code{eq} to
223 compare them, then you test whether two values are the same
224 @emph{object}. By contrast, @code{=} compares only the numeric values
227 At present, each integer value has a unique Lisp object in XEmacs Lisp.
228 Therefore, @code{eq} is equivalent to @code{=} where integers are
229 concerned. It is sometimes convenient to use @code{eq} for comparing an
230 unknown value with an integer, because @code{eq} does not report an
231 error if the unknown value is not a number---it accepts arguments of any
232 type. By contrast, @code{=} signals an error if the arguments are not
233 numbers or markers. However, it is a good idea to use @code{=} if you
234 can, even for comparing integers, just in case we change the
235 representation of integers in a future XEmacs version.
237 There is another wrinkle: because floating point arithmetic is not
238 exact, it is often a bad idea to check for equality of two floating
239 point values. Usually it is better to test for approximate equality.
240 Here's a function to do this:
243 (defconst fuzz-factor 1.0e-6)
244 (defun approx-equal (x y)
245 (or (and (= x 0) (= y 0))
247 (max (abs x) (abs y)))
251 @cindex CL note---integers vrs @code{eq}
253 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
254 @code{=} because Common Lisp implements multi-word integers, and two
255 distinct integer objects can have the same numeric value. XEmacs Lisp
256 can have just one integer object for any given value because it has a
257 limited range of integer values.
260 In addition to numbers, all of the following functions also accept
261 characters and markers as arguments, and treat them as their number
264 @defun = number &rest more-numbers
265 This function returns @code{t} if all of its arguments are numerically
266 equal, @code{nil} otherwise.
280 @defun /= number &rest more-numbers
281 This function returns @code{t} if no two arguments are numerically
282 equal, @code{nil} otherwise.
294 @defun < number &rest more-numbers
295 This function returns @code{t} if the sequence of its arguments is
296 monotonically increasing, @code{nil} otherwise.
308 @defun <= number &rest more-numbers
309 This function returns @code{t} if the sequence of its arguments is
310 monotonically nondecreasing, @code{nil} otherwise.
322 @defun > number &rest more-numbers
323 This function returns @code{t} if the sequence of its arguments is
324 monotonically decreasing, @code{nil} otherwise.
327 @defun >= number &rest more-numbers
328 This function returns @code{t} if the sequence of its arguments is
329 monotonically nonincreasing, @code{nil} otherwise.
332 @defun max number &rest more-numbers
333 This function returns the largest of its arguments.
345 @defun min number &rest more-numbers
346 This function returns the smallest of its arguments.
354 @node Numeric Conversions
355 @section Numeric Conversions
356 @cindex rounding in conversions
358 To convert an integer to floating point, use the function @code{float}.
361 This returns @var{number} converted to floating point.
362 If @var{number} is already a floating point number, @code{float} returns
366 There are four functions to convert floating point numbers to integers;
367 they differ in how they round. These functions accept integer arguments
368 also, and return such arguments unchanged.
370 @defun truncate number
371 This returns @var{number}, converted to an integer by rounding towards
375 @defun floor number &optional divisor
376 This returns @var{number}, converted to an integer by rounding downward
377 (towards negative infinity).
379 If @var{divisor} is specified, @var{number} is divided by @var{divisor}
380 before the floor is taken; this is the division operation that
381 corresponds to @code{mod}. An @code{arith-error} results if
385 @defun ceiling number
386 This returns @var{number}, converted to an integer by rounding upward
387 (towards positive infinity).
391 This returns @var{number}, converted to an integer by rounding towards the
392 nearest integer. Rounding a value equidistant between two integers
393 may choose the integer closer to zero, or it may prefer an even integer,
394 depending on your machine.
397 @node Arithmetic Operations
398 @section Arithmetic Operations
400 XEmacs Lisp provides the traditional four arithmetic operations:
401 addition, subtraction, multiplication, and division. Remainder and modulus
402 functions supplement the division functions. The functions to
403 add or subtract 1 are provided because they are traditional in Lisp and
406 All of these functions except @code{%} return a floating point value
407 if any argument is floating.
409 It is important to note that in XEmacs Lisp, arithmetic functions
410 do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
411 @minus{}134217728, depending on your hardware.
413 @defun 1+ number-or-marker
414 This function returns @var{number-or-marker} plus 1.
424 This function is not analogous to the C operator @code{++}---it does not
425 increment a variable. It just computes a sum. Thus, if we continue,
432 If you want to increment the variable, you must use @code{setq},
440 Now that the @code{cl} package is always available from lisp code, a
441 more convenient and natural way to increment a variable is
442 @w{@code{(incf foo)}}.
445 @defun 1- number-or-marker
446 This function returns @var{number-or-marker} minus 1.
450 This returns the absolute value of @var{number}.
453 @defun + &rest numbers-or-markers
454 This function adds its arguments together. When given no arguments,
467 @defun - &optional number-or-marker &rest other-numbers-or-markers
468 The @code{-} function serves two purposes: negation and subtraction.
469 When @code{-} has a single argument, the value is the negative of the
470 argument. When there are multiple arguments, @code{-} subtracts each of
471 the @var{other-numbers-or-markers} from @var{number-or-marker},
472 cumulatively. If there are no arguments, the result is 0.
484 @defun * &rest numbers-or-markers
485 This function multiplies its arguments together, and returns the
486 product. When given no arguments, @code{*} returns 1.
498 @defun / dividend divisor &rest divisors
499 This function divides @var{dividend} by @var{divisor} and returns the
500 quotient. If there are additional arguments @var{divisors}, then it
501 divides @var{dividend} by each divisor in turn. Each argument may be a
504 If all the arguments are integers, then the result is an integer too.
505 This means the result has to be rounded. On most machines, the result
506 is rounded towards zero after each division, but some machines may round
507 differently with negative arguments. This is because the Lisp function
508 @code{/} is implemented using the C division operator, which also
509 permits machine-dependent rounding. As a practical matter, all known
510 machines round in the standard fashion.
512 @cindex @code{arith-error} in division
513 If you divide by 0, an @code{arith-error} error is signaled.
529 The result of @code{(/ -17 6)} could in principle be -3 on some
533 @defun % dividend divisor
535 This function returns the integer remainder after division of @var{dividend}
536 by @var{divisor}. The arguments must be integers or markers.
538 For negative arguments, the remainder is in principle machine-dependent
539 since the quotient is; but in practice, all known machines behave alike.
541 An @code{arith-error} results if @var{divisor} is 0.
554 For any two integers @var{dividend} and @var{divisor},
558 (+ (% @var{dividend} @var{divisor})
559 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
564 always equals @var{dividend}.
567 @defun mod dividend divisor
569 This function returns the value of @var{dividend} modulo @var{divisor};
570 in other words, the remainder after division of @var{dividend}
571 by @var{divisor}, but with the same sign as @var{divisor}.
572 The arguments must be numbers or markers.
574 Unlike @code{%}, @code{mod} returns a well-defined result for negative
575 arguments. It also permits floating point arguments; it rounds the
576 quotient downward (towards minus infinity) to an integer, and uses that
577 quotient to compute the remainder.
579 An @code{arith-error} results if @var{divisor} is 0.
604 For any two numbers @var{dividend} and @var{divisor},
608 (+ (mod @var{dividend} @var{divisor})
609 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
614 always equals @var{dividend}, subject to rounding error if either
615 argument is floating point. For @code{floor}, see @ref{Numeric
619 @node Rounding Operations
620 @section Rounding Operations
621 @cindex rounding without conversion
623 The functions @code{ffloor}, @code{fceiling}, @code{fround} and
624 @code{ftruncate} take a floating point argument and return a floating
625 point result whose value is a nearby integer. @code{ffloor} returns the
626 nearest integer below; @code{fceiling}, the nearest integer above;
627 @code{ftruncate}, the nearest integer in the direction towards zero;
628 @code{fround}, the nearest integer.
631 This function rounds @var{float} to the next lower integral value, and
632 returns that value as a floating point number.
635 @defun fceiling float
636 This function rounds @var{float} to the next higher integral value, and
637 returns that value as a floating point number.
640 @defun ftruncate float
641 This function rounds @var{float} towards zero to an integral value, and
642 returns that value as a floating point number.
646 This function rounds @var{float} to the nearest integral value,
647 and returns that value as a floating point number.
650 @node Bitwise Operations
651 @section Bitwise Operations on Integers
653 In a computer, an integer is represented as a binary number, a
654 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
655 operation acts on the individual bits of such a sequence. For example,
656 @dfn{shifting} moves the whole sequence left or right one or more places,
657 reproducing the same pattern ``moved over''.
659 The bitwise operations in XEmacs Lisp apply only to integers.
661 @defun lsh integer1 count
662 @cindex logical shift
663 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
664 bits in @var{integer1} to the left @var{count} places, or to the right
665 if @var{count} is negative, bringing zeros into the vacated bits. If
666 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
667 (most-significant) bit, producing a positive result even if
668 @var{integer1} is negative. Contrast this with @code{ash}, below.
670 Here are two examples of @code{lsh}, shifting a pattern of bits one
671 place to the left. We show only the low-order eight bits of the binary
672 pattern; the rest are all zero.
678 ;; @r{Decimal 5 becomes decimal 10.}
679 00000101 @result{} 00001010
683 ;; @r{Decimal 7 becomes decimal 14.}
684 00000111 @result{} 00001110
689 As the examples illustrate, shifting the pattern of bits one place to
690 the left produces a number that is twice the value of the previous
693 Shifting a pattern of bits two places to the left produces results
694 like this (with 8-bit binary numbers):
700 ;; @r{Decimal 3 becomes decimal 12.}
701 00000011 @result{} 00001100
705 On the other hand, shifting one place to the right looks like this:
711 ;; @r{Decimal 6 becomes decimal 3.}
712 00000110 @result{} 00000011
718 ;; @r{Decimal 5 becomes decimal 2.}
719 00000101 @result{} 00000010
724 As the example illustrates, shifting one place to the right divides the
725 value of a positive integer by two, rounding downward.
727 The function @code{lsh}, like all XEmacs Lisp arithmetic functions, does
728 not check for overflow, so shifting left can discard significant bits
729 and change the sign of the number. For example, left shifting
730 134,217,727 produces @minus{}2 on a 28-bit machine:
733 (lsh 134217727 1) ; @r{left shift}
737 In binary, in the 28-bit implementation, the argument looks like this:
741 ;; @r{Decimal 134,217,727}
742 0111 1111 1111 1111 1111 1111 1111
747 which becomes the following when left shifted:
751 ;; @r{Decimal @minus{}2}
752 1111 1111 1111 1111 1111 1111 1110
757 @defun ash integer1 count
758 @cindex arithmetic shift
759 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
760 to the left @var{count} places, or to the right if @var{count}
763 @code{ash} gives the same results as @code{lsh} except when
764 @var{integer1} and @var{count} are both negative. In that case,
765 @code{ash} puts ones in the empty bit positions on the left, while
766 @code{lsh} puts zeros in those bit positions.
768 Thus, with @code{ash}, shifting the pattern of bits one place to the right
773 (ash -6 -1) @result{} -3
774 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
775 1111 1111 1111 1111 1111 1111 1010
777 1111 1111 1111 1111 1111 1111 1101
781 In contrast, shifting the pattern of bits one place to the right with
782 @code{lsh} looks like this:
786 (lsh -6 -1) @result{} 134217725
787 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
788 1111 1111 1111 1111 1111 1111 1010
790 0111 1111 1111 1111 1111 1111 1101
794 Here are other examples:
796 @c !!! Check if lined up in smallbook format! XDVI shows problem
797 @c with smallbook but not with regular book! --rjc 16mar92
800 ; @r{ 28-bit binary values}
802 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
803 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100}
808 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
809 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100}
814 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
815 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001}
822 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
823 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110}
826 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
827 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110}
832 @defun logand &rest ints-or-markers
835 This function returns the ``logical and'' of the arguments: the
836 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
837 set in all the arguments. (``Set'' means that the value of the bit is 1
840 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
841 12 is 12: 1101 combined with 1100 produces 1100.
842 In both the binary numbers, the leftmost two bits are set (i.e., they
843 are 1's), so the leftmost two bits of the returned value are set.
844 However, for the rightmost two bits, each is zero in at least one of
845 the arguments, so the rightmost two bits of the returned value are 0's.
857 If @code{logand} is not passed any argument, it returns a value of
858 @minus{}1. This number is an identity element for @code{logand}
859 because its binary representation consists entirely of ones. If
860 @code{logand} is passed just one argument, it returns that argument.
864 ; @r{ 28-bit binary values}
866 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
867 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
868 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
872 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
873 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
874 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
875 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
880 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111}
885 @defun logior &rest ints-or-markers
886 @cindex logical inclusive or
888 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
889 is set in the result if, and only if, the @var{n}th bit is set in at least
890 one of the arguments. If there are no arguments, the result is zero,
891 which is an identity element for this operation. If @code{logior} is
892 passed just one argument, it returns that argument.
896 ; @r{ 28-bit binary values}
898 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
899 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
900 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
904 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
905 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
906 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
907 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111}
912 @defun logxor &rest ints-or-markers
913 @cindex bitwise exclusive or
914 @cindex logical exclusive or
915 This function returns the ``exclusive or'' of its arguments: the
916 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
917 set in an odd number of the arguments. If there are no arguments, the
918 result is 0, which is an identity element for this operation. If
919 @code{logxor} is passed just one argument, it returns that argument.
923 ; @r{ 28-bit binary values}
925 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
926 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
927 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001}
931 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
932 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
933 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
934 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
939 @defun lognot integer
942 This function returns the logical complement of its argument: the @var{n}th
943 bit is one in the result if, and only if, the @var{n}th bit is zero in
944 @var{integer}, and vice-versa.
949 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
951 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
956 @section Standard Mathematical Functions
957 @cindex transcendental functions
958 @cindex mathematical functions
960 These mathematical functions are available if floating point is
961 supported (which is the normal state of affairs). They allow integers
962 as well as floating point numbers as arguments.
967 These are the ordinary trigonometric functions, with argument measured
972 The value of @code{(asin @var{arg})} is a number between @minus{}pi/2
973 and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
974 is out of range (outside [-1, 1]), then the result is a NaN.
978 The value of @code{(acos @var{arg})} is a number between 0 and pi
979 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
980 is out of range (outside [-1, 1]), then the result is a NaN.
984 The value of @code{(atan @var{arg})} is a number between @minus{}pi/2
985 and pi/2 (exclusive) whose tangent is @var{arg}.
991 These are the ordinary hyperbolic trigonometric functions.
997 These are the inverse hyperbolic trigonometric functions.
1001 This is the exponential function; it returns @i{e} to the power
1002 @var{arg}. @i{e} is a fundamental mathematical constant also called the
1003 base of natural logarithms.
1006 @defun log arg &optional base
1007 This function returns the logarithm of @var{arg}, with base @var{base}.
1008 If you don't specify @var{base}, the base @var{e} is used. If @var{arg}
1009 is negative, the result is a NaN.
1014 This function returns @code{(1- (exp @var{arg}))}, but it is more
1015 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1020 This function returns @code{(log (1+ @var{arg}))}, but it is more
1021 accurate than that when @var{arg} is so small that adding 1 to it would
1027 This function returns the logarithm of @var{arg}, with base 10. If
1028 @var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
1029 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1033 This function returns @var{x} raised to power @var{y}. If both
1034 arguments are integers and @var{y} is positive, the result is an
1035 integer; in this case, it is truncated to fit the range of possible
1040 This returns the square root of @var{arg}. If @var{arg} is negative,
1044 @defun cube-root arg
1045 This returns the cube root of @var{arg}.
1048 @node Random Numbers
1049 @section Random Numbers
1050 @cindex random numbers
1052 A deterministic computer program cannot generate true random numbers.
1053 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1054 pseudo-random numbers is generated in a deterministic fashion. The
1055 numbers are not truly random, but they have certain properties that
1056 mimic a random series. For example, all possible values occur equally
1057 often in a pseudo-random series.
1059 In XEmacs, pseudo-random numbers are generated from a ``seed'' number.
1060 Starting from any given seed, the @code{random} function always
1061 generates the same sequence of numbers. XEmacs always starts with the
1062 same seed value, so the sequence of values of @code{random} is actually
1063 the same in each XEmacs run! For example, in one operating system, the
1064 first call to @code{(random)} after you start XEmacs always returns
1065 -1457731, and the second one always returns -7692030. This
1066 repeatability is helpful for debugging.
1068 If you want truly unpredictable random numbers, execute @code{(random
1069 t)}. This chooses a new seed based on the current time of day and on
1070 XEmacs's process @sc{id} number.
1072 @defun random &optional limit
1073 This function returns a pseudo-random integer. Repeated calls return a
1074 series of pseudo-random integers.
1076 If @var{limit} is a positive integer, the value is chosen to be
1077 nonnegative and less than @var{limit}.
1079 If @var{limit} is @code{t}, it means to choose a new seed based on the
1080 current time of day and on XEmacs's process @sc{id} number.
1081 @c "XEmacs'" is incorrect usage!
1083 On some machines, any integer representable in Lisp may be the result
1084 of @code{random}. On other machines, the result can never be larger
1085 than a certain maximum or less than a certain (negative) minimum.