man/lispref/numbers.texi

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