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