*** empty log message ***
[emacs.git] / doc / lispref / numbers.texi
blobd86e698cc2145e81459e73a13a26c3767a75ea51
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, 2001,
4 @c   2002, 2003, 2004, 2005, 2006, 2007, 2008  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{}268435456 to 268435455 (29 bits; i.e.,
40 @ifnottex
41 -2**28
42 @end ifnottex
43 @tex
44 @math{-2^{28}}
45 @end tex
47 @ifnottex
48 2**28 - 1),
49 @end ifnottex
50 @tex
51 @math{2^{28}-1}),
52 @end tex
53 but some machines may provide a wider range.  Many examples in this
54 chapter assume an integer has 29 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  536870913       ; @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 @cindex hex numbers
74 @cindex octal numbers
75 @cindex reading numbers in hex, octal, and binary
76   The syntax for integers in bases other than 10 uses @samp{#}
77 followed by a letter that specifies the radix: @samp{b} for binary,
78 @samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
79 specify radix @var{radix}.  Case is not significant for the letter
80 that specifies the radix.  Thus, @samp{#b@var{integer}} reads
81 @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
82 @var{integer} in radix @var{radix}.  Allowed values of @var{radix} run
83 from 2 to 36.  For example:
85 @example
86 #b101100 @result{} 44
87 #o54 @result{} 44
88 #x2c @result{} 44
89 #24r1k @result{} 44
90 @end example
92   To understand how various functions work on integers, especially the
93 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
94 view the numbers in their binary form.
96   In 29-bit binary, the decimal integer 5 looks like this:
98 @example
99 0 0000  0000 0000  0000 0000  0000 0101
100 @end example
102 @noindent
103 (We have inserted spaces between groups of 4 bits, and two spaces
104 between groups of 8 bits, to make the binary integer easier to read.)
106   The integer @minus{}1 looks like this:
108 @example
109 1 1111  1111 1111  1111 1111  1111 1111
110 @end example
112 @noindent
113 @cindex two's complement
114 @minus{}1 is represented as 29 ones.  (This is called @dfn{two's
115 complement} notation.)
117   The negative integer, @minus{}5, is creating by subtracting 4 from
118 @minus{}1.  In binary, the decimal integer 4 is 100.  Consequently,
119 @minus{}5 looks like this:
121 @example
122 1 1111  1111 1111  1111 1111  1111 1011
123 @end example
125   In this implementation, the largest 29-bit binary integer value is
126 268,435,455 in decimal.  In binary, it looks like this:
128 @example
129 0 1111  1111 1111  1111 1111  1111 1111
130 @end example
132   Since the arithmetic functions do not check whether integers go
133 outside their range, when you add 1 to 268,435,455, the value is the
134 negative integer @minus{}268,435,456:
136 @example
137 (+ 1 268435455)
138      @result{} -268435456
139      @result{} 1 0000  0000 0000  0000 0000  0000 0000
140 @end example
142   Many of the functions described in this chapter accept markers for
143 arguments in place of numbers.  (@xref{Markers}.)  Since the actual
144 arguments to such functions may be either numbers or markers, we often
145 give these arguments the name @var{number-or-marker}.  When the argument
146 value is a marker, its position value is used and its buffer is ignored.
148 @defvar most-positive-fixnum
149 The value of this variable is the largest integer that Emacs Lisp
150 can handle.
151 @end defvar
153 @defvar most-negative-fixnum
154 The value of this variable is the smallest integer that Emacs Lisp can
155 handle.  It is negative.
156 @end defvar
158 @node Float Basics
159 @section Floating Point Basics
161   Floating point numbers are useful for representing numbers that are
162 not integral.  The precise range of floating point numbers is
163 machine-specific; it is the same as the range of the C data type
164 @code{double} on the machine you are using.
166   The read-syntax for floating point numbers requires either a decimal
167 point (with at least one digit following), an exponent, or both.  For
168 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
169 @samp{.15e4} are five ways of writing a floating point number whose
170 value is 1500.  They are all equivalent.  You can also use a minus sign
171 to write negative floating point numbers, as in @samp{-1.0}.
173 @cindex @acronym{IEEE} floating point
174 @cindex positive infinity
175 @cindex negative infinity
176 @cindex infinity
177 @cindex NaN
178   Most modern computers support the @acronym{IEEE} floating point standard,
179 which provides for positive infinity and negative infinity as floating point
180 values.  It also provides for a class of values called NaN or
181 ``not-a-number''; numerical functions return such values in cases where
182 there is no correct answer.  For example, @code{(/ 0.0 0.0)} returns a
183 NaN.  For practical purposes, there's no significant difference between
184 different NaN values in Emacs Lisp, and there's no rule for precisely
185 which NaN value should be used in a particular case, so Emacs Lisp
186 doesn't try to distinguish them (but it does report the sign, if you
187 print it).  Here are the read syntaxes for these special floating
188 point values:
190 @table @asis
191 @item positive infinity
192 @samp{1.0e+INF}
193 @item negative infinity
194 @samp{-1.0e+INF}
195 @item Not-a-number 
196 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
197 @end table
199   To test whether a floating point value is a NaN, compare it with
200 itself using @code{=}.  That returns @code{nil} for a NaN, and
201 @code{t} for any other floating point value.
203   The value @code{-0.0} is distinguishable from ordinary zero in
204 @acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
205 @code{=} consider them equal values.
207   You can use @code{logb} to extract the binary exponent of a floating
208 point number (or estimate the logarithm of an integer):
210 @defun logb number
211 This function returns the binary exponent of @var{number}.  More
212 precisely, the value is the logarithm of @var{number} base 2, rounded
213 down to an integer.
215 @example
216 (logb 10)
217      @result{} 3
218 (logb 10.0e20)
219      @result{} 69
220 @end example
221 @end defun
223 @node Predicates on Numbers
224 @section Type Predicates for Numbers
225 @cindex predicates for numbers
227   The functions in this section test for numbers, or for a specific
228 type of number.  The functions @code{integerp} and @code{floatp} can
229 take any type of Lisp object as argument (they would not be of much
230 use otherwise), but the @code{zerop} predicate requires a number as
231 its argument.  See also @code{integer-or-marker-p} and
232 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
234 @defun floatp object
235 This predicate tests whether its argument is a floating point
236 number and returns @code{t} if so, @code{nil} otherwise.
238 @code{floatp} does not exist in Emacs versions 18 and earlier.
239 @end defun
241 @defun integerp object
242 This predicate tests whether its argument is an integer, and returns
243 @code{t} if so, @code{nil} otherwise.
244 @end defun
246 @defun numberp object
247 This predicate tests whether its argument is a number (either integer or
248 floating point), and returns @code{t} if so, @code{nil} otherwise.
249 @end defun
251 @defun wholenump object
252 @cindex natural numbers
253 The @code{wholenump} predicate (whose name comes from the phrase
254 ``whole-number-p'') tests to see whether its argument is a nonnegative
255 integer, and returns @code{t} if so, @code{nil} otherwise.  0 is
256 considered non-negative.
258 @findex natnump
259 @code{natnump} is an obsolete synonym for @code{wholenump}.
260 @end defun
262 @defun zerop number
263 This predicate tests whether its argument is zero, and returns @code{t}
264 if so, @code{nil} otherwise.  The argument must be a number.
266 @code{(zerop x)} is equivalent to @code{(= x 0)}.
267 @end defun
269 @node Comparison of Numbers
270 @section Comparison of Numbers
271 @cindex number comparison
272 @cindex comparing numbers
274   To test numbers for numerical equality, you should normally use
275 @code{=}, not @code{eq}.  There can be many distinct floating point
276 number objects with the same numeric value.  If you use @code{eq} to
277 compare them, then you test whether two values are the same
278 @emph{object}.  By contrast, @code{=} compares only the numeric values
279 of the objects.
281   At present, each integer value has a unique Lisp object in Emacs Lisp.
282 Therefore, @code{eq} is equivalent to @code{=} where integers are
283 concerned.  It is sometimes convenient to use @code{eq} for comparing an
284 unknown value with an integer, because @code{eq} does not report an
285 error if the unknown value is not a number---it accepts arguments of any
286 type.  By contrast, @code{=} signals an error if the arguments are not
287 numbers or markers.  However, it is a good idea to use @code{=} if you
288 can, even for comparing integers, just in case we change the
289 representation of integers in a future Emacs version.
291   Sometimes it is useful to compare numbers with @code{equal}; it
292 treats two numbers as equal if they have the same data type (both
293 integers, or both floating point) and the same value.  By contrast,
294 @code{=} can treat an integer and a floating point number as equal.
295 @xref{Equality Predicates}.
297   There is another wrinkle: because floating point arithmetic is not
298 exact, it is often a bad idea to check for equality of two floating
299 point values.  Usually it is better to test for approximate equality.
300 Here's a function to do this:
302 @example
303 (defvar fuzz-factor 1.0e-6)
304 (defun approx-equal (x y)
305   (or (and (= x 0) (= y 0))
306       (< (/ (abs (- x y))
307             (max (abs x) (abs y)))
308          fuzz-factor)))
309 @end example
311 @cindex CL note---integers vrs @code{eq}
312 @quotation
313 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
314 @code{=} because Common Lisp implements multi-word integers, and two
315 distinct integer objects can have the same numeric value.  Emacs Lisp
316 can have just one integer object for any given value because it has a
317 limited range of integer values.
318 @end quotation
320 @defun = number-or-marker1 number-or-marker2
321 This function tests whether its arguments are numerically equal, and
322 returns @code{t} if so, @code{nil} otherwise.
323 @end defun
325 @defun eql value1 value2
326 This function acts like @code{eq} except when both arguments are
327 numbers.  It compares numbers by type and numeric value, so that
328 @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
329 @code{(eql 1 1)} both return @code{t}.
330 @end defun
332 @defun /= number-or-marker1 number-or-marker2
333 This function tests whether its arguments are numerically equal, and
334 returns @code{t} if they are not, and @code{nil} if they are.
335 @end defun
337 @defun <  number-or-marker1 number-or-marker2
338 This function tests whether its first argument is strictly less than
339 its second argument.  It returns @code{t} if so, @code{nil} otherwise.
340 @end defun
342 @defun <=  number-or-marker1 number-or-marker2
343 This function tests whether its first argument is less than or equal
344 to its second argument.  It returns @code{t} if so, @code{nil}
345 otherwise.
346 @end defun
348 @defun >  number-or-marker1 number-or-marker2
349 This function tests whether its first argument is strictly greater
350 than its second argument.  It returns @code{t} if so, @code{nil}
351 otherwise.
352 @end defun
354 @defun >=  number-or-marker1 number-or-marker2
355 This function tests whether its first argument is greater than or
356 equal to its second argument.  It returns @code{t} if so, @code{nil}
357 otherwise.
358 @end defun
360 @defun max number-or-marker &rest numbers-or-markers
361 This function returns the largest of its arguments.
362 If any of the arguments is floating-point, the value is returned
363 as floating point, even if it was given as an integer.
365 @example
366 (max 20)
367      @result{} 20
368 (max 1 2.5)
369      @result{} 2.5
370 (max 1 3 2.5)
371      @result{} 3.0
372 @end example
373 @end defun
375 @defun min number-or-marker &rest numbers-or-markers
376 This function returns the smallest of its arguments.
377 If any of the arguments is floating-point, the value is returned
378 as floating point, even if it was given as an integer.
380 @example
381 (min -4 1)
382      @result{} -4
383 @end example
384 @end defun
386 @defun abs number
387 This function returns the absolute value of @var{number}.
388 @end defun
390 @node Numeric Conversions
391 @section Numeric Conversions
392 @cindex rounding in conversions
393 @cindex number conversions
394 @cindex converting numbers
396 To convert an integer to floating point, use the function @code{float}.
398 @defun float number
399 This returns @var{number} converted to floating point.
400 If @var{number} is already a floating point number, @code{float} returns
401 it unchanged.
402 @end defun
404 There are four functions to convert floating point numbers to integers;
405 they differ in how they round.  All accept an argument @var{number}
406 and an optional argument @var{divisor}.  Both arguments may be
407 integers or floating point numbers.  @var{divisor} may also be
408 @code{nil}.  If @var{divisor} is @code{nil} or omitted, these
409 functions convert @var{number} to an integer, or return it unchanged
410 if it already is an integer.  If @var{divisor} is non-@code{nil}, they
411 divide @var{number} by @var{divisor} and convert the result to an
412 integer.  An @code{arith-error} results if @var{divisor} is 0.
414 @defun truncate number &optional divisor
415 This returns @var{number}, converted to an integer by rounding towards
416 zero.
418 @example
419 (truncate 1.2)
420      @result{} 1
421 (truncate 1.7)
422      @result{} 1
423 (truncate -1.2)
424      @result{} -1
425 (truncate -1.7)
426      @result{} -1
427 @end example
428 @end defun
430 @defun floor number &optional divisor
431 This returns @var{number}, converted to an integer by rounding downward
432 (towards negative infinity).
434 If @var{divisor} is specified, this uses the kind of division
435 operation that corresponds to @code{mod}, rounding downward.
437 @example
438 (floor 1.2)
439      @result{} 1
440 (floor 1.7)
441      @result{} 1
442 (floor -1.2)
443      @result{} -2
444 (floor -1.7)
445      @result{} -2
446 (floor 5.99 3)
447      @result{} 1
448 @end example
449 @end defun
451 @defun ceiling number &optional divisor
452 This returns @var{number}, converted to an integer by rounding upward
453 (towards positive infinity).
455 @example
456 (ceiling 1.2)
457      @result{} 2
458 (ceiling 1.7)
459      @result{} 2
460 (ceiling -1.2)
461      @result{} -1
462 (ceiling -1.7)
463      @result{} -1
464 @end example
465 @end defun
467 @defun round number &optional divisor
468 This returns @var{number}, converted to an integer by rounding towards the
469 nearest integer.  Rounding a value equidistant between two integers
470 may choose the integer closer to zero, or it may prefer an even integer,
471 depending on your machine.
473 @example
474 (round 1.2)
475      @result{} 1
476 (round 1.7)
477      @result{} 2
478 (round -1.2)
479      @result{} -1
480 (round -1.7)
481      @result{} -2
482 @end example
483 @end defun
485 @node Arithmetic Operations
486 @section Arithmetic Operations
487 @cindex arithmetic operations
489   Emacs Lisp provides the traditional four arithmetic operations:
490 addition, subtraction, multiplication, and division.  Remainder and modulus
491 functions supplement the division functions.  The functions to
492 add or subtract 1 are provided because they are traditional in Lisp and
493 commonly used.
495   All of these functions except @code{%} return a floating point value
496 if any argument is floating.
498   It is important to note that in Emacs Lisp, arithmetic functions
499 do not check for overflow.  Thus @code{(1+ 268435455)} may evaluate to
500 @minus{}268435456, depending on your hardware.
502 @defun 1+ number-or-marker
503 This function returns @var{number-or-marker} plus 1.
504 For example,
506 @example
507 (setq foo 4)
508      @result{} 4
509 (1+ foo)
510      @result{} 5
511 @end example
513 This function is not analogous to the C operator @code{++}---it does not
514 increment a variable.  It just computes a sum.  Thus, if we continue,
516 @example
518      @result{} 4
519 @end example
521 If you want to increment the variable, you must use @code{setq},
522 like this:
524 @example
525 (setq foo (1+ foo))
526      @result{} 5
527 @end example
528 @end defun
530 @defun 1- number-or-marker
531 This function returns @var{number-or-marker} minus 1.
532 @end defun
534 @defun + &rest numbers-or-markers
535 This function adds its arguments together.  When given no arguments,
536 @code{+} returns 0.
538 @example
540      @result{} 0
541 (+ 1)
542      @result{} 1
543 (+ 1 2 3 4)
544      @result{} 10
545 @end example
546 @end defun
548 @defun - &optional number-or-marker &rest more-numbers-or-markers
549 The @code{-} function serves two purposes: negation and subtraction.
550 When @code{-} has a single argument, the value is the negative of the
551 argument.  When there are multiple arguments, @code{-} subtracts each of
552 the @var{more-numbers-or-markers} from @var{number-or-marker},
553 cumulatively.  If there are no arguments, the result is 0.
555 @example
556 (- 10 1 2 3 4)
557      @result{} 0
558 (- 10)
559      @result{} -10
561      @result{} 0
562 @end example
563 @end defun
565 @defun * &rest numbers-or-markers
566 This function multiplies its arguments together, and returns the
567 product.  When given no arguments, @code{*} returns 1.
569 @example
571      @result{} 1
572 (* 1)
573      @result{} 1
574 (* 1 2 3 4)
575      @result{} 24
576 @end example
577 @end defun
579 @defun / dividend divisor &rest divisors
580 This function divides @var{dividend} by @var{divisor} and returns the
581 quotient.  If there are additional arguments @var{divisors}, then it
582 divides @var{dividend} by each divisor in turn.  Each argument may be a
583 number or a marker.
585 If all the arguments are integers, then the result is an integer too.
586 This means the result has to be rounded.  On most machines, the result
587 is rounded towards zero after each division, but some machines may round
588 differently with negative arguments.  This is because the Lisp function
589 @code{/} is implemented using the C division operator, which also
590 permits machine-dependent rounding.  As a practical matter, all known
591 machines round in the standard fashion.
593 @cindex @code{arith-error} in division
594 If you divide an integer by 0, an @code{arith-error} error is signaled.
595 (@xref{Errors}.)  Floating point division by zero returns either
596 infinity or a NaN if your machine supports @acronym{IEEE} floating point;
597 otherwise, it signals an @code{arith-error} error.
599 @example
600 @group
601 (/ 6 2)
602      @result{} 3
603 @end group
604 (/ 5 2)
605      @result{} 2
606 (/ 5.0 2)
607      @result{} 2.5
608 (/ 5 2.0)
609      @result{} 2.5
610 (/ 5.0 2.0)
611      @result{} 2.5
612 (/ 25 3 2)
613      @result{} 4
614 @group
615 (/ -17 6)
616      @result{} -2   @r{(could in theory be @minus{}3 on some machines)}
617 @end group
618 @end example
619 @end defun
621 @defun % dividend divisor
622 @cindex remainder
623 This function returns the integer remainder after division of @var{dividend}
624 by @var{divisor}.  The arguments must be integers or markers.
626 For negative arguments, the remainder is in principle machine-dependent
627 since the quotient is; but in practice, all known machines behave alike.
629 An @code{arith-error} results if @var{divisor} is 0.
631 @example
632 (% 9 4)
633      @result{} 1
634 (% -9 4)
635      @result{} -1
636 (% 9 -4)
637      @result{} 1
638 (% -9 -4)
639      @result{} -1
640 @end example
642 For any two integers @var{dividend} and @var{divisor},
644 @example
645 @group
646 (+ (% @var{dividend} @var{divisor})
647    (* (/ @var{dividend} @var{divisor}) @var{divisor}))
648 @end group
649 @end example
651 @noindent
652 always equals @var{dividend}.
653 @end defun
655 @defun mod dividend divisor
656 @cindex modulus
657 This function returns the value of @var{dividend} modulo @var{divisor};
658 in other words, the remainder after division of @var{dividend}
659 by @var{divisor}, but with the same sign as @var{divisor}.
660 The arguments must be numbers or markers.
662 Unlike @code{%}, @code{mod} returns a well-defined result for negative
663 arguments.  It also permits floating point arguments; it rounds the
664 quotient downward (towards minus infinity) to an integer, and uses that
665 quotient to compute the remainder.
667 An @code{arith-error} results if @var{divisor} is 0.
669 @example
670 @group
671 (mod 9 4)
672      @result{} 1
673 @end group
674 @group
675 (mod -9 4)
676      @result{} 3
677 @end group
678 @group
679 (mod 9 -4)
680      @result{} -3
681 @end group
682 @group
683 (mod -9 -4)
684      @result{} -1
685 @end group
686 @group
687 (mod 5.5 2.5)
688      @result{} .5
689 @end group
690 @end example
692 For any two numbers @var{dividend} and @var{divisor},
694 @example
695 @group
696 (+ (mod @var{dividend} @var{divisor})
697    (* (floor @var{dividend} @var{divisor}) @var{divisor}))
698 @end group
699 @end example
701 @noindent
702 always equals @var{dividend}, subject to rounding error if either
703 argument is floating point.  For @code{floor}, see @ref{Numeric
704 Conversions}.
705 @end defun
707 @node Rounding Operations
708 @section Rounding Operations
709 @cindex rounding without conversion
711 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
712 @code{ftruncate} take a floating point argument and return a floating
713 point result whose value is a nearby integer.  @code{ffloor} returns the
714 nearest integer below; @code{fceiling}, the nearest integer above;
715 @code{ftruncate}, the nearest integer in the direction towards zero;
716 @code{fround}, the nearest integer.
718 @defun ffloor float
719 This function rounds @var{float} to the next lower integral value, and
720 returns that value as a floating point number.
721 @end defun
723 @defun fceiling float
724 This function rounds @var{float} to the next higher integral value, and
725 returns that value as a floating point number.
726 @end defun
728 @defun ftruncate float
729 This function rounds @var{float} towards zero to an integral value, and
730 returns that value as a floating point number.
731 @end defun
733 @defun fround float
734 This function rounds @var{float} to the nearest integral value,
735 and returns that value as a floating point number.
736 @end defun
738 @node Bitwise Operations
739 @section Bitwise Operations on Integers
740 @cindex bitwise arithmetic
741 @cindex logical arithmetic
743   In a computer, an integer is represented as a binary number, a
744 sequence of @dfn{bits} (digits which are either zero or one).  A bitwise
745 operation acts on the individual bits of such a sequence.  For example,
746 @dfn{shifting} moves the whole sequence left or right one or more places,
747 reproducing the same pattern ``moved over.''
749   The bitwise operations in Emacs Lisp apply only to integers.
751 @defun lsh integer1 count
752 @cindex logical shift
753 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
754 bits in @var{integer1} to the left @var{count} places, or to the right
755 if @var{count} is negative, bringing zeros into the vacated bits.  If
756 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
757 (most-significant) bit, producing a positive result even if
758 @var{integer1} is negative.  Contrast this with @code{ash}, below.
760 Here are two examples of @code{lsh}, shifting a pattern of bits one
761 place to the left.  We show only the low-order eight bits of the binary
762 pattern; the rest are all zero.
764 @example
765 @group
766 (lsh 5 1)
767      @result{} 10
768 ;; @r{Decimal 5 becomes decimal 10.}
769 00000101 @result{} 00001010
771 (lsh 7 1)
772      @result{} 14
773 ;; @r{Decimal 7 becomes decimal 14.}
774 00000111 @result{} 00001110
775 @end group
776 @end example
778 @noindent
779 As the examples illustrate, shifting the pattern of bits one place to
780 the left produces a number that is twice the value of the previous
781 number.
783 Shifting a pattern of bits two places to the left produces results
784 like this (with 8-bit binary numbers):
786 @example
787 @group
788 (lsh 3 2)
789      @result{} 12
790 ;; @r{Decimal 3 becomes decimal 12.}
791 00000011 @result{} 00001100
792 @end group
793 @end example
795 On the other hand, shifting one place to the right looks like this:
797 @example
798 @group
799 (lsh 6 -1)
800      @result{} 3
801 ;; @r{Decimal 6 becomes decimal 3.}
802 00000110 @result{} 00000011
803 @end group
805 @group
806 (lsh 5 -1)
807      @result{} 2
808 ;; @r{Decimal 5 becomes decimal 2.}
809 00000101 @result{} 00000010
810 @end group
811 @end example
813 @noindent
814 As the example illustrates, shifting one place to the right divides the
815 value of a positive integer by two, rounding downward.
817 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
818 not check for overflow, so shifting left can discard significant bits
819 and change the sign of the number.  For example, left shifting
820 268,435,455 produces @minus{}2 on a 29-bit machine:
822 @example
823 (lsh 268435455 1)          ; @r{left shift}
824      @result{} -2
825 @end example
827 In binary, in the 29-bit implementation, the argument looks like this:
829 @example
830 @group
831 ;; @r{Decimal 268,435,455}
832 0 1111  1111 1111  1111 1111  1111 1111
833 @end group
834 @end example
836 @noindent
837 which becomes the following when left shifted:
839 @example
840 @group
841 ;; @r{Decimal @minus{}2}
842 1 1111  1111 1111  1111 1111  1111 1110
843 @end group
844 @end example
845 @end defun
847 @defun ash integer1 count
848 @cindex arithmetic shift
849 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
850 to the left @var{count} places, or to the right if @var{count}
851 is negative.
853 @code{ash} gives the same results as @code{lsh} except when
854 @var{integer1} and @var{count} are both negative.  In that case,
855 @code{ash} puts ones in the empty bit positions on the left, while
856 @code{lsh} puts zeros in those bit positions.
858 Thus, with @code{ash}, shifting the pattern of bits one place to the right
859 looks like this:
861 @example
862 @group
863 (ash -6 -1) @result{} -3
864 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
865 1 1111  1111 1111  1111 1111  1111 1010
866      @result{}
867 1 1111  1111 1111  1111 1111  1111 1101
868 @end group
869 @end example
871 In contrast, shifting the pattern of bits one place to the right with
872 @code{lsh} looks like this:
874 @example
875 @group
876 (lsh -6 -1) @result{} 268435453
877 ;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
878 1 1111  1111 1111  1111 1111  1111 1010
879      @result{}
880 0 1111  1111 1111  1111 1111  1111 1101
881 @end group
882 @end example
884 Here are other examples:
886 @c !!! Check if lined up in smallbook format!  XDVI shows problem
887 @c     with smallbook but not with regular book! --rjc 16mar92
888 @smallexample
889 @group
890                    ;  @r{             29-bit binary values}
892 (lsh 5 2)          ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
893      @result{} 20         ;      =  @r{0 0000  0000 0000  0000 0000  0001 0100}
894 @end group
895 @group
896 (ash 5 2)
897      @result{} 20
898 (lsh -5 2)         ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
899      @result{} -20        ;      =  @r{1 1111  1111 1111  1111 1111  1110 1100}
900 (ash -5 2)
901      @result{} -20
902 @end group
903 @group
904 (lsh 5 -2)         ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
905      @result{} 1          ;      =  @r{0 0000  0000 0000  0000 0000  0000 0001}
906 @end group
907 @group
908 (ash 5 -2)
909      @result{} 1
910 @end group
911 @group
912 (lsh -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
913      @result{} 134217726  ;      =  @r{0 0111  1111 1111  1111 1111  1111 1110}
914 @end group
915 @group
916 (ash -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
917      @result{} -2         ;      =  @r{1 1111  1111 1111  1111 1111  1111 1110}
918 @end group
919 @end smallexample
920 @end defun
922 @defun logand &rest ints-or-markers
923 This function returns the ``logical and'' of the arguments: the
924 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
925 set in all the arguments.  (``Set'' means that the value of the bit is 1
926 rather than 0.)
928 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
929 12 is 12: 1101 combined with 1100 produces 1100.
930 In both the binary numbers, the leftmost two bits are set (i.e., they
931 are 1's), so the leftmost two bits of the returned value are set.
932 However, for the rightmost two bits, each is zero in at least one of
933 the arguments, so the rightmost two bits of the returned value are 0's.
935 @noindent
936 Therefore,
938 @example
939 @group
940 (logand 13 12)
941      @result{} 12
942 @end group
943 @end example
945 If @code{logand} is not passed any argument, it returns a value of
946 @minus{}1.  This number is an identity element for @code{logand}
947 because its binary representation consists entirely of ones.  If
948 @code{logand} is passed just one argument, it returns that argument.
950 @smallexample
951 @group
952                    ; @r{               29-bit binary values}
954 (logand 14 13)     ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
955                    ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
956      @result{} 12         ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
957 @end group
959 @group
960 (logand 14 13 4)   ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
961                    ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
962                    ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
963      @result{} 4          ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
964 @end group
966 @group
967 (logand)
968      @result{} -1         ; -1  =  @r{1 1111  1111 1111  1111 1111  1111 1111}
969 @end group
970 @end smallexample
971 @end defun
973 @defun logior &rest ints-or-markers
974 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
975 is set in the result if, and only if, the @var{n}th bit is set in at least
976 one of the arguments.  If there are no arguments, the result is zero,
977 which is an identity element for this operation.  If @code{logior} is
978 passed just one argument, it returns that argument.
980 @smallexample
981 @group
982                    ; @r{              29-bit binary values}
984 (logior 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
985                    ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
986      @result{} 13         ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
987 @end group
989 @group
990 (logior 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
991                    ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
992                    ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
993      @result{} 15         ; 15  =  @r{0 0000  0000 0000  0000 0000  0000 1111}
994 @end group
995 @end smallexample
996 @end defun
998 @defun logxor &rest ints-or-markers
999 This function returns the ``exclusive or'' of its arguments: the
1000 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
1001 set in an odd number of the arguments.  If there are no arguments, the
1002 result is 0, which is an identity element for this operation.  If
1003 @code{logxor} is passed just one argument, it returns that argument.
1005 @smallexample
1006 @group
1007                    ; @r{              29-bit binary values}
1009 (logxor 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
1010                    ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
1011      @result{} 9          ;  9  =  @r{0 0000  0000 0000  0000 0000  0000 1001}
1012 @end group
1014 @group
1015 (logxor 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
1016                    ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
1017                    ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
1018      @result{} 14         ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
1019 @end group
1020 @end smallexample
1021 @end defun
1023 @defun lognot integer
1024 This function returns the logical complement of its argument: the @var{n}th
1025 bit is one in the result if, and only if, the @var{n}th bit is zero in
1026 @var{integer}, and vice-versa.
1028 @example
1029 (lognot 5)
1030      @result{} -6
1031 ;;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
1032 ;; @r{becomes}
1033 ;; -6  =  @r{1 1111  1111 1111  1111 1111  1111 1010}
1034 @end example
1035 @end defun
1037 @node Math Functions
1038 @section Standard Mathematical Functions
1039 @cindex transcendental functions
1040 @cindex mathematical functions
1041 @cindex floating-point functions
1043   These mathematical functions allow integers as well as floating point
1044 numbers as arguments.
1046 @defun sin arg
1047 @defunx cos arg
1048 @defunx tan arg
1049 These are the ordinary trigonometric functions, with argument measured
1050 in radians.
1051 @end defun
1053 @defun asin arg
1054 The value of @code{(asin @var{arg})} is a number between
1055 @ifnottex
1056 @minus{}pi/2
1057 @end ifnottex
1058 @tex
1059 @math{-\pi/2}
1060 @end tex
1062 @ifnottex
1063 pi/2
1064 @end ifnottex
1065 @tex
1066 @math{\pi/2}
1067 @end tex
1068 (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
1069 range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1070 @end defun
1072 @defun acos arg
1073 The value of @code{(acos @var{arg})} is a number between 0 and
1074 @ifnottex
1076 @end ifnottex
1077 @tex
1078 @math{\pi}
1079 @end tex
1080 (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
1081 of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
1082 @end defun
1084 @defun atan y &optional x
1085 The value of @code{(atan @var{y})} is a number between
1086 @ifnottex
1087 @minus{}pi/2
1088 @end ifnottex
1089 @tex
1090 @math{-\pi/2}
1091 @end tex
1093 @ifnottex
1094 pi/2
1095 @end ifnottex
1096 @tex
1097 @math{\pi/2}
1098 @end tex
1099 (exclusive) whose tangent is @var{y}.  If the optional second
1100 argument @var{x} is given, the value of @code{(atan y x)} is the
1101 angle in radians between the vector @code{[@var{x}, @var{y}]} and the
1102 @code{X} axis.
1103 @end defun
1105 @defun exp arg
1106 This is the exponential function; it returns
1107 @tex
1108 @math{e}
1109 @end tex
1110 @ifnottex
1111 @i{e}
1112 @end ifnottex
1113 to the power @var{arg}.
1114 @tex
1115 @math{e}
1116 @end tex
1117 @ifnottex
1118 @i{e}
1119 @end ifnottex
1120 is a fundamental mathematical constant also called the base of natural
1121 logarithms.
1122 @end defun
1124 @defun log arg &optional base
1125 This function returns the logarithm of @var{arg}, with base @var{base}.
1126 If you don't specify @var{base}, the base
1127 @tex
1128 @math{e}
1129 @end tex
1130 @ifnottex
1131 @i{e}
1132 @end ifnottex
1133 is used.  If @var{arg} is negative, it signals a @code{domain-error}
1134 error.
1135 @end defun
1137 @ignore
1138 @defun expm1 arg
1139 This function returns @code{(1- (exp @var{arg}))}, but it is more
1140 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1141 is close to 1.
1142 @end defun
1144 @defun log1p arg
1145 This function returns @code{(log (1+ @var{arg}))}, but it is more
1146 accurate than that when @var{arg} is so small that adding 1 to it would
1147 lose accuracy.
1148 @end defun
1149 @end ignore
1151 @defun log10 arg
1152 This function returns the logarithm of @var{arg}, with base 10.  If
1153 @var{arg} is negative, it signals a @code{domain-error} error.
1154 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
1155 approximately.
1156 @end defun
1158 @defun expt x y
1159 This function returns @var{x} raised to power @var{y}.  If both
1160 arguments are integers and @var{y} is positive, the result is an
1161 integer; in this case, overflow causes truncation, so watch out.
1162 @end defun
1164 @defun sqrt arg
1165 This returns the square root of @var{arg}.  If @var{arg} is negative,
1166 it signals a @code{domain-error} error.
1167 @end defun
1169 @node Random Numbers
1170 @section Random Numbers
1171 @cindex random numbers
1173 A deterministic computer program cannot generate true random numbers.
1174 For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
1175 pseudo-random numbers is generated in a deterministic fashion.  The
1176 numbers are not truly random, but they have certain properties that
1177 mimic a random series.  For example, all possible values occur equally
1178 often in a pseudo-random series.
1180 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
1181 Starting from any given seed, the @code{random} function always
1182 generates the same sequence of numbers.  Emacs always starts with the
1183 same seed value, so the sequence of values of @code{random} is actually
1184 the same in each Emacs run!  For example, in one operating system, the
1185 first call to @code{(random)} after you start Emacs always returns
1186 @minus{}1457731, and the second one always returns @minus{}7692030.  This
1187 repeatability is helpful for debugging.
1189 If you want random numbers that don't always come out the same, execute
1190 @code{(random t)}.  This chooses a new seed based on the current time of
1191 day and on Emacs's process @acronym{ID} number.
1193 @defun random &optional limit
1194 This function returns a pseudo-random integer.  Repeated calls return a
1195 series of pseudo-random integers.
1197 If @var{limit} is a positive integer, the value is chosen to be
1198 nonnegative and less than @var{limit}.
1200 If @var{limit} is @code{t}, it means to choose a new seed based on the
1201 current time of day and on Emacs's process @acronym{ID} number.
1202 @c "Emacs'" is incorrect usage!
1204 On some machines, any integer representable in Lisp may be the result
1205 of @code{random}.  On other machines, the result can never be larger
1206 than a certain maximum or less than a certain (negative) minimum.
1207 @end defun
1209 @ignore
1210    arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e
1211 @end ignore