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 * Transcendental 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 range is @minus{}8388608 to 8388607 (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 on most machines, but some machines may have a wider range.  Many
  57 examples in this 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 24-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   (< (/ (abs (- x y))
 253         (max (abs x) (abs y)))
 254      fuzz-factor))
 255 @end example
 256
 257 @cindex CL note---integers vrs @code{eq}
 258 @quotation
 259 @b{Common Lisp note:} Comparing numbers in Common Lisp always requires
 260 @code{=} because Common Lisp implements multi-word integers, and two
 261 distinct integer objects can have the same numeric value.  Emacs Lisp
 262 can have just one integer object for any given value because it has a
 263 limited range of integer values.
 264 @end quotation
 265
 266 @defun = number-or-marker1 number-or-marker2
 267 This function tests whether its arguments are numerically equal, and
 268 returns @code{t} if so, @code{nil} otherwise.
 269 @end defun
 270
 271 @defun /= number-or-marker1 number-or-marker2
 272 This function tests whether its arguments are numerically equal, and
 273 returns @code{t} if they are not, and @code{nil} if they are.
 274 @end defun
 275
 276 @defun <  number-or-marker1 number-or-marker2
 277 This function tests whether its first argument is strictly less than
 278 its second argument.  It returns @code{t} if so, @code{nil} otherwise.
 279 @end defun
 280
 281 @defun <=  number-or-marker1 number-or-marker2
 282 This function tests whether its first argument is less than or equal
 283 to its second argument.  It returns @code{t} if so, @code{nil}
 284 otherwise.
 285 @end defun
 286
 287 @defun >  number-or-marker1 number-or-marker2
 288 This function tests whether its first argument is strictly greater
 289 than its second argument.  It returns @code{t} if so, @code{nil}
 290 otherwise.
 291 @end defun
 292
 293 @defun >=  number-or-marker1 number-or-marker2
 294 This function tests whether its first argument is greater than or
 295 equal to its second argument.  It returns @code{t} if so, @code{nil}
 296 otherwise.
 297 @end defun
 298
 299 @defun max number-or-marker &rest numbers-or-markers
 300 This function returns the largest of its arguments.
 301
 302 @example
 303 (max 20)
 304      @result{} 20
 305 (max 1 2.5)
 306      @result{} 2.5
 307 (max 1 3 2.5)
 308      @result{} 3
 309 @end example
 310 @end defun
 311
 312 @defun min number-or-marker &rest numbers-or-markers
 313 This function returns the smallest of its arguments.
 314
 315 @example
 316 (min -4 1)
 317      @result{} -4
 318 @end example
 319 @end defun
 320
 321 @node Numeric Conversions
 322 @section Numeric Conversions
 323 @cindex rounding in conversions
 324
 325 To convert an integer to floating point, use the function @code{float}.
 326
 327 @defun float number
 328 This returns @var{number} converted to floating point.
 329 If @var{number} is already a floating point number, @code{float} returns
 330 it unchanged.
 331 @end defun
 332
 333 There are four functions to convert floating point numbers to integers;
 334 they differ in how they round.  These functions accept integer arguments
 335 also, and return such arguments unchanged.
 336
 337 @defun truncate number
 338 This returns @var{number}, converted to an integer by rounding towards
 339 zero.
 340 @end defun
 341
 342 @defun floor number &optional divisor
 343 This returns @var{number}, converted to an integer by rounding downward
 344 (towards negative infinity).
 345
 346 If @var{divisor} is specified, @var{number} is divided by @var{divisor}
 347 before the floor is taken; this is the division operation that
 348 corresponds to @code{mod}.  An @code{arith-error} results if
 349 @var{divisor} is 0.
 350 @end defun
 351
 352 @defun ceiling number
 353 This returns @var{number}, converted to an integer by rounding upward
 354 (towards positive infinity).
 355 @end defun
 356
 357 @defun round number
 358 This returns @var{number}, converted to an integer by rounding towards the
 359 nearest integer.
 360 @end defun
 361
 362 @node Arithmetic Operations
 363 @section Arithmetic Operations
 364
 365   Emacs Lisp provides the traditional four arithmetic operations:
 366 addition, subtraction, multiplication, and division.  Remainder and modulus
 367 functions supplement the division functions.  The functions to
 368 add or subtract 1 are provided because they are traditional in Lisp and
 369 commonly used.
 370
 371   All of these functions except @code{%} return a floating point value
 372 if any argument is floating.
 373
 374   It is important to note that in GNU Emacs Lisp, arithmetic functions
 375 do not check for overflow.  Thus @code{(1+ 8388607)} may evaluate to
 376 @minus{}8388608, depending on your hardware.
 377
 378 @defun 1+ number-or-marker
 379 This function returns @var{number-or-marker} plus 1.
 380 For example,
 381
 382 @example
 383 (setq foo 4)
 384      @result{} 4
 385 (1+ foo)
 386      @result{} 5
 387 @end example
 388
 389 This function is not analogous to the C operator @code{++}---it does
 390 not increment a variable.  It just computes a sum.  Thus,
 391
 392 @example
 393 foo
 394      @result{} 4
 395 @end example
 396
 397 If you want to increment the variable, you must use @code{setq},
 398 like this:
 399
 400 @example
 401 (setq foo (1+ foo))
 402      @result{} 5
 403 @end example
 404 @end defun
 405
 406 @defun 1- number-or-marker
 407 This function returns @var{number-or-marker} minus 1.
 408 @end defun
 409
 410 @defun abs number
 411 This returns the absolute value of @var{number}.
 412 @end defun
 413
 414 @defun + &rest numbers-or-markers
 415 This function adds its arguments together.  When given no arguments,
 416 @code{+} returns 0.  It does not check for overflow.
 417
 418 @example
 419 (+)
 420      @result{} 0
 421 (+ 1)
 422      @result{} 1
 423 (+ 1 2 3 4)
 424      @result{} 10
 425 @end example
 426 @end defun
 427
 428 @defun - &optional number-or-marker &rest other-numbers-or-markers
 429 The @code{-} function serves two purposes: negation and subtraction.
 430 When @code{-} has a single argument, the value is the negative of the
 431 argument.  When there are multiple arguments, @code{-} subtracts each of
 432 the @var{other-numbers-or-markers} from @var{number-or-marker},
 433 cumulatively.  If there are no arguments, the result is 0.  This
 434 function does not check for overflow.
 435
 436 @example
 437 (- 10 1 2 3 4)
 438      @result{} 0
 439 (- 10)
 440      @result{} -10
 441 (-)
 442      @result{} 0
 443 @end example
 444 @end defun
 445
 446 @defun * &rest numbers-or-markers
 447 This function multiplies its arguments together, and returns the
 448 product.  When given no arguments, @code{*} returns 1.  It does
 449 not check for overflow.
 450
 451 @example
 452 (*)
 453      @result{} 1
 454 (* 1)
 455      @result{} 1
 456 (* 1 2 3 4)
 457      @result{} 24
 458 @end example
 459 @end defun
 460
 461 @defun / dividend divisor &rest divisors
 462 This function divides @var{dividend} by @var{divisor} and returns the
 463 quotient.  If there are additional arguments @var{divisors}, then it
 464 divides @var{dividend} by each divisor in turn.  Each argument may be a
 465 number or a marker.
 466
 467 If all the arguments are integers, then the result is an integer too.
 468 This means the result has to be rounded.  On most machines, the result
 469 is rounded towards zero after each division, but some machines may round
 470 differently with negative arguments.  This is because the Lisp function
 471 @code{/} is implemented using the C division operator, which also
 472 permits machine-dependent rounding.  As a practical matter, all known
 473 machines round in the standard fashion.
 474
 475 @cindex @code{arith-error} in division
 476 If you divide by 0, an @code{arith-error} error is signaled.
 477 (@xref{Errors}.)
 478
 479 @example
 480 (/ 6 2)
 481      @result{} 3
 482 (/ 5 2)
 483      @result{} 2
 484 (/ 25 3 2)
 485      @result{} 4
 486 (/ -17 6)
 487      @result{} -2
 488 @end example
 489
 490 The result of @code{(/ -17 6)} could in principle be -3 on some
 491 machines.
 492 @end defun
 493
 494 @defun % dividend divisor
 495 @cindex remainder
 496 This function returns the integer remainder after division of @var{dividend}
 497 by @var{divisor}.  The arguments must be integers or markers.
 498
 499 For negative arguments, the remainder is in principle machine-dependent
 500 since the quotient is; but in practice, all known machines behave alike.
 501
 502 An @code{arith-error} results if @var{divisor} is 0.
 503
 504 @example
 505 (% 9 4)
 506      @result{} 1
 507 (% -9 4)
 508      @result{} -1
 509 (% 9 -4)
 510      @result{} 1
 511 (% -9 -4)
 512      @result{} -1
 513 @end example
 514
 515 For any two integers @var{dividend} and @var{divisor},
 516
 517 @example
 518 @group
 519 (+ (% @var{dividend} @var{divisor})
 520    (* (/ @var{dividend} @var{divisor}) @var{divisor}))
 521 @end group
 522 @end example
 523
 524 @noindent
 525 always equals @var{dividend}.
 526 @end defun
 527
 528 @defun mod dividend divisor
 529 @cindex modulus
 530 This function returns the value of @var{dividend} modulo @var{divisor};
 531 in other words, the remainder after division of @var{dividend}
 532 by @var{divisor}, but with the same sign as @var{divisor}.
 533 The arguments must be numbers or markers.
 534
 535 Unlike @code{%}, @code{mod} returns a well-defined result for negative
 536 arguments.  It also permits floating point arguments; it rounds the
 537 quotient downward (towards minus infinity) to an integer, and uses that
 538 quotient to compute the remainder.
 539
 540 An @code{arith-error} results if @var{divisor} is 0.
 541
 542 @example
 543 (mod 9 4)
 544      @result{} 1
 545 (mod -9 4)
 546      @result{} 3
 547 (mod 9 -4)
 548      @result{} -3
 549 (mod -9 -4)
 550      @result{} -1
 551 (mod 5.5 2.5)
 552      @result{} .5
 553 @end example
 554
 555 For any two numbers @var{dividend} and @var{divisor},
 556
 557 @example
 558 @group
 559 (+ (mod @var{dividend} @var{divisor})
 560    (* (floor @var{dividend} @var{divisor}) @var{divisor}))
 561 @end group
 562 @end example
 563
 564 @noindent
 565 always equals @var{dividend}, subject to rounding error if
 566 either argument is floating point.
 567 @end defun
 568
 569 @node Rounding Operations
 570 @section Rounding Operations
 571 @cindex rounding without conversion
 572
 573 The functions @code{ffloor}, @code{fceiling}, @code{fround} and
 574 @code{ftruncate} take a floating point argument and return a floating
 575 point result whose value is a nearby integer.  @code{ffloor} returns the
 576 nearest integer below; @code{fceiling}, the nearest integer above;
 577 @code{ftruncate}, the nearest integer in the direction towards zero;
 578 @code{fround}, the nearest integer.
 579
 580 @defun ffloor float
 581 This function rounds @var{float} to the next lower integral value, and
 582 returns that value as a floating point number.
 583 @end defun
 584
 585 @defun fceiling float
 586 This function rounds @var{float} to the next higher integral value, and
 587 returns that value as a floating point number.
 588 @end defun
 589
 590 @defun ftruncate float
 591 This function rounds @var{float} towards zero to an integral value, and
 592 returns that value as a floating point number.
 593 @end defun
 594
 595 @defun fround float
 596 This function rounds @var{float} to the nearest integral value,
 597 and returns that value as a floating point number.
 598 @end defun
 599
 600 @node Bitwise Operations
 601 @section Bitwise Operations on Integers
 602
 603   In a computer, an integer is represented as a binary number, a
 604 sequence of @dfn{bits} (digits which are either zero or one).  A bitwise
 605 operation acts on the individual bits of such a sequence.  For example,
 606 @dfn{shifting} moves the whole sequence left or right one or more places,
 607 reproducing the same pattern ``moved over''.
 608
 609   The bitwise operations in Emacs Lisp apply only to integers.
 610
 611 @defun lsh integer1 count
 612 @cindex logical shift
 613 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
 614 bits in @var{integer1} to the left @var{count} places, or to the right
 615 if @var{count} is negative, bringing zeros into the vacated bits.  If
 616 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
 617 (most-significant) bit, producing a positive result even if
 618 @var{integer1} is negative.  Contrast this with @code{ash}, below.
 619
 620 Here are two examples of @code{lsh}, shifting a pattern of bits one
 621 place to the left.  We show only the low-order eight bits of the binary
 622 pattern; the rest are all zero.
 623
 624 @example
 625 @group
 626 (lsh 5 1)
 627      @result{} 10
 628 ;; @r{Decimal 5 becomes decimal 10.}
 629 00000101 @result{} 00001010
 630
 631 (lsh 7 1)
 632      @result{} 14
 633 ;; @r{Decimal 7 becomes decimal 14.}
 634 00000111 @result{} 00001110
 635 @end group
 636 @end example
 637
 638 @noindent
 639 As the examples illustrate, shifting the pattern of bits one place to
 640 the left produces a number that is twice the value of the previous
 641 number.
 642
 643 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
 644 not check for overflow, so shifting left can discard significant bits
 645 and change the sign of the number.  For example, left shifting 8,388,607
 646 produces @minus{}2 on a 24-bit machine:
 647
 648 @example
 649 (lsh 8388607 1)          ; @r{left shift}
 650      @result{} -2
 651 @end example
 652
 653 In binary, in the 28-bit implementation, the argument looks like this:
 654
 655 @example
 656 @group
 657 ;; @r{Decimal 134.217,727}
 658 0111  1111 1111  1111 1111  1111 1111
 659 @end group
 660 @end example
 661
 662 @noindent
 663 which becomes the following when left shifted:
 664
 665 @example
 666 @group
 667 ;; @r{Decimal @minus{}2}
 668 1111  1111 1111  1111 1111  1111 1110
 669 @end group
 670 @end example
 671
 672 Shifting the pattern of bits two places to the left produces results
 673 like this (with 8-bit binary numbers):
 674
 675 @example
 676 @group
 677 (lsh 3 2)
 678      @result{} 12
 679 ;; @r{Decimal 3 becomes decimal 12.}
 680 00000011 @result{} 00001100
 681 @end group
 682 @end example
 683
 684 On the other hand, shifting the pattern of bits one place to the right
 685 looks like this:
 686
 687 @example
 688 @group
 689 (lsh 6 -1)
 690      @result{} 3
 691 ;; @r{Decimal 6 becomes decimal 3.}
 692 00000110 @result{} 00000011
 693 @end group
 694
 695 @group
 696 (lsh 5 -1)
 697      @result{} 2
 698 ;; @r{Decimal 5 becomes decimal 2.}
 699 00000101 @result{} 00000010
 700 @end group
 701 @end example
 702
 703 @noindent
 704 As the example illustrates, shifting the pattern of bits one place to
 705 the right divides the value of the binary number by two, rounding downward.
 706 @end defun
 707
 708 @defun ash integer1 count
 709 @cindex arithmetic shift
 710 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
 711 to the left @var{count} places, or to the right if @var{count}
 712 is negative.
 713
 714 @code{ash} gives the same results as @code{lsh} except when
 715 @var{integer1} and @var{count} are both negative.  In that case,
 716 @code{ash} puts a one in the leftmost position, while @code{lsh} puts
 717 a zero in the leftmost position.
 718
 719 Thus, with @code{ash}, shifting the pattern of bits one place to the right
 720 looks like this:
 721
 722 @example
 723 @group
 724 (ash -6 -1) @result{} -3
 725 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
 726 1111  1111 1111  1111 1111  1111 1010
 727      @result{}
 728 1111  1111 1111  1111 1111  1111 1101
 729 @end group
 730 @end example
 731
 732 In contrast, shifting the pattern of bits one place to the right with
 733 @code{lsh} looks like this:
 734
 735 @example
 736 @group
 737 (lsh -6 -1) @result{} 134217725
 738 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
 739 1111  1111 1111  1111 1111  1111 1010
 740      @result{}
 741 0111  1111 1111  1111 1111  1111 1101
 742 @end group
 743 @end example
 744
 745 Here are other examples:
 746
 747 @c !!! Check if lined up in smallbook format!  XDVI shows problem
 748 @c     with smallbook but not with regular book! --rjc 16mar92
 749 @smallexample
 750 @group
 751                    ;  @r{             28-bit binary values}
 752
 753 (lsh 5 2)          ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
 754      @result{} 20         ;      =  @r{0000  0000 0000  0000 0000  0001 0100}
 755 @end group
 756 @group
 757 (ash 5 2)
 758      @result{} 20
 759 (lsh -5 2)         ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
 760      @result{} -20        ;      =  @r{1111  1111 1111  1111 1111  1110 1100}
 761 (ash -5 2)
 762      @result{} -20
 763 @end group
 764 @group
 765 (lsh 5 -2)         ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
 766      @result{} 1          ;      =  @r{0000  0000 0000  0000 0000  0000 0001}
 767 @end group
 768 @group
 769 (ash 5 -2)
 770      @result{} 1
 771 @end group
 772 @group
 773 (lsh -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
 774      @result{} 4194302    ;      =  @r{0011  1111 1111  1111 1111  1111 1110}
 775 @end group
 776 @group
 777 (ash -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
 778      @result{} -2         ;      =  @r{1111  1111 1111  1111 1111  1111 1110}
 779 @end group
 780 @end smallexample
 781 @end defun
 782
 783 @defun logand &rest ints-or-markers
 784 @cindex logical and
 785 @cindex bitwise and
 786 This function returns the ``logical and'' of the arguments: the
 787 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
 788 set in all the arguments.  (``Set'' means that the value of the bit is 1
 789 rather than 0.)
 790
 791 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
 792 12 is 12: 1101 combined with 1100 produces 1100.
 793 In both the binary numbers, the leftmost two bits are set (i.e., they
 794 are 1's), so the leftmost two bits of the returned value are set.
 795 However, for the rightmost two bits, each is zero in at least one of
 796 the arguments, so the rightmost two bits of the returned value are 0's.
 797
 798 @noindent
 799 Therefore,
 800
 801 @example
 802 @group
 803 (logand 13 12)
 804      @result{} 12
 805 @end group
 806 @end example
 807
 808 If @code{logand} is not passed any argument, it returns a value of
 809 @minus{}1.  This number is an identity element for @code{logand}
 810 because its binary representation consists entirely of ones.  If
 811 @code{logand} is passed just one argument, it returns that argument.
 812
 813 @smallexample
 814 @group
 815                    ; @r{               28-bit binary values}
 816
 817 (logand 14 13)     ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
 818                    ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
 819      @result{} 12         ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
 820 @end group
 821
 822 @group
 823 (logand 14 13 4)   ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
 824                    ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
 825                    ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
 826      @result{} 4          ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
 827 @end group
 828
 829 @group
 830 (logand)
 831      @result{} -1         ; -1  =  @r{1111  1111 1111  1111 1111  1111 1111}
 832 @end group
 833 @end smallexample
 834 @end defun
 835
 836 @defun logior &rest ints-or-markers
 837 @cindex logical inclusive or
 838 @cindex bitwise or
 839 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
 840 is set in the result if, and only if, the @var{n}th bit is set in at least
 841 one of the arguments.  If there are no arguments, the result is zero,
 842 which is an identity element for this operation.  If @code{logior} is
 843 passed just one argument, it returns that argument.
 844
 845 @smallexample
 846 @group
 847                    ; @r{              28-bit binary values}
 848
 849 (logior 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
 850                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
 851      @result{} 13         ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
 852 @end group
 853
 854 @group
 855 (logior 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
 856                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
 857                    ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
 858      @result{} 15         ; 15  =  @r{0000  0000 0000  0000 0000  0000 1111}
 859 @end group
 860 @end smallexample
 861 @end defun
 862
 863 @defun logxor &rest ints-or-markers
 864 @cindex bitwise exclusive or
 865 @cindex logical exclusive or
 866 This function returns the ``exclusive or'' of its arguments: the
 867 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
 868 set in an odd number of the arguments.  If there are no arguments, the
 869 result is 0, which is an identity element for this operation.  If
 870 @code{logxor} is passed just one argument, it returns that argument.
 871
 872 @smallexample
 873 @group
 874                    ; @r{              28-bit binary values}
 875
 876 (logxor 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
 877                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
 878      @result{} 9          ;  9  =  @r{0000  0000 0000  0000 0000  0000 1001}
 879 @end group
 880
 881 @group
 882 (logxor 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
 883                    ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
 884                    ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
 885      @result{} 14         ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
 886 @end group
 887 @end smallexample
 888 @end defun
 889
 890 @defun lognot integer
 891 @cindex logical not
 892 @cindex bitwise not
 893 This function returns the logical complement of its argument: the @var{n}th
 894 bit is one in the result if, and only if, the @var{n}th bit is zero in
 895 @var{integer}, and vice-versa.
 896
 897 @example
 898 (lognot 5)
 899      @result{} -6
 900 ;;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
 901 ;; @r{becomes}
 902 ;; -6  =  @r{1111  1111 1111  1111 1111  1111 1010}
 903 @end example
 904 @end defun
 905
 906 @node Transcendental Functions
 907 @section Transcendental Functions
 908 @cindex transcendental functions
 909 @cindex mathematical functions
 910
 911 These mathematical functions are available if floating point is
 912 supported.  They allow integers as well as floating point numbers
 913 as arguments.
 914
 915 @defun sin arg
 916 @defunx cos arg
 917 @defunx tan arg
 918 These are the ordinary trigonometric functions, with argument measured
 919 in radians.
 920 @end defun
 921
 922 @defun asin arg
 923 The value of @code{(asin @var{arg})} is a number between @minus{}pi/2
 924 and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
 925 is out of range (outside [-1, 1]), then the result is a NaN.
 926 @end defun
 927
 928 @defun acos arg
 929 The value of @code{(acos @var{arg})} is a number between 0 and pi
 930 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
 931 is out of range (outside [-1, 1]), then the result is a NaN.
 932 @end defun
 933
 934 @defun atan arg
 935 The value of @code{(atan @var{arg})} is a number between @minus{}pi/2
 936 and pi/2 (exclusive) whose tangent is @var{arg}.
 937 @end defun
 938
 939 @defun exp arg
 940 This is the exponential function; it returns @i{e} to the power
 941 @var{arg}.  @i{e} is a fundamental mathematical constant also called the
 942 base of natural logarithms.
 943 @end defun
 944
 945 @defun log arg &optional base
 946 This function returns the logarithm of @var{arg}, with base @var{base}.
 947 If you don't specify @var{base}, the base @var{e} is used.  If @var{arg}
 948 is negative, the result is a NaN.
 949 @end defun
 950
 951 @ignore
 952 @defun expm1 arg
 953 This function returns @code{(1- (exp @var{arg}))}, but it is more
 954 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
 955 is close to 1.
 956 @end defun
 957
 958 @defun log1p arg
 959 This function returns @code{(log (1+ @var{arg}))}, but it is more
 960 accurate than that when @var{arg} is so small that adding 1 to it would
 961 lose accuracy.
 962 @end defun
 963 @end ignore
 964
 965 @defun log10 arg
 966 This function returns the logarithm of @var{arg}, with base 10.  If
 967 @var{arg} is negative, the result is a NaN.  @code{(log10 @var{x})}
 968 @equiv{} @code{(log @var{x} 10)}, at least approximately.
 969 @end defun
 970
 971 @defun expt x y
 972 This function returns @var{x} raised to power @var{y}.  If both
 973 arguments are integers and @var{y} is positive, the result is an
 974 integer; in this case, it is truncated to fit the range of possible
 975 integer values.
 976 @end defun
 977
 978 @defun sqrt arg
 979 This returns the square root of @var{arg}.  If @var{arg} is negative,
 980 the value is a NaN.
 981 @end defun
 982
 983 @node Random Numbers
 984 @section Random Numbers
 985 @cindex random numbers
 986
 987 A deterministic computer program cannot generate true random numbers.
 988 For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
 989 pseudo-random numbers is generated in a deterministic fashion.  The
 990 numbers are not truly random, but they have certain properties that
 991 mimic a random series.  For example, all possible values occur equally
 992 often in a pseudo-random series.
 993
 994 In Emacs, pseudo-random numbers are generated from a ``seed'' number.
 995 Starting from any given seed, the @code{random} function always
 996 generates the same sequence of numbers.  Emacs always starts with the
 997 same seed value, so the sequence of values of @code{random} is actually
 998 the same in each Emacs run!  For example, in one operating system, the
 999 first call to @code{(random)} after you start Emacs always returns
1000 -1457731, and the second one always returns -7692030.  This
1001 repeatability is helpful for debugging.
1002
1003 If you want truly unpredictable random numbers, execute @code{(random
1004 t)}.  This chooses a new seed based on the current time of day and on
1005 Emacs's process @sc{id} number.
1006
1007 @defun random &optional limit
1008 This function returns a pseudo-random integer.  Repeated calls return a
1009 series of pseudo-random integers.
1010
1011 If @var{limit} is @code{nil}, then the value may in principle be any
1012 integer.  If @var{limit} is a positive integer, the value is chosen to
1013 be nonnegative and less than @var{limit} (only in Emacs 19).
1014
1015 If @var{limit} is @code{t}, it means to choose a new seed based on the
1016 current time of day and on Emacs's process @sc{id} number.
1017 @c "Emacs'" is incorrect usage!
1018
1019 On some machines, any integer representable in Lisp may be the result
1020 of @code{random}.  On other machines, the result can never be larger
1021 than a certain maximum or less than a certain (negative) minimum.
1022 @end defun