Add Commentary section, minor cleanup of file header.
[emacs.git] / lispref / numbers.texi
blobe2cfc937c4d1a18d2ddb3a4600cd3d22ef30f084
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
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 @cindex integers in specific radix
71 @cindex radix for reading an integer
72 @cindex base for reading an integer
73   In addition, the Lisp reader recognizes a syntax for integers in
74 bases other than 10: @samp{#B@var{integer}} reads @var{integer} in
75 binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal
76 (radix 8), @samp{#X@var{integer}} reads @var{integer} in hexadecimal
77 (radix 16), and @samp{#@var{radix}r@var{integer}} reads @var{integer}
78 in radix @var{radix} (where @var{radix} is between 2 and 36,
79 inclusively).  Case is not significant for the letter after @samp{#}
80 (@samp{B}, @samp{O}, etc.) that denotes the radix.
82   To understand how various functions work on integers, especially the
83 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
84 view the numbers in their binary form.
86   In 28-bit binary, the decimal integer 5 looks like this:
88 @example
89 0000  0000 0000  0000 0000  0000 0101
90 @end example
92 @noindent
93 (We have inserted spaces between groups of 4 bits, and two spaces
94 between groups of 8 bits, to make the binary integer easier to read.)
96   The integer @minus{}1 looks like this:
98 @example
99 1111  1111 1111  1111 1111  1111 1111
100 @end example
102 @noindent
103 @cindex two's complement
104 @minus{}1 is represented as 28 ones.  (This is called @dfn{two's
105 complement} notation.)
107   The negative integer, @minus{}5, is creating by subtracting 4 from
108 @minus{}1.  In binary, the decimal integer 4 is 100.  Consequently,
109 @minus{}5 looks like this:
111 @example
112 1111  1111 1111  1111 1111  1111 1011
113 @end example
115   In this implementation, the largest 28-bit binary integer value is
116 134,217,727 in decimal.  In binary, it looks like this:
118 @example
119 0111  1111 1111  1111 1111  1111 1111
120 @end example
122   Since the arithmetic functions do not check whether integers go
123 outside their range, when you add 1 to 134,217,727, the value is the
124 negative integer @minus{}134,217,728:
126 @example
127 (+ 1 134217727)
128      @result{} -134217728
129      @result{} 1000  0000 0000  0000 0000  0000 0000
130 @end example
132   Many of the functions described in this chapter accept markers for
133 arguments in place of numbers.  (@xref{Markers}.)  Since the actual
134 arguments to such functions may be either numbers or markers, we often
135 give these arguments the name @var{number-or-marker}.  When the argument
136 value is a marker, its position value is used and its buffer is ignored.
138 @defvar most-positive-fixnum
139 The value of this variable is the largest integer that Emacs Lisp
140 can handle.
141 @end defvar
143 @defvar most-negative-fixnum
144 The value of this variable is the smallest integer that Emacs Lisp can
145 handle.  It is negative.
146 @end defvar
148 @node Float Basics
149 @section Floating Point Basics
151   Floating point numbers are useful for representing numbers that are
152 not integral.  The precise range of floating point numbers is
153 machine-specific; it is the same as the range of the C data type
154 @code{double} on the machine you are using.
156   The read-syntax for floating point numbers requires either a decimal
157 point (with at least one digit following), an exponent, or both.  For
158 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
159 @samp{.15e4} are five ways of writing a floating point number whose
160 value is 1500.  They are all equivalent.  You can also use a minus sign
161 to write negative floating point numbers, as in @samp{-1.0}.
163 @cindex IEEE floating point
164 @cindex positive infinity
165 @cindex negative infinity
166 @cindex infinity
167 @cindex NaN
168    Most modern computers support the IEEE floating point standard, which
169 provides for positive infinity and negative infinity as floating point
170 values.  It also provides for a class of values called NaN or
171 ``not-a-number''; numerical functions return such values in cases where
172 there is no correct answer.  For example, @code{(sqrt -1.0)} returns a
173 NaN.  For practical purposes, there's no significant difference between
174 different NaN values in Emacs Lisp, and there's no rule for precisely
175 which NaN value should be used in a particular case, so Emacs Lisp
176 doesn't try to distinguish them.  Here are the read syntaxes for
177 these special floating point values:
179 @table @asis
180 @item positive infinity
181 @samp{1.0e+INF}
182 @item negative infinity
183 @samp{-1.0e+INF}
184 @item Not-a-number
185 @samp{0.0e+NaN}.
186 @end table
188   In addition, the value @code{-0.0} is distinguishable from ordinary
189 zero in IEEE floating point (although @code{equal} and @code{=} consider
190 them equal values).
192   You can use @code{logb} to extract the binary exponent of a floating
193 point number (or estimate the logarithm of an integer):
195 @defun logb number
196 This function returns the binary exponent of @var{number}.  More
197 precisely, the value is the logarithm of @var{number} base 2, rounded
198 down to an integer.
200 @example
201 (logb 10)
202      @result{} 3
203 (logb 10.0e20)
204      @result{} 69
205 @end example
206 @end defun
208 @node Predicates on Numbers
209 @section Type Predicates for Numbers
211   The functions in this section test whether the argument is a number or
212 whether it is a certain sort of number.  The functions @code{integerp}
213 and @code{floatp} can take any type of Lisp object as argument (the
214 predicates would not be of much use otherwise); but the @code{zerop}
215 predicate requires a number as its argument.  See also
216 @code{integer-or-marker-p} and @code{number-or-marker-p}, in
217 @ref{Predicates on Markers}.
219 @defun floatp object
220 This predicate tests whether its argument is a floating point
221 number and returns @code{t} if so, @code{nil} otherwise.
223 @code{floatp} does not exist in Emacs versions 18 and earlier.
224 @end defun
226 @defun integerp object
227 This predicate tests whether its argument is an integer, and returns
228 @code{t} if so, @code{nil} otherwise.
229 @end defun
231 @defun numberp object
232 This predicate tests whether its argument is a number (either integer or
233 floating point), and returns @code{t} if so, @code{nil} otherwise.
234 @end defun
236 @defun wholenump object
237 @cindex natural numbers
238 The @code{wholenump} predicate (whose name comes from the phrase
239 ``whole-number-p'') tests to see whether its argument is a nonnegative
240 integer, and returns @code{t} if so, @code{nil} otherwise.  0 is
241 considered non-negative.
243 @findex natnump
244 @code{natnump} is an obsolete synonym for @code{wholenump}.
245 @end defun
247 @defun zerop number
248 This predicate tests whether its argument is zero, and returns @code{t}
249 if so, @code{nil} otherwise.  The argument must be a number.
251 These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
252 @end defun
254 @node Comparison of Numbers
255 @section Comparison of Numbers
256 @cindex number equality
258   To test numbers for numerical equality, you should normally use
259 @code{=}, not @code{eq}.  There can be many distinct floating point
260 number objects with the same numeric value.  If you use @code{eq} to
261 compare them, then you test whether two values are the same
262 @emph{object}.  By contrast, @code{=} compares only the numeric values
263 of the objects.
265   At present, each integer value has a unique Lisp object in Emacs Lisp.
266 Therefore, @code{eq} is equivalent to @code{=} where integers are
267 concerned.  It is sometimes convenient to use @code{eq} for comparing an
268 unknown value with an integer, because @code{eq} does not report an
269 error if the unknown value is not a number---it accepts arguments of any
270 type.  By contrast, @code{=} signals an error if the arguments are not
271 numbers or markers.  However, it is a good idea to use @code{=} if you
272 can, even for comparing integers, just in case we change the
273 representation of integers in a future Emacs version.
275   Sometimes it is useful to compare numbers with @code{equal}; it treats
276 two numbers as equal if they have the same data type (both integers, or
277 both floating point) and the same value.  By contrast, @code{=} can
278 treat an integer and a floating point number as equal.
280   There is another wrinkle: because floating point arithmetic is not
281 exact, it is often a bad idea to check for equality of two floating
282 point values.  Usually it is better to test for approximate equality.
283 Here's a function to do this:
285 @example
286 (defvar fuzz-factor 1.0e-6)
287 (defun approx-equal (x y)
288   (or (and (= x 0) (= y 0))
289       (< (/ (abs (- x y))
290             (max (abs x) (abs y)))
291          fuzz-factor)))
292 @end example
294 @cindex CL note---integers vrs @code{eq}
295 @quotation
296 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
297 @code{=} because Common Lisp implements multi-word integers, and two
298 distinct integer objects can have the same numeric value.  Emacs Lisp
299 can have just one integer object for any given value because it has a
300 limited range of integer values.
301 @end quotation
303 @defun = number-or-marker1 number-or-marker2
304 This function tests whether its arguments are numerically equal, and
305 returns @code{t} if so, @code{nil} otherwise.
306 @end defun
308 @defun /= number-or-marker1 number-or-marker2
309 This function tests whether its arguments are numerically equal, and
310 returns @code{t} if they are not, and @code{nil} if they are.
311 @end defun
313 @defun <  number-or-marker1 number-or-marker2
314 This function tests whether its first argument is strictly less than
315 its second argument.  It returns @code{t} if so, @code{nil} otherwise.
316 @end defun
318 @defun <=  number-or-marker1 number-or-marker2
319 This function tests whether its first argument is less than or equal
320 to its second argument.  It returns @code{t} if so, @code{nil}
321 otherwise.
322 @end defun
324 @defun >  number-or-marker1 number-or-marker2
325 This function tests whether its first argument is strictly greater
326 than its second argument.  It returns @code{t} if so, @code{nil}
327 otherwise.
328 @end defun
330 @defun >=  number-or-marker1 number-or-marker2
331 This function tests whether its first argument is greater than or
332 equal to its second argument.  It returns @code{t} if so, @code{nil}
333 otherwise.
334 @end defun
336 @defun max number-or-marker &rest numbers-or-markers
337 This function returns the largest of its arguments.
338 If any of the argument is floating-point, the value is returned
339 as floating point, even if it was given as an integer.
341 @example
342 (max 20)
343      @result{} 20
344 (max 1 2.5)
345      @result{} 2.5
346 (max 1 3 2.5)
347      @result{} 3.0
348 @end example
349 @end defun
351 @defun min number-or-marker &rest numbers-or-markers
352 This function returns the smallest of its arguments.
353 If any of the argument is floating-point, the value is returned
354 as floating point, even if it was given as an integer.
356 @example
357 (min -4 1)
358      @result{} -4
359 @end example
360 @end defun
362 @defun abs number
363 This function returns the absolute value of @var{number}.
364 @end defun
366 @node Numeric Conversions
367 @section Numeric Conversions
368 @cindex rounding in conversions
370 To convert an integer to floating point, use the function @code{float}.
372 @defun float number
373 This returns @var{number} converted to floating point.
374 If @var{number} is already a floating point number, @code{float} returns
375 it unchanged.
376 @end defun
378 There are four functions to convert floating point numbers to integers;
379 they differ in how they round.  These functions accept integer arguments
380 also, and return such arguments unchanged.
382 @defun truncate number
383 This returns @var{number}, converted to an integer by rounding towards
384 zero.
386 @example
387 (truncate 1.2)
388      @result{} 1
389 (truncate 1.7)
390      @result{} 1
391 (truncate -1.2)
392      @result{} -1
393 (truncate -1.7)
394      @result{} -1
395 @end example
396 @end defun
398 @defun floor number &optional divisor
399 This returns @var{number}, converted to an integer by rounding downward
400 (towards negative infinity).
402 If @var{divisor} is specified, @code{floor} divides @var{number} by
403 @var{divisor} and then converts to an integer; this uses the kind of
404 division operation that corresponds to @code{mod}, rounding downward.
405 An @code{arith-error} results if @var{divisor} is 0.
407 @example
408 (floor 1.2)
409      @result{} 1
410 (floor 1.7)
411      @result{} 1
412 (floor -1.2)
413      @result{} -2
414 (floor -1.7)
415      @result{} -2
416 (floor 5.99 3)
417      @result{} 1
418 @end example
419 @end defun
421 @defun ceiling number
422 This returns @var{number}, converted to an integer by rounding upward
423 (towards positive infinity).
425 @example
426 (ceiling 1.2)
427      @result{} 2
428 (ceiling 1.7)
429      @result{} 2
430 (ceiling -1.2)
431      @result{} -1
432 (ceiling -1.7)
433      @result{} -1
434 @end example
435 @end defun
437 @defun round number
438 This returns @var{number}, converted to an integer by rounding towards the
439 nearest integer.  Rounding a value equidistant between two integers
440 may choose the integer closer to zero, or it may prefer an even integer,
441 depending on your machine.
443 @example
444 (round 1.2)
445      @result{} 1
446 (round 1.7)
447      @result{} 2
448 (round -1.2)
449      @result{} -1
450 (round -1.7)
451      @result{} -2
452 @end example
453 @end defun
455 @node Arithmetic Operations
456 @section Arithmetic Operations
458   Emacs Lisp provides the traditional four arithmetic operations:
459 addition, subtraction, multiplication, and division.  Remainder and modulus
460 functions supplement the division functions.  The functions to
461 add or subtract 1 are provided because they are traditional in Lisp and
462 commonly used.
464   All of these functions except @code{%} return a floating point value
465 if any argument is floating.
467   It is important to note that in Emacs Lisp, arithmetic functions
468 do not check for overflow.  Thus @code{(1+ 134217727)} may evaluate to
469 @minus{}134217728, depending on your hardware.
471 @defun 1+ number-or-marker
472 This function returns @var{number-or-marker} plus 1.
473 For example,
475 @example
476 (setq foo 4)
477      @result{} 4
478 (1+ foo)
479      @result{} 5
480 @end example
482 This function is not analogous to the C operator @code{++}---it does not
483 increment a variable.  It just computes a sum.  Thus, if we continue,
485 @example
487      @result{} 4
488 @end example
490 If you want to increment the variable, you must use @code{setq},
491 like this:
493 @example
494 (setq foo (1+ foo))
495      @result{} 5
496 @end example
497 @end defun
499 @defun 1- number-or-marker
500 This function returns @var{number-or-marker} minus 1.
501 @end defun
503 @defun + &rest numbers-or-markers
504 This function adds its arguments together.  When given no arguments,
505 @code{+} returns 0.
507 @example
509      @result{} 0
510 (+ 1)
511      @result{} 1
512 (+ 1 2 3 4)
513      @result{} 10
514 @end example
515 @end defun
517 @defun - &optional number-or-marker &rest more-numbers-or-markers
518 The @code{-} function serves two purposes: negation and subtraction.
519 When @code{-} has a single argument, the value is the negative of the
520 argument.  When there are multiple arguments, @code{-} subtracts each of
521 the @var{more-numbers-or-markers} from @var{number-or-marker},
522 cumulatively.  If there are no arguments, the result is 0.
524 @example
525 (- 10 1 2 3 4)
526      @result{} 0
527 (- 10)
528      @result{} -10
530      @result{} 0
531 @end example
532 @end defun
534 @defun * &rest numbers-or-markers
535 This function multiplies its arguments together, and returns the
536 product.  When given no arguments, @code{*} returns 1.
538 @example
540      @result{} 1
541 (* 1)
542      @result{} 1
543 (* 1 2 3 4)
544      @result{} 24
545 @end example
546 @end defun
548 @defun / dividend divisor &rest divisors
549 This function divides @var{dividend} by @var{divisor} and returns the
550 quotient.  If there are additional arguments @var{divisors}, then it
551 divides @var{dividend} by each divisor in turn.  Each argument may be a
552 number or a marker.
554 If all the arguments are integers, then the result is an integer too.
555 This means the result has to be rounded.  On most machines, the result
556 is rounded towards zero after each division, but some machines may round
557 differently with negative arguments.  This is because the Lisp function
558 @code{/} is implemented using the C division operator, which also
559 permits machine-dependent rounding.  As a practical matter, all known
560 machines round in the standard fashion.
562 @cindex @code{arith-error} in division
563 If you divide an integer by 0, an @code{arith-error} error is signaled.
564 (@xref{Errors}.)  Floating point division by zero returns either
565 infinity or a NaN if your machine supports IEEE floating point;
566 otherwise, it signals an @code{arith-error} error.
568 @example
569 @group
570 (/ 6 2)
571      @result{} 3
572 @end group
573 (/ 5 2)
574      @result{} 2
575 (/ 5.0 2)
576      @result{} 2.5
577 (/ 5 2.0)
578      @result{} 2.5
579 (/ 5.0 2.0)
580      @result{} 2.5
581 (/ 25 3 2)
582      @result{} 4
583 (/ -17 6)
584      @result{} -2
585 @end example
587 The result of @code{(/ -17 6)} could in principle be -3 on some
588 machines.
589 @end defun
591 @defun % dividend divisor
592 @cindex remainder
593 This function returns the integer remainder after division of @var{dividend}
594 by @var{divisor}.  The arguments must be integers or markers.
596 For negative arguments, the remainder is in principle machine-dependent
597 since the quotient is; but in practice, all known machines behave alike.
599 An @code{arith-error} results if @var{divisor} is 0.
601 @example
602 (% 9 4)
603      @result{} 1
604 (% -9 4)
605      @result{} -1
606 (% 9 -4)
607      @result{} 1
608 (% -9 -4)
609      @result{} -1
610 @end example
612 For any two integers @var{dividend} and @var{divisor},
614 @example
615 @group
616 (+ (% @var{dividend} @var{divisor})
617    (* (/ @var{dividend} @var{divisor}) @var{divisor}))
618 @end group
619 @end example
621 @noindent
622 always equals @var{dividend}.
623 @end defun
625 @defun mod dividend divisor
626 @cindex modulus
627 This function returns the value of @var{dividend} modulo @var{divisor};
628 in other words, the remainder after division of @var{dividend}
629 by @var{divisor}, but with the same sign as @var{divisor}.
630 The arguments must be numbers or markers.
632 Unlike @code{%}, @code{mod} returns a well-defined result for negative
633 arguments.  It also permits floating point arguments; it rounds the
634 quotient downward (towards minus infinity) to an integer, and uses that
635 quotient to compute the remainder.
637 An @code{arith-error} results if @var{divisor} is 0.
639 @example
640 @group
641 (mod 9 4)
642      @result{} 1
643 @end group
644 @group
645 (mod -9 4)
646      @result{} 3
647 @end group
648 @group
649 (mod 9 -4)
650      @result{} -3
651 @end group
652 @group
653 (mod -9 -4)
654      @result{} -1
655 @end group
656 @group
657 (mod 5.5 2.5)
658      @result{} .5
659 @end group
660 @end example
662 For any two numbers @var{dividend} and @var{divisor},
664 @example
665 @group
666 (+ (mod @var{dividend} @var{divisor})
667    (* (floor @var{dividend} @var{divisor}) @var{divisor}))
668 @end group
669 @end example
671 @noindent
672 always equals @var{dividend}, subject to rounding error if either
673 argument is floating point.  For @code{floor}, see @ref{Numeric
674 Conversions}.
675 @end defun
677 @node Rounding Operations
678 @section Rounding Operations
679 @cindex rounding without conversion
681 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
682 @code{ftruncate} take a floating point argument and return a floating
683 point result whose value is a nearby integer.  @code{ffloor} returns the
684 nearest integer below; @code{fceiling}, the nearest integer above;
685 @code{ftruncate}, the nearest integer in the direction towards zero;
686 @code{fround}, the nearest integer.
688 @defun ffloor float
689 This function rounds @var{float} to the next lower integral value, and
690 returns that value as a floating point number.
691 @end defun
693 @defun fceiling float
694 This function rounds @var{float} to the next higher integral value, and
695 returns that value as a floating point number.
696 @end defun
698 @defun ftruncate float
699 This function rounds @var{float} towards zero to an integral value, and
700 returns that value as a floating point number.
701 @end defun
703 @defun fround float
704 This function rounds @var{float} to the nearest integral value,
705 and returns that value as a floating point number.
706 @end defun
708 @node Bitwise Operations
709 @section Bitwise Operations on Integers
711   In a computer, an integer is represented as a binary number, a
712 sequence of @dfn{bits} (digits which are either zero or one).  A bitwise
713 operation acts on the individual bits of such a sequence.  For example,
714 @dfn{shifting} moves the whole sequence left or right one or more places,
715 reproducing the same pattern ``moved over''.
717   The bitwise operations in Emacs Lisp apply only to integers.
719 @defun lsh integer1 count
720 @cindex logical shift
721 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
722 bits in @var{integer1} to the left @var{count} places, or to the right
723 if @var{count} is negative, bringing zeros into the vacated bits.  If
724 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
725 (most-significant) bit, producing a positive result even if
726 @var{integer1} is negative.  Contrast this with @code{ash}, below.
728 Here are two examples of @code{lsh}, shifting a pattern of bits one
729 place to the left.  We show only the low-order eight bits of the binary
730 pattern; the rest are all zero.
732 @example
733 @group
734 (lsh 5 1)
735      @result{} 10
736 ;; @r{Decimal 5 becomes decimal 10.}
737 00000101 @result{} 00001010
739 (lsh 7 1)
740      @result{} 14
741 ;; @r{Decimal 7 becomes decimal 14.}
742 00000111 @result{} 00001110
743 @end group
744 @end example
746 @noindent
747 As the examples illustrate, shifting the pattern of bits one place to
748 the left produces a number that is twice the value of the previous
749 number.
751 Shifting a pattern of bits two places to the left produces results
752 like this (with 8-bit binary numbers):
754 @example
755 @group
756 (lsh 3 2)
757      @result{} 12
758 ;; @r{Decimal 3 becomes decimal 12.}
759 00000011 @result{} 00001100
760 @end group
761 @end example
763 On the other hand, shifting one place to the right looks like this:
765 @example
766 @group
767 (lsh 6 -1)
768      @result{} 3
769 ;; @r{Decimal 6 becomes decimal 3.}
770 00000110 @result{} 00000011
771 @end group
773 @group
774 (lsh 5 -1)
775      @result{} 2
776 ;; @r{Decimal 5 becomes decimal 2.}
777 00000101 @result{} 00000010
778 @end group
779 @end example
781 @noindent
782 As the example illustrates, shifting one place to the right divides the
783 value of a positive integer by two, rounding downward.
785 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
786 not check for overflow, so shifting left can discard significant bits
787 and change the sign of the number.  For example, left shifting
788 134,217,727 produces @minus{}2 on a 28-bit machine:
790 @example
791 (lsh 134217727 1)          ; @r{left shift}
792      @result{} -2
793 @end example
795 In binary, in the 28-bit implementation, the argument looks like this:
797 @example
798 @group
799 ;; @r{Decimal 134,217,727}
800 0111  1111 1111  1111 1111  1111 1111
801 @end group
802 @end example
804 @noindent
805 which becomes the following when left shifted:
807 @example
808 @group
809 ;; @r{Decimal @minus{}2}
810 1111  1111 1111  1111 1111  1111 1110
811 @end group
812 @end example
813 @end defun
815 @defun ash integer1 count
816 @cindex arithmetic shift
817 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
818 to the left @var{count} places, or to the right if @var{count}
819 is negative.
821 @code{ash} gives the same results as @code{lsh} except when
822 @var{integer1} and @var{count} are both negative.  In that case,
823 @code{ash} puts ones in the empty bit positions on the left, while
824 @code{lsh} puts zeros in those bit positions.
826 Thus, with @code{ash}, shifting the pattern of bits one place to the right
827 looks like this:
829 @example
830 @group
831 (ash -6 -1) @result{} -3
832 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
833 1111  1111 1111  1111 1111  1111 1010
834      @result{}
835 1111  1111 1111  1111 1111  1111 1101
836 @end group
837 @end example
839 In contrast, shifting the pattern of bits one place to the right with
840 @code{lsh} looks like this:
842 @example
843 @group
844 (lsh -6 -1) @result{} 134217725
845 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
846 1111  1111 1111  1111 1111  1111 1010
847      @result{}
848 0111  1111 1111  1111 1111  1111 1101
849 @end group
850 @end example
852 Here are other examples:
854 @c !!! Check if lined up in smallbook format!  XDVI shows problem
855 @c     with smallbook but not with regular book! --rjc 16mar92
856 @smallexample
857 @group
858                    ;  @r{             28-bit binary values}
860 (lsh 5 2)          ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
861      @result{} 20         ;      =  @r{0000  0000 0000  0000 0000  0001 0100}
862 @end group
863 @group
864 (ash 5 2)
865      @result{} 20
866 (lsh -5 2)         ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
867      @result{} -20        ;      =  @r{1111  1111 1111  1111 1111  1110 1100}
868 (ash -5 2)
869      @result{} -20
870 @end group
871 @group
872 (lsh 5 -2)         ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
873      @result{} 1          ;      =  @r{0000  0000 0000  0000 0000  0000 0001}
874 @end group
875 @group
876 (ash 5 -2)
877      @result{} 1
878 @end group
879 @group
880 (lsh -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
881      @result{} 4194302    ;      =  @r{0011  1111 1111  1111 1111  1111 1110}
882 @end group
883 @group
884 (ash -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
885      @result{} -2         ;      =  @r{1111  1111 1111  1111 1111  1111 1110}
886 @end group
887 @end smallexample
888 @end defun
890 @defun logand &rest ints-or-markers
891 @cindex logical and
892 @cindex bitwise and
893 This function returns the ``logical and'' of the arguments: the
894 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
895 set in all the arguments.  (``Set'' means that the value of the bit is 1
896 rather than 0.)
898 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
899 12 is 12: 1101 combined with 1100 produces 1100.
900 In both the binary numbers, the leftmost two bits are set (i.e., they
901 are 1's), so the leftmost two bits of the returned value are set.
902 However, for the rightmost two bits, each is zero in at least one of
903 the arguments, so the rightmost two bits of the returned value are 0's.
905 @noindent
906 Therefore,
908 @example
909 @group
910 (logand 13 12)
911      @result{} 12
912 @end group
913 @end example
915 If @code{logand} is not passed any argument, it returns a value of
916 @minus{}1.  This number is an identity element for @code{logand}
917 because its binary representation consists entirely of ones.  If
918 @code{logand} is passed just one argument, it returns that argument.
920 @smallexample
921 @group
922                    ; @r{               28-bit binary values}
924 (logand 14 13)     ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
925                    ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
926      @result{} 12         ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
927 @end group
929 @group
930 (logand 14 13 4)   ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
931                    ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
932                    ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
933      @result{} 4          ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
934 @end group
936 @group
937 (logand)
938      @result{} -1         ; -1  =  @r{1111  1111 1111  1111 1111  1111 1111}
939 @end group
940 @end smallexample
941 @end defun
943 @defun logior &rest ints-or-markers
944 @cindex logical inclusive or
945 @cindex bitwise or
946 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
947 is set in the result if, and only if, the @var{n}th bit is set in at least
948 one of the arguments.  If there are no arguments, the result is zero,
949 which is an identity element for this operation.  If @code{logior} is
950 passed just one argument, it returns that argument.
952 @smallexample
953 @group
954                    ; @r{              28-bit binary values}
956 (logior 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
957                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
958      @result{} 13         ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
959 @end group
961 @group
962 (logior 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
963                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
964                    ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
965      @result{} 15         ; 15  =  @r{0000  0000 0000  0000 0000  0000 1111}
966 @end group
967 @end smallexample
968 @end defun
970 @defun logxor &rest ints-or-markers
971 @cindex bitwise exclusive or
972 @cindex logical exclusive or
973 This function returns the ``exclusive or'' of its arguments: the
974 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
975 set in an odd number of the arguments.  If there are no arguments, the
976 result is 0, which is an identity element for this operation.  If
977 @code{logxor} is passed just one argument, it returns that argument.
979 @smallexample
980 @group
981                    ; @r{              28-bit binary values}
983 (logxor 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
984                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
985      @result{} 9          ;  9  =  @r{0000  0000 0000  0000 0000  0000 1001}
986 @end group
988 @group
989 (logxor 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
990                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
991                    ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
992      @result{} 14         ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
993 @end group
994 @end smallexample
995 @end defun
997 @defun lognot integer
998 @cindex logical not
999 @cindex bitwise not
1000 This function returns the logical complement of its argument: the @var{n}th
1001 bit is one in the result if, and only if, the @var{n}th bit is zero in
1002 @var{integer}, and vice-versa.
1004 @example
1005 (lognot 5)
1006      @result{} -6
1007 ;;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
1008 ;; @r{becomes}
1009 ;; -6  =  @r{1111  1111 1111  1111 1111  1111 1010}
1010 @end example
1011 @end defun
1013 @node Math Functions
1014 @section Standard Mathematical Functions
1015 @cindex transcendental functions
1016 @cindex mathematical functions
1018   These mathematical functions allow integers as well as floating point
1019 numbers as arguments.
1021 @defun sin arg
1022 @defunx cos arg
1023 @defunx tan arg
1024 These are the ordinary trigonometric functions, with argument measured
1025 in radians.
1026 @end defun
1028 @defun asin arg
1029 The value of @code{(asin @var{arg})} is a number between
1030 @ifnottex
1031 @minus{}pi/2
1032 @end ifnottex
1033 @tex
1034 @math{-\pi/2}
1035 @end tex
1037 @ifnottex
1038 pi/2
1039 @end ifnottex
1040 @tex
1041 @math{\pi/2}
1042 @end tex
1043 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
1044 is out of range (outside [-1, 1]), then the result is a NaN.
1045 @end defun
1047 @defun acos arg
1048 The value of @code{(acos @var{arg})} is a number between 0 and
1049 @ifnottex
1051 @end ifnottex
1052 @tex
1053 @math{\pi}
1054 @end tex
1055 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
1056 is out of range (outside [-1, 1]), then the result is a NaN.
1057 @end defun
1059 @defun atan y &optional x
1060 The value of @code{(atan @var{y})} is a number between
1061 @ifnottex
1062 @minus{}pi/2
1063 @end ifnottex
1064 @tex
1065 @math{-\pi/2}
1066 @end tex
1068 @ifnottex
1069 pi/2
1070 @end ifnottex
1071 @tex
1072 @math{\pi/2}
1073 @end tex
1074 (exclusive) whose tangent is @var{y}.  If the optional second
1075 argument @var{x} is given, the value of @code{(atan y x)} is the
1076 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1077 @code{X} axis.
1078 @end defun
1080 @defun exp arg
1081 This is the exponential function; it returns
1082 @tex
1083 @math{e}
1084 @end tex
1085 @ifnottex
1086 @i{e}
1087 @end ifnottex
1088 to the power @var{arg}.
1089 @tex
1090 @math{e}
1091 @end tex
1092 @ifnottex
1093 @i{e}
1094 @end ifnottex
1095 is a fundamental mathematical constant also called the base of natural
1096 logarithms.
1097 @end defun
1099 @defun log arg &optional base
1100 This function returns the logarithm of @var{arg}, with base @var{base}.
1101 If you don't specify @var{base}, the base
1102 @tex
1103 @math{e}
1104 @end tex
1105 @ifnottex
1106 @i{e}
1107 @end ifnottex
1108 is used.  If @var{arg}
1109 is negative, the result is a NaN.
1110 @end defun
1112 @ignore
1113 @defun expm1 arg
1114 This function returns @code{(1- (exp @var{arg}))}, but it is more
1115 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1116 is close to 1.
1117 @end defun
1119 @defun log1p arg
1120 This function returns @code{(log (1+ @var{arg}))}, but it is more
1121 accurate than that when @var{arg} is so small that adding 1 to it would
1122 lose accuracy.
1123 @end defun
1124 @end ignore
1126 @defun log10 arg
1127 This function returns the logarithm of @var{arg}, with base 10.  If
1128 @var{arg} is negative, the result is a NaN.  @code{(log10 @var{x})}
1129 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1130 @end defun
1132 @defun expt x y
1133 This function returns @var{x} raised to power @var{y}.  If both
1134 arguments are integers and @var{y} is positive, the result is an
1135 integer; in this case, it is truncated to fit the range of possible
1136 integer values.
1137 @end defun
1139 @defun sqrt arg
1140 This returns the square root of @var{arg}.  If @var{arg} is negative,
1141 the value is a NaN.
1142 @end defun
1144 @node Random Numbers
1145 @section Random Numbers
1146 @cindex random numbers
1148 A deterministic computer program cannot generate true random numbers.
1149 For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
1150 pseudo-random numbers is generated in a deterministic fashion.  The
1151 numbers are not truly random, but they have certain properties that
1152 mimic a random series.  For example, all possible values occur equally
1153 often in a pseudo-random series.
1155 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1156 Starting from any given seed, the @code{random} function always
1157 generates the same sequence of numbers.  Emacs always starts with the
1158 same seed value, so the sequence of values of @code{random} is actually
1159 the same in each Emacs run!  For example, in one operating system, the
1160 first call to @code{(random)} after you start Emacs always returns
1161 -1457731, and the second one always returns -7692030.  This
1162 repeatability is helpful for debugging.
1164 If you want random numbers that don't always come out the same, execute
1165 @code{(random t)}.  This chooses a new seed based on the current time of
1166 day and on Emacs's process @sc{id} number.
1168 @defun random &optional limit
1169 This function returns a pseudo-random integer.  Repeated calls return a
1170 series of pseudo-random integers.
1172 If @var{limit} is a positive integer, the value is chosen to be
1173 nonnegative and less than @var{limit}.
1175 If @var{limit} is @code{t}, it means to choose a new seed based on the
1176 current time of day and on Emacs's process @sc{id} number.
1177 @c "Emacs'" is incorrect usage!
1179 On some machines, any integer representable in Lisp may be the result
1180 of @code{random}.  On other machines, the result can never be larger
1181 than a certain maximum or less than a certain (negative) minimum.
1182 @end defun
1184 @ignore
1185    arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e
1186 @end ignore