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