*** empty log message ***
[emacs.git] / lispref / numbers.texi
blobeaa2250a3fd101f3c1807fda75284ab467c7ad6e
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/numbers
7 @node Numbers, Strings and Characters, Lisp Data Types, Top
8 @chapter Numbers
9 @cindex integers
10 @cindex numbers
12   GNU Emacs supports two numeric data types: @dfn{integers} and
13 @dfn{floating point numbers}.  Integers are whole numbers such as
14 @minus{}3, 0, 7, 13, and 511.  Their values are exact.  Floating point
15 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
16 2.71828.  They can also be expressed in exponential notation: 1.5e2
17 equals 150; in this example, @samp{e2} stands for ten to the second
18 power, and that is multiplied by 1.5.  Floating point values are not
19 exact; they have a fixed, limited amount of precision.
21 @menu
22 * Integer Basics::            Representation and range of integers.
23 * Float Basics::              Representation and range of floating point.
24 * Predicates on Numbers::     Testing for numbers.
25 * Comparison of Numbers::     Equality and inequality predicates.
26 * Numeric Conversions::       Converting float to integer and vice versa.
27 * Arithmetic Operations::     How to add, subtract, multiply and divide.
28 * Rounding Operations::       Explicitly rounding floating point numbers.
29 * Bitwise Operations::        Logical and, or, not, shifting.
30 * Math Functions::            Trig, exponential and logarithmic functions.
31 * Random Numbers::            Obtaining random integers, predictable or not.
32 @end menu
34 @node Integer Basics
35 @comment  node-name,  next,  previous,  up
36 @section Integer Basics
38   The range of values for an integer depends on the machine.  The
39 minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
40 @ifnottex
41 -2**27
42 @end ifnottex
43 @tex 
44 @math{-2^{27}}
45 @end tex
46 to 
47 @ifnottex
48 2**27 - 1),
49 @end ifnottex
50 @tex 
51 @math{2^{27}-1}),
52 @end tex
53 but some machines may provide a wider range.  Many examples in this
54 chapter assume an integer has 28 bits.
55 @cindex overflow
57   The Lisp reader reads an integer as a sequence of digits with optional
58 initial sign and optional final period.
60 @example
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.}
68 @end example
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:
76 @example
77 0000  0000 0000  0000 0000  0000 0101
78 @end example
80 @noindent
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:
86 @example
87 1111  1111 1111  1111 1111  1111 1111
88 @end example
90 @noindent
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:
99 @example
100 1111  1111 1111  1111 1111  1111 1011
101 @end example
103   In this implementation, the largest 28-bit binary integer value is
104 134,217,727 in decimal.  In binary, it looks like this:
106 @example
107 0111  1111 1111  1111 1111  1111 1111
108 @end example
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:
114 @example
115 (+ 1 134217727)
116      @result{} -134217728
117      @result{} 1000  0000 0000  0000 0000  0000 0000
118 @end example
120   Many of the functions described in this chapter accept markers for
121 arguments in place of numbers.  (@xref{Markers}.)  Since the actual
122 arguments to such functions may be either numbers or markers, we often
123 give these arguments the name @var{number-or-marker}.  When the argument
124 value is a marker, its position value is used and its buffer is ignored.
126 @node Float Basics
127 @section Floating Point Basics
129   Floating point numbers are useful for representing numbers that are
130 not integral.  The precise range of floating point numbers is
131 machine-specific; it is the same as the range of the C data type
132 @code{double} on the machine you are using.
134   The read-syntax for floating point numbers requires either a decimal
135 point (with at least one digit following), an exponent, or both.  For
136 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
137 @samp{.15e4} are five ways of writing a floating point number whose
138 value is 1500.  They are all equivalent.  You can also use a minus sign
139 to write negative floating point numbers, as in @samp{-1.0}.
141 @cindex IEEE floating point
142 @cindex positive infinity
143 @cindex negative infinity
144 @cindex infinity
145 @cindex NaN
146    Most modern computers support the IEEE floating point standard, which
147 provides for positive infinity and negative infinity as floating point
148 values.  It also provides for a class of values called NaN or
149 ``not-a-number''; numerical functions return such values in cases where
150 there is no correct answer.  For example, @code{(sqrt -1.0)} returns a
151 NaN.  For practical purposes, there's no significant difference between
152 different NaN values in Emacs Lisp, and there's no rule for precisely
153 which NaN value should be used in a particular case, so Emacs Lisp
154 doesn't try to distinguish them.  Here are the read syntaxes for
155 these special floating point values:
157 @table @asis
158 @item positive infinity
159 @samp{1.0e+INF}
160 @item negative infinity
161 @samp{-1.0e+INF}
162 @item Not-a-number
163 @samp{0.0e+NaN}.
164 @end table
166   In addition, the value @code{-0.0} is distinguishable from ordinary
167 zero in IEEE floating point (although @code{equal} and @code{=} consider
168 them equal values).
170   You can use @code{logb} to extract the binary exponent of a floating
171 point number (or estimate the logarithm of an integer):
173 @defun logb number
174 This function returns the binary exponent of @var{number}.  More
175 precisely, the value is the logarithm of @var{number} base 2, rounded
176 down to an integer.
178 @example
179 (logb 10)
180      @result{} 3
181 (logb 10.0e20)
182      @result{} 69
183 @end example
184 @end defun
186 @node Predicates on Numbers
187 @section Type Predicates for Numbers
189   The functions in this section test whether the argument is a number or
190 whether it is a certain sort of number.  The functions @code{integerp}
191 and @code{floatp} can take any type of Lisp object as argument (the
192 predicates would not be of much use otherwise); but the @code{zerop}
193 predicate requires a number as its argument.  See also
194 @code{integer-or-marker-p} and @code{number-or-marker-p}, in
195 @ref{Predicates on Markers}.
197 @defun floatp object
198 This predicate tests whether its argument is a floating point
199 number and returns @code{t} if so, @code{nil} otherwise.
201 @code{floatp} does not exist in Emacs versions 18 and earlier.
202 @end defun
204 @defun integerp object
205 This predicate tests whether its argument is an integer, and returns
206 @code{t} if so, @code{nil} otherwise.
207 @end defun
209 @defun numberp object
210 This predicate tests whether its argument is a number (either integer or
211 floating point), and returns @code{t} if so, @code{nil} otherwise.
212 @end defun
214 @defun wholenump object
215 @cindex natural numbers
216 The @code{wholenump} predicate (whose name comes from the phrase
217 ``whole-number-p'') tests to see whether its argument is a nonnegative
218 integer, and returns @code{t} if so, @code{nil} otherwise.  0 is
219 considered non-negative.
221 @findex natnump
222 @code{natnump} is an obsolete synonym for @code{wholenump}.
223 @end defun
225 @defun zerop number
226 This predicate tests whether its argument is zero, and returns @code{t}
227 if so, @code{nil} otherwise.  The argument must be a number.
229 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
230 @end defun
232 @node Comparison of Numbers
233 @section Comparison of Numbers
234 @cindex number equality
236   To test numbers for numerical equality, you should normally use
237 @code{=}, not @code{eq}.  There can be many distinct floating point
238 number objects with the same numeric value.  If you use @code{eq} to
239 compare them, then you test whether two values are the same
240 @emph{object}.  By contrast, @code{=} compares only the numeric values
241 of the objects.
243   At present, each integer value has a unique Lisp object in Emacs Lisp.
244 Therefore, @code{eq} is equivalent to @code{=} where integers are
245 concerned.  It is sometimes convenient to use @code{eq} for comparing an
246 unknown value with an integer, because @code{eq} does not report an
247 error if the unknown value is not a number---it accepts arguments of any
248 type.  By contrast, @code{=} signals an error if the arguments are not
249 numbers or markers.  However, it is a good idea to use @code{=} if you
250 can, even for comparing integers, just in case we change the
251 representation of integers in a future Emacs version.
253   Sometimes it is useful to compare numbers with @code{equal}; it treats
254 two numbers as equal if they have the same data type (both integers, or
255 both floating point) and the same value.  By contrast, @code{=} can
256 treat an integer and a floating point number as equal.
258   There is another wrinkle: because floating point arithmetic is not
259 exact, it is often a bad idea to check for equality of two floating
260 point values.  Usually it is better to test for approximate equality.
261 Here's a function to do this:
263 @example
264 (defvar fuzz-factor 1.0e-6)
265 (defun approx-equal (x y)
266   (or (and (= x 0) (= y 0))
267       (< (/ (abs (- x y))
268             (max (abs x) (abs y)))
269          fuzz-factor)))
270 @end example
272 @cindex CL note---integers vrs @code{eq}
273 @quotation
274 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
275 @code{=} because Common Lisp implements multi-word integers, and two
276 distinct integer objects can have the same numeric value.  Emacs Lisp
277 can have just one integer object for any given value because it has a
278 limited range of integer values.
279 @end quotation
281 @defun = number-or-marker1 number-or-marker2
282 This function tests whether its arguments are numerically equal, and
283 returns @code{t} if so, @code{nil} otherwise.
284 @end defun
286 @defun /= number-or-marker1 number-or-marker2
287 This function tests whether its arguments are numerically equal, and
288 returns @code{t} if they are not, and @code{nil} if they are.
289 @end defun
291 @defun <  number-or-marker1 number-or-marker2
292 This function tests whether its first argument is strictly less than
293 its second argument.  It returns @code{t} if so, @code{nil} otherwise.
294 @end defun
296 @defun <=  number-or-marker1 number-or-marker2
297 This function tests whether its first argument is less than or equal
298 to its second argument.  It returns @code{t} if so, @code{nil}
299 otherwise.
300 @end defun
302 @defun >  number-or-marker1 number-or-marker2
303 This function tests whether its first argument is strictly greater
304 than its second argument.  It returns @code{t} if so, @code{nil}
305 otherwise.
306 @end defun
308 @defun >=  number-or-marker1 number-or-marker2
309 This function tests whether its first argument is greater than or
310 equal to its second argument.  It returns @code{t} if so, @code{nil}
311 otherwise.
312 @end defun
314 @defun max number-or-marker &rest numbers-or-markers
315 This function returns the largest of its arguments.
316 If any of the argument is floating-point, the value is returned
317 as floating point, even if it was given as an integer.
319 @example
320 (max 20)
321      @result{} 20
322 (max 1 2.5)
323      @result{} 2.5
324 (max 1 3 2.5)
325      @result{} 3.0
326 @end example
327 @end defun
329 @defun min number-or-marker &rest numbers-or-markers
330 This function returns the smallest of its arguments.
331 If any of the argument is floating-point, the value is returned
332 as floating point, even if it was given as an integer.
334 @example
335 (min -4 1)
336      @result{} -4
337 @end example
338 @end defun
340 @defun abs number
341 This function returns the absolute value of @var{number}.
342 @end defun
344 @node Numeric Conversions
345 @section Numeric Conversions
346 @cindex rounding in conversions
348 To convert an integer to floating point, use the function @code{float}.
350 @defun float number
351 This returns @var{number} converted to floating point.
352 If @var{number} is already a floating point number, @code{float} returns
353 it unchanged.
354 @end defun
356 There are four functions to convert floating point numbers to integers;
357 they differ in how they round.  These functions accept integer arguments
358 also, and return such arguments unchanged.
360 @defun truncate number
361 This returns @var{number}, converted to an integer by rounding towards
362 zero.
363 @end defun
365 @defun floor number &optional divisor
366 This returns @var{number}, converted to an integer by rounding downward
367 (towards negative infinity).
369 If @var{divisor} is specified, @var{number} is divided by @var{divisor}
370 before the floor is taken; this uses the kind of division operation that
371 corresponds to @code{mod}, rounding downward.  An @code{arith-error}
372 results if @var{divisor} is 0.
373 @end defun
375 @defun ceiling number
376 This returns @var{number}, converted to an integer by rounding upward
377 (towards positive infinity).
378 @end defun
380 @defun round number
381 This returns @var{number}, converted to an integer by rounding towards the
382 nearest integer.  Rounding a value equidistant between two integers
383 may choose the integer closer to zero, or it may prefer an even integer,
384 depending on your machine.
385 @end defun
387 @node Arithmetic Operations
388 @section Arithmetic Operations
390   Emacs Lisp provides the traditional four arithmetic operations:
391 addition, subtraction, multiplication, and division.  Remainder and modulus
392 functions supplement the division functions.  The functions to
393 add or subtract 1 are provided because they are traditional in Lisp and
394 commonly used.
396   All of these functions except @code{%} return a floating point value
397 if any argument is floating.
399   It is important to note that in Emacs Lisp, arithmetic functions
400 do not check for overflow.  Thus @code{(1+ 134217727)} may evaluate to
401 @minus{}134217728, depending on your hardware.
403 @defun 1+ number-or-marker
404 This function returns @var{number-or-marker} plus 1.
405 For example,
407 @example
408 (setq foo 4)
409      @result{} 4
410 (1+ foo)
411      @result{} 5
412 @end example
414 This function is not analogous to the C operator @code{++}---it does not
415 increment a variable.  It just computes a sum.  Thus, if we continue,
417 @example
419      @result{} 4
420 @end example
422 If you want to increment the variable, you must use @code{setq},
423 like this:
425 @example
426 (setq foo (1+ foo))
427      @result{} 5
428 @end example
429 @end defun
431 @defun 1- number-or-marker
432 This function returns @var{number-or-marker} minus 1.
433 @end defun
435 @defun + &rest numbers-or-markers
436 This function adds its arguments together.  When given no arguments,
437 @code{+} returns 0.
439 @example
441      @result{} 0
442 (+ 1)
443      @result{} 1
444 (+ 1 2 3 4)
445      @result{} 10
446 @end example
447 @end defun
449 @defun - &optional number-or-marker &rest more-numbers-or-markers
450 The @code{-} function serves two purposes: negation and subtraction.
451 When @code{-} has a single argument, the value is the negative of the
452 argument.  When there are multiple arguments, @code{-} subtracts each of
453 the @var{more-numbers-or-markers} from @var{number-or-marker},
454 cumulatively.  If there are no arguments, the result is 0.
456 @example
457 (- 10 1 2 3 4)
458      @result{} 0
459 (- 10)
460      @result{} -10
462      @result{} 0
463 @end example
464 @end defun
466 @defun * &rest numbers-or-markers
467 This function multiplies its arguments together, and returns the
468 product.  When given no arguments, @code{*} returns 1.
470 @example
472      @result{} 1
473 (* 1)
474      @result{} 1
475 (* 1 2 3 4)
476      @result{} 24
477 @end example
478 @end defun
480 @defun / dividend divisor &rest divisors
481 This function divides @var{dividend} by @var{divisor} and returns the
482 quotient.  If there are additional arguments @var{divisors}, then it
483 divides @var{dividend} by each divisor in turn.  Each argument may be a
484 number or a marker.
486 If all the arguments are integers, then the result is an integer too.
487 This means the result has to be rounded.  On most machines, the result
488 is rounded towards zero after each division, but some machines may round
489 differently with negative arguments.  This is because the Lisp function
490 @code{/} is implemented using the C division operator, which also
491 permits machine-dependent rounding.  As a practical matter, all known
492 machines round in the standard fashion.
494 @cindex @code{arith-error} in division
495 If you divide an integer by 0, an @code{arith-error} error is signaled.
496 (@xref{Errors}.)  Floating point division by zero returns either
497 infinity or a NaN if your machine supports IEEE floating point;
498 otherwise, it signals an @code{arith-error} error.
500 @example
501 @group
502 (/ 6 2)
503      @result{} 3
504 @end group
505 (/ 5 2)
506      @result{} 2
507 (/ 5.0 2)
508      @result{} 2.5
509 (/ 5 2.0)
510      @result{} 2.5
511 (/ 5.0 2.0)
512      @result{} 2.5
513 (/ 25 3 2)
514      @result{} 4
515 (/ -17 6)
516      @result{} -2
517 @end example
519 The result of @code{(/ -17 6)} could in principle be -3 on some
520 machines.
521 @end defun
523 @defun % dividend divisor
524 @cindex remainder
525 This function returns the integer remainder after division of @var{dividend}
526 by @var{divisor}.  The arguments must be integers or markers.
528 For negative arguments, the remainder is in principle machine-dependent
529 since the quotient is; but in practice, all known machines behave alike.
531 An @code{arith-error} results if @var{divisor} is 0.
533 @example
534 (% 9 4)
535      @result{} 1
536 (% -9 4)
537      @result{} -1
538 (% 9 -4)
539      @result{} 1
540 (% -9 -4)
541      @result{} -1
542 @end example
544 For any two integers @var{dividend} and @var{divisor},
546 @example
547 @group
548 (+ (% @var{dividend} @var{divisor})
549    (* (/ @var{dividend} @var{divisor}) @var{divisor}))
550 @end group
551 @end example
553 @noindent
554 always equals @var{dividend}.
555 @end defun
557 @defun mod dividend divisor
558 @cindex modulus
559 This function returns the value of @var{dividend} modulo @var{divisor};
560 in other words, the remainder after division of @var{dividend}
561 by @var{divisor}, but with the same sign as @var{divisor}.
562 The arguments must be numbers or markers.
564 Unlike @code{%}, @code{mod} returns a well-defined result for negative
565 arguments.  It also permits floating point arguments; it rounds the
566 quotient downward (towards minus infinity) to an integer, and uses that
567 quotient to compute the remainder.
569 An @code{arith-error} results if @var{divisor} is 0.
571 @example
572 @group
573 (mod 9 4)
574      @result{} 1
575 @end group
576 @group
577 (mod -9 4)
578      @result{} 3
579 @end group
580 @group
581 (mod 9 -4)
582      @result{} -3
583 @end group
584 @group
585 (mod -9 -4)
586      @result{} -1
587 @end group
588 @group
589 (mod 5.5 2.5)
590      @result{} .5
591 @end group
592 @end example
594 For any two numbers @var{dividend} and @var{divisor},
596 @example
597 @group
598 (+ (mod @var{dividend} @var{divisor})
599    (* (floor @var{dividend} @var{divisor}) @var{divisor}))
600 @end group
601 @end example
603 @noindent
604 always equals @var{dividend}, subject to rounding error if either
605 argument is floating point.  For @code{floor}, see @ref{Numeric
606 Conversions}.
607 @end defun
609 @node Rounding Operations
610 @section Rounding Operations
611 @cindex rounding without conversion
613 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
614 @code{ftruncate} take a floating point argument and return a floating
615 point result whose value is a nearby integer.  @code{ffloor} returns the
616 nearest integer below; @code{fceiling}, the nearest integer above;
617 @code{ftruncate}, the nearest integer in the direction towards zero;
618 @code{fround}, the nearest integer.
620 @defun ffloor float
621 This function rounds @var{float} to the next lower integral value, and
622 returns that value as a floating point number.
623 @end defun
625 @defun fceiling float
626 This function rounds @var{float} to the next higher integral value, and
627 returns that value as a floating point number.
628 @end defun
630 @defun ftruncate float
631 This function rounds @var{float} towards zero to an integral value, and
632 returns that value as a floating point number.
633 @end defun
635 @defun fround float
636 This function rounds @var{float} to the nearest integral value,
637 and returns that value as a floating point number.
638 @end defun
640 @node Bitwise Operations
641 @section Bitwise Operations on Integers
643   In a computer, an integer is represented as a binary number, a
644 sequence of @dfn{bits} (digits which are either zero or one).  A bitwise
645 operation acts on the individual bits of such a sequence.  For example,
646 @dfn{shifting} moves the whole sequence left or right one or more places,
647 reproducing the same pattern ``moved over''.
649   The bitwise operations in Emacs Lisp apply only to integers.
651 @defun lsh integer1 count
652 @cindex logical shift
653 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
654 bits in @var{integer1} to the left @var{count} places, or to the right
655 if @var{count} is negative, bringing zeros into the vacated bits.  If
656 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
657 (most-significant) bit, producing a positive result even if
658 @var{integer1} is negative.  Contrast this with @code{ash}, below.
660 Here are two examples of @code{lsh}, shifting a pattern of bits one
661 place to the left.  We show only the low-order eight bits of the binary
662 pattern; the rest are all zero.
664 @example
665 @group
666 (lsh 5 1)
667      @result{} 10
668 ;; @r{Decimal 5 becomes decimal 10.}
669 00000101 @result{} 00001010
671 (lsh 7 1)
672      @result{} 14
673 ;; @r{Decimal 7 becomes decimal 14.}
674 00000111 @result{} 00001110
675 @end group
676 @end example
678 @noindent
679 As the examples illustrate, shifting the pattern of bits one place to
680 the left produces a number that is twice the value of the previous
681 number.
683 Shifting a pattern of bits two places to the left produces results
684 like this (with 8-bit binary numbers):
686 @example
687 @group
688 (lsh 3 2)
689      @result{} 12
690 ;; @r{Decimal 3 becomes decimal 12.}
691 00000011 @result{} 00001100       
692 @end group
693 @end example
695 On the other hand, shifting one place to the right looks like this:
697 @example
698 @group
699 (lsh 6 -1)
700      @result{} 3
701 ;; @r{Decimal 6 becomes decimal 3.}
702 00000110 @result{} 00000011       
703 @end group
705 @group
706 (lsh 5 -1)
707      @result{} 2
708 ;; @r{Decimal 5 becomes decimal 2.}
709 00000101 @result{} 00000010       
710 @end group
711 @end example
713 @noindent
714 As the example illustrates, shifting one place to the right divides the
715 value of a positive integer by two, rounding downward.
717 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
718 not check for overflow, so shifting left can discard significant bits
719 and change the sign of the number.  For example, left shifting
720 134,217,727 produces @minus{}2 on a 28-bit machine:
722 @example
723 (lsh 134217727 1)          ; @r{left shift}
724      @result{} -2
725 @end example
727 In binary, in the 28-bit implementation, the argument looks like this:
729 @example
730 @group
731 ;; @r{Decimal 134,217,727}
732 0111  1111 1111  1111 1111  1111 1111         
733 @end group
734 @end example
736 @noindent
737 which becomes the following when left shifted:
739 @example
740 @group
741 ;; @r{Decimal @minus{}2}
742 1111  1111 1111  1111 1111  1111 1110         
743 @end group
744 @end example
745 @end defun
747 @defun ash integer1 count
748 @cindex arithmetic shift
749 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
750 to the left @var{count} places, or to the right if @var{count}
751 is negative.
753 @code{ash} gives the same results as @code{lsh} except when
754 @var{integer1} and @var{count} are both negative.  In that case,
755 @code{ash} puts ones in the empty bit positions on the left, while
756 @code{lsh} puts zeros in those bit positions.
758 Thus, with @code{ash}, shifting the pattern of bits one place to the right
759 looks like this:
761 @example
762 @group
763 (ash -6 -1) @result{} -3            
764 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
765 1111  1111 1111  1111 1111  1111 1010
766      @result{} 
767 1111  1111 1111  1111 1111  1111 1101
768 @end group
769 @end example
771 In contrast, shifting the pattern of bits one place to the right with
772 @code{lsh} looks like this:
774 @example
775 @group
776 (lsh -6 -1) @result{} 134217725
777 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
778 1111  1111 1111  1111 1111  1111 1010
779      @result{} 
780 0111  1111 1111  1111 1111  1111 1101
781 @end group
782 @end example
784 Here are other examples:
786 @c !!! Check if lined up in smallbook format!  XDVI shows problem
787 @c     with smallbook but not with regular book! --rjc 16mar92
788 @smallexample
789 @group
790                    ;  @r{             28-bit binary values}
792 (lsh 5 2)          ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
793      @result{} 20         ;      =  @r{0000  0000 0000  0000 0000  0001 0100}
794 @end group
795 @group
796 (ash 5 2)
797      @result{} 20
798 (lsh -5 2)         ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
799      @result{} -20        ;      =  @r{1111  1111 1111  1111 1111  1110 1100}
800 (ash -5 2)
801      @result{} -20
802 @end group
803 @group
804 (lsh 5 -2)         ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
805      @result{} 1          ;      =  @r{0000  0000 0000  0000 0000  0000 0001}
806 @end group
807 @group
808 (ash 5 -2)
809      @result{} 1
810 @end group
811 @group
812 (lsh -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
813      @result{} 4194302    ;      =  @r{0011  1111 1111  1111 1111  1111 1110}
814 @end group
815 @group
816 (ash -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
817      @result{} -2         ;      =  @r{1111  1111 1111  1111 1111  1111 1110}
818 @end group
819 @end smallexample
820 @end defun
822 @defun logand &rest ints-or-markers
823 @cindex logical and
824 @cindex bitwise and
825 This function returns the ``logical and'' of the arguments: the
826 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
827 set in all the arguments.  (``Set'' means that the value of the bit is 1
828 rather than 0.)
830 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
831 12 is 12: 1101 combined with 1100 produces 1100.
832 In both the binary numbers, the leftmost two bits are set (i.e., they
833 are 1's), so the leftmost two bits of the returned value are set.
834 However, for the rightmost two bits, each is zero in at least one of
835 the arguments, so the rightmost two bits of the returned value are 0's.
837 @noindent
838 Therefore,
840 @example
841 @group
842 (logand 13 12)
843      @result{} 12
844 @end group
845 @end example
847 If @code{logand} is not passed any argument, it returns a value of
848 @minus{}1.  This number is an identity element for @code{logand}
849 because its binary representation consists entirely of ones.  If
850 @code{logand} is passed just one argument, it returns that argument.
852 @smallexample
853 @group
854                    ; @r{               28-bit binary values}
856 (logand 14 13)     ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
857                    ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
858      @result{} 12         ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
859 @end group
861 @group
862 (logand 14 13 4)   ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
863                    ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
864                    ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
865      @result{} 4          ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
866 @end group
868 @group
869 (logand)
870      @result{} -1         ; -1  =  @r{1111  1111 1111  1111 1111  1111 1111}
871 @end group
872 @end smallexample
873 @end defun
875 @defun logior &rest ints-or-markers
876 @cindex logical inclusive or
877 @cindex bitwise or
878 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
879 is set in the result if, and only if, the @var{n}th bit is set in at least
880 one of the arguments.  If there are no arguments, the result is zero,
881 which is an identity element for this operation.  If @code{logior} is
882 passed just one argument, it returns that argument.
884 @smallexample
885 @group
886                    ; @r{              28-bit binary values}
888 (logior 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
889                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
890      @result{} 13         ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
891 @end group
893 @group
894 (logior 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
895                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
896                    ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
897      @result{} 15         ; 15  =  @r{0000  0000 0000  0000 0000  0000 1111}
898 @end group
899 @end smallexample
900 @end defun
902 @defun logxor &rest ints-or-markers
903 @cindex bitwise exclusive or
904 @cindex logical exclusive or
905 This function returns the ``exclusive or'' of its arguments: the
906 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
907 set in an odd number of the arguments.  If there are no arguments, the
908 result is 0, which is an identity element for this operation.  If
909 @code{logxor} is passed just one argument, it returns that argument.
911 @smallexample
912 @group
913                    ; @r{              28-bit binary values}
915 (logxor 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
916                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
917      @result{} 9          ;  9  =  @r{0000  0000 0000  0000 0000  0000 1001}
918 @end group
920 @group
921 (logxor 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
922                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
923                    ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
924      @result{} 14         ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
925 @end group
926 @end smallexample
927 @end defun
929 @defun lognot integer
930 @cindex logical not
931 @cindex bitwise not
932 This function returns the logical complement of its argument: the @var{n}th
933 bit is one in the result if, and only if, the @var{n}th bit is zero in
934 @var{integer}, and vice-versa.
936 @example
937 (lognot 5)             
938      @result{} -6
939 ;;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
940 ;; @r{becomes}
941 ;; -6  =  @r{1111  1111 1111  1111 1111  1111 1010}
942 @end example
943 @end defun
945 @node Math Functions
946 @section Standard Mathematical Functions
947 @cindex transcendental functions
948 @cindex mathematical functions
950   These mathematical functions allow integers as well as floating point
951 numbers as arguments.
953 @defun sin arg
954 @defunx cos arg
955 @defunx tan arg
956 These are the ordinary trigonometric functions, with argument measured
957 in radians.
958 @end defun
960 @defun asin arg
961 The value of @code{(asin @var{arg})} is a number between
962 @ifnottex
963 @minus{}pi/2
964 @end ifnottex
965 @tex
966 @math{-\pi/2}
967 @end tex
969 @ifnottex
970 pi/2
971 @end ifnottex
972 @tex
973 @math{\pi/2}
974 @end tex
975 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
976 is out of range (outside [-1, 1]), then the result is a NaN.
977 @end defun
979 @defun acos arg
980 The value of @code{(acos @var{arg})} is a number between 0 and
981 @ifnottex
983 @end ifnottex
984 @tex
985 @math{\pi}
986 @end tex
987 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
988 is out of range (outside [-1, 1]), then the result is a NaN.
989 @end defun
991 @defun atan arg
992 The value of @code{(atan @var{arg})} is a number between
993 @ifnottex
994 @minus{}pi/2
995 @end ifnottex
996 @tex
997 @math{-\pi/2}
998 @end tex
1000 @ifnottex
1001 pi/2
1002 @end ifnottex
1003 @tex
1004 @math{\pi/2}
1005 @end tex
1006 (exclusive) whose tangent is @var{arg}.
1007 @end defun
1009 @defun exp arg
1010 This is the exponential function; it returns
1011 @tex
1012 @math{e}
1013 @end tex
1014 @ifnottex
1015 @i{e}
1016 @end ifnottex
1017 to the power @var{arg}.
1018 @tex
1019 @math{e}
1020 @end tex
1021 @ifnottex
1022 @i{e}
1023 @end ifnottex
1024 is a fundamental mathematical constant also called the base of natural
1025 logarithms.
1026 @end defun
1028 @defun log arg &optional base
1029 This function returns the logarithm of @var{arg}, with base @var{base}.
1030 If you don't specify @var{base}, the base
1031 @tex
1032 @math{e}
1033 @end tex
1034 @ifnottex
1035 @i{e}
1036 @end ifnottex
1037 is used.  If @var{arg}
1038 is negative, the result is a NaN.
1039 @end defun
1041 @ignore
1042 @defun expm1 arg
1043 This function returns @code{(1- (exp @var{arg}))}, but it is more
1044 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1045 is close to 1.
1046 @end defun
1048 @defun log1p arg
1049 This function returns @code{(log (1+ @var{arg}))}, but it is more
1050 accurate than that when @var{arg} is so small that adding 1 to it would
1051 lose accuracy.
1052 @end defun
1053 @end ignore
1055 @defun log10 arg
1056 This function returns the logarithm of @var{arg}, with base 10.  If
1057 @var{arg} is negative, the result is a NaN.  @code{(log10 @var{x})}
1058 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1059 @end defun
1061 @defun expt x y
1062 This function returns @var{x} raised to power @var{y}.  If both
1063 arguments are integers and @var{y} is positive, the result is an
1064 integer; in this case, it is truncated to fit the range of possible
1065 integer values.
1066 @end defun
1068 @defun sqrt arg
1069 This returns the square root of @var{arg}.  If @var{arg} is negative,
1070 the value is a NaN.
1071 @end defun
1073 @node Random Numbers
1074 @section Random Numbers
1075 @cindex random numbers
1077 A deterministic computer program cannot generate true random numbers.
1078 For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
1079 pseudo-random numbers is generated in a deterministic fashion.  The
1080 numbers are not truly random, but they have certain properties that
1081 mimic a random series.  For example, all possible values occur equally
1082 often in a pseudo-random series.
1084 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1085 Starting from any given seed, the @code{random} function always
1086 generates the same sequence of numbers.  Emacs always starts with the
1087 same seed value, so the sequence of values of @code{random} is actually
1088 the same in each Emacs run!  For example, in one operating system, the
1089 first call to @code{(random)} after you start Emacs always returns
1090 -1457731, and the second one always returns -7692030.  This
1091 repeatability is helpful for debugging.
1093 If you want random numbers that don't always come out the same, execute
1094 @code{(random t)}.  This chooses a new seed based on the current time of
1095 day and on Emacs's process @sc{id} number.
1097 @defun random &optional limit
1098 This function returns a pseudo-random integer.  Repeated calls return a
1099 series of pseudo-random integers.
1101 If @var{limit} is a positive integer, the value is chosen to be
1102 nonnegative and less than @var{limit}.
1104 If @var{limit} is @code{t}, it means to choose a new seed based on the
1105 current time of day and on Emacs's process @sc{id} number.
1106 @c "Emacs'" is incorrect usage!
1108 On some machines, any integer representable in Lisp may be the result
1109 of @code{random}.  On other machines, the result can never be larger
1110 than a certain maximum or less than a certain (negative) minimum.
1111 @end defun