lispref/numbers.texi

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