Mercurial > hg > xemacs-beta

comparison man/lispref/numbers.texi @ 428:3ecd8885ac67 r21-2-22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-22
author cvs
date Mon, 13 Aug 2007 11:28:15 +0200
parents
children 576fb035e263
comparison
equal deleted inserted replaced
427:0a0253eac470 428:3ecd8885ac67
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-or-marker
414 This function returns @var{number-or-marker} plus 1.
415 For example,
416
417 @example
418 (setq foo 4)
419 @result{} 4
420 (1+ foo)
421 @result{} 5
422 @end example
423
424 This function is not analogous to the C operator @code{++}---it does not
425 increment a variable. It just computes a sum. Thus, if we continue,
426
427 @example
428 foo
429 @result{} 4
430 @end example
431
432 If you want to increment the variable, you must use @code{setq},
433 like this:
434
435 @example
436 (setq foo (1+ foo))
437 @result{} 5
438 @end example
439
440 Now that the @code{cl} package is always available from lisp code, a
441 more convenient and natural way to increment a variable is
442 @w{@code{(incf foo)}}.
443 @end defun
444
445 @defun 1- number-or-marker
446 This function returns @var{number-or-marker} minus 1.
447 @end defun
448
449 @defun abs number
450 This returns the absolute value of @var{number}.
451 @end defun
452
453 @defun + &rest numbers-or-markers
454 This function adds its arguments together. When given no arguments,
455 @code{+} returns 0.
456
457 @example
458 (+)
459 @result{} 0
460 (+ 1)
461 @result{} 1
462 (+ 1 2 3 4)
463 @result{} 10
464 @end example
465 @end defun
466
467 @defun - &optional number-or-marker &rest other-numbers-or-markers
468 The @code{-} function serves two purposes: negation and subtraction.
469 When @code{-} has a single argument, the value is the negative of the
470 argument. When there are multiple arguments, @code{-} subtracts each of
471 the @var{other-numbers-or-markers} from @var{number-or-marker},
472 cumulatively. If there are no arguments, the result is 0.
473
474 @example
475 (- 10 1 2 3 4)
476 @result{} 0
477 (- 10)
478 @result{} -10
479 (-)
480 @result{} 0
481 @end example
482 @end defun
483
484 @defun * &rest numbers-or-markers
485 This function multiplies its arguments together, and returns the
486 product. When given no arguments, @code{*} returns 1.
487
488 @example
489 (*)
490 @result{} 1
491 (* 1)
492 @result{} 1
493 (* 1 2 3 4)
494 @result{} 24
495 @end example
496 @end defun
497
498 @defun / dividend divisor &rest divisors
499 This function divides @var{dividend} by @var{divisor} and returns the
500 quotient. If there are additional arguments @var{divisors}, then it
501 divides @var{dividend} by each divisor in turn. Each argument may be a
502 number or a marker.
503
504 If all the arguments are integers, then the result is an integer too.
505 This means the result has to be rounded. On most machines, the result
506 is rounded towards zero after each division, but some machines may round
507 differently with negative arguments. This is because the Lisp function
508 @code{/} is implemented using the C division operator, which also
509 permits machine-dependent rounding. As a practical matter, all known
510 machines round in the standard fashion.
511
512 @cindex @code{arith-error} in division
513 If you divide by 0, an @code{arith-error} error is signaled.
514 (@xref{Errors}.)
515
516 @example
517 @group
518 (/ 6 2)
519 @result{} 3
520 @end group
521 (/ 5 2)
522 @result{} 2
523 (/ 25 3 2)
524 @result{} 4
525 (/ -17 6)
526 @result{} -2
527 @end example
528
529 The result of @code{(/ -17 6)} could in principle be -3 on some
530 machines.
531 @end defun
532
533 @defun % dividend divisor
534 @cindex remainder
535 This function returns the integer remainder after division of @var{dividend}
536 by @var{divisor}. The arguments must be integers or markers.
537
538 For negative arguments, the remainder is in principle machine-dependent
539 since the quotient is; but in practice, all known machines behave alike.
540
541 An @code{arith-error} results if @var{divisor} is 0.
542
543 @example
544 (% 9 4)
545 @result{} 1
546 (% -9 4)
547 @result{} -1
548 (% 9 -4)
549 @result{} 1
550 (% -9 -4)
551 @result{} -1
552 @end example
553
554 For any two integers @var{dividend} and @var{divisor},
555
556 @example
557 @group
558 (+ (% @var{dividend} @var{divisor})
559 (* (/ @var{dividend} @var{divisor}) @var{divisor}))
560 @end group
561 @end example
562
563 @noindent
564 always equals @var{dividend}.
565 @end defun
566
567 @defun mod dividend divisor
568 @cindex modulus
569 This function returns the value of @var{dividend} modulo @var{divisor};
570 in other words, the remainder after division of @var{dividend}
571 by @var{divisor}, but with the same sign as @var{divisor}.
572 The arguments must be numbers or markers.
573
574 Unlike @code{%}, @code{mod} returns a well-defined result for negative
575 arguments. It also permits floating point arguments; it rounds the
576 quotient downward (towards minus infinity) to an integer, and uses that
577 quotient to compute the remainder.
578
579 An @code{arith-error} results if @var{divisor} is 0.
580
581 @example
582 @group
583 (mod 9 4)
584 @result{} 1
585 @end group
586 @group
587 (mod -9 4)
588 @result{} 3
589 @end group
590 @group
591 (mod 9 -4)
592 @result{} -3
593 @end group
594 @group
595 (mod -9 -4)
596 @result{} -1
597 @end group
598 @group
599 (mod 5.5 2.5)
600 @result{} .5
601 @end group
602 @end example
603
604 For any two numbers @var{dividend} and @var{divisor},
605
606 @example
607 @group
608 (+ (mod @var{dividend} @var{divisor})
609 (* (floor @var{dividend} @var{divisor}) @var{divisor}))
610 @end group
611 @end example
612
613 @noindent
614 always equals @var{dividend}, subject to rounding error if either
615 argument is floating point. For @code{floor}, see @ref{Numeric
616 Conversions}.
617 @end defun
618
619 @node Rounding Operations
620 @section Rounding Operations
621 @cindex rounding without conversion
622
623 The functions @code{ffloor}, @code{fceiling}, @code{fround} and
624 @code{ftruncate} take a floating point argument and return a floating
625 point result whose value is a nearby integer. @code{ffloor} returns the
626 nearest integer below; @code{fceiling}, the nearest integer above;
627 @code{ftruncate}, the nearest integer in the direction towards zero;
628 @code{fround}, the nearest integer.
629
630 @defun ffloor float
631 This function rounds @var{float} to the next lower integral value, and
632 returns that value as a floating point number.
633 @end defun
634
635 @defun fceiling float
636 This function rounds @var{float} to the next higher integral value, and
637 returns that value as a floating point number.
638 @end defun
639
640 @defun ftruncate float
641 This function rounds @var{float} towards zero to an integral value, and
642 returns that value as a floating point number.
643 @end defun
644
645 @defun fround float
646 This function rounds @var{float} to the nearest integral value,
647 and returns that value as a floating point number.
648 @end defun
649
650 @node Bitwise Operations
651 @section Bitwise Operations on Integers
652
653 In a computer, an integer is represented as a binary number, a
654 sequence of @dfn{bits} (digits which are either zero or one). A bitwise
655 operation acts on the individual bits of such a sequence. For example,
656 @dfn{shifting} moves the whole sequence left or right one or more places,
657 reproducing the same pattern ``moved over''.
658
659 The bitwise operations in XEmacs Lisp apply only to integers.
660
661 @defun lsh integer1 count
662 @cindex logical shift
663 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
664 bits in @var{integer1} to the left @var{count} places, or to the right
665 if @var{count} is negative, bringing zeros into the vacated bits. If
666 @var{count} is negative, @code{lsh} shifts zeros into the leftmost
667 (most-significant) bit, producing a positive result even if
668 @var{integer1} is negative. Contrast this with @code{ash}, below.
669
670 Here are two examples of @code{lsh}, shifting a pattern of bits one
671 place to the left. We show only the low-order eight bits of the binary
672 pattern; the rest are all zero.
673
674 @example
675 @group
676 (lsh 5 1)
677 @result{} 10
678 ;; @r{Decimal 5 becomes decimal 10.}
679 00000101 @result{} 00001010
680
681 (lsh 7 1)
682 @result{} 14
683 ;; @r{Decimal 7 becomes decimal 14.}
684 00000111 @result{} 00001110
685 @end group
686 @end example
687
688 @noindent
689 As the examples illustrate, shifting the pattern of bits one place to
690 the left produces a number that is twice the value of the previous
691 number.
692
693 Shifting a pattern of bits two places to the left produces results
694 like this (with 8-bit binary numbers):
695
696 @example
697 @group
698 (lsh 3 2)
699 @result{} 12
700 ;; @r{Decimal 3 becomes decimal 12.}
701 00000011 @result{} 00001100
702 @end group
703 @end example
704
705 On the other hand, shifting one place to the right looks like this:
706
707 @example
708 @group
709 (lsh 6 -1)
710 @result{} 3
711 ;; @r{Decimal 6 becomes decimal 3.}
712 00000110 @result{} 00000011
713 @end group
714
715 @group
716 (lsh 5 -1)
717 @result{} 2
718 ;; @r{Decimal 5 becomes decimal 2.}
719 00000101 @result{} 00000010
720 @end group
721 @end example
722
723 @noindent
724 As the example illustrates, shifting one place to the right divides the
725 value of a positive integer by two, rounding downward.
726
727 The function @code{lsh}, like all XEmacs Lisp arithmetic functions, does
728 not check for overflow, so shifting left can discard significant bits
729 and change the sign of the number. For example, left shifting
730 134,217,727 produces @minus{}2 on a 28-bit machine:
731
732 @example
733 (lsh 134217727 1) ; @r{left shift}
734 @result{} -2
735 @end example
736
737 In binary, in the 28-bit implementation, the argument looks like this:
738
739 @example
740 @group
741 ;; @r{Decimal 134,217,727}
742 0111 1111 1111 1111 1111 1111 1111
743 @end group
744 @end example
745
746 @noindent
747 which becomes the following when left shifted:
748
749 @example
750 @group
751 ;; @r{Decimal @minus{}2}
752 1111 1111 1111 1111 1111 1111 1110
753 @end group
754 @end example
755 @end defun
756
757 @defun ash integer1 count
758 @cindex arithmetic shift
759 @code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
760 to the left @var{count} places, or to the right if @var{count}
761 is negative.
762
763 @code{ash} gives the same results as @code{lsh} except when
764 @var{integer1} and @var{count} are both negative. In that case,
765 @code{ash} puts ones in the empty bit positions on the left, while
766 @code{lsh} puts zeros in those bit positions.
767
768 Thus, with @code{ash}, shifting the pattern of bits one place to the right
769 looks like this:
770
771 @example
772 @group
773 (ash -6 -1) @result{} -3
774 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
775 1111 1111 1111 1111 1111 1111 1010
776 @result{}
777 1111 1111 1111 1111 1111 1111 1101
778 @end group
779 @end example
780
781 In contrast, shifting the pattern of bits one place to the right with
782 @code{lsh} looks like this:
783
784 @example
785 @group
786 (lsh -6 -1) @result{} 134217725
787 ;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
788 1111 1111 1111 1111 1111 1111 1010
789 @result{}
790 0111 1111 1111 1111 1111 1111 1101
791 @end group
792 @end example
793
794 Here are other examples:
795
796 @c !!! Check if lined up in smallbook format! XDVI shows problem
797 @c with smallbook but not with regular book! --rjc 16mar92
798 @smallexample
799 @group
800 ; @r{ 28-bit binary values}
801
802 (lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
803 @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100}
804 @end group
805 @group
806 (ash 5 2)
807 @result{} 20
808 (lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
809 @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100}
810 (ash -5 2)
811 @result{} -20
812 @end group
813 @group
814 (lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
815 @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001}
816 @end group
817 @group
818 (ash 5 -2)
819 @result{} 1
820 @end group
821 @group
822 (lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
823 @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110}
824 @end group
825 @group
826 (ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
827 @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110}
828 @end group
829 @end smallexample
830 @end defun
831
832 @defun logand &rest ints-or-markers
833 @cindex logical and
834 @cindex bitwise and
835 This function returns the ``logical and'' of the arguments: the
836 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
837 set in all the arguments. (``Set'' means that the value of the bit is 1
838 rather than 0.)
839
840 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
841 12 is 12: 1101 combined with 1100 produces 1100.
842 In both the binary numbers, the leftmost two bits are set (i.e., they
843 are 1's), so the leftmost two bits of the returned value are set.
844 However, for the rightmost two bits, each is zero in at least one of
845 the arguments, so the rightmost two bits of the returned value are 0's.
846
847 @noindent
848 Therefore,
849
850 @example
851 @group
852 (logand 13 12)
853 @result{} 12
854 @end group
855 @end example
856
857 If @code{logand} is not passed any argument, it returns a value of
858 @minus{}1. This number is an identity element for @code{logand}
859 because its binary representation consists entirely of ones. If
860 @code{logand} is passed just one argument, it returns that argument.
861
862 @smallexample
863 @group
864 ; @r{ 28-bit binary values}
865
866 (logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
867 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
868 @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
869 @end group
870
871 @group
872 (logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
873 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
874 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
875 @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
876 @end group
877
878 @group
879 (logand)
880 @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111}
881 @end group
882 @end smallexample
883 @end defun
884
885 @defun logior &rest ints-or-markers
886 @cindex logical inclusive or
887 @cindex bitwise or
888 This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
889 is set in the result if, and only if, the @var{n}th bit is set in at least
890 one of the arguments. If there are no arguments, the result is zero,
891 which is an identity element for this operation. If @code{logior} is
892 passed just one argument, it returns that argument.
893
894 @smallexample
895 @group
896 ; @r{ 28-bit binary values}
897
898 (logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
899 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
900 @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
901 @end group
902
903 @group
904 (logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
905 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
906 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
907 @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111}
908 @end group
909 @end smallexample
910 @end defun
911
912 @defun logxor &rest ints-or-markers
913 @cindex bitwise exclusive or
914 @cindex logical exclusive or
915 This function returns the ``exclusive or'' of its arguments: the
916 @var{n}th bit is set in the result if, and only if, the @var{n}th bit is
917 set in an odd number of the arguments. If there are no arguments, the
918 result is 0, which is an identity element for this operation. If
919 @code{logxor} is passed just one argument, it returns that argument.
920
921 @smallexample
922 @group
923 ; @r{ 28-bit binary values}
924
925 (logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
926 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
927 @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001}
928 @end group
929
930 @group
931 (logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
932 ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
933 ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
934 @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
935 @end group
936 @end smallexample
937 @end defun
938
939 @defun lognot integer
940 @cindex logical not
941 @cindex bitwise not
942 This function returns the logical complement of its argument: the @var{n}th
943 bit is one in the result if, and only if, the @var{n}th bit is zero in
944 @var{integer}, and vice-versa.
945
946 @example
947 (lognot 5)
948 @result{} -6
949 ;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
950 ;; @r{becomes}
951 ;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
952 @end example
953 @end defun
954
955 @node Math Functions
956 @section Standard Mathematical Functions
957 @cindex transcendental functions
958 @cindex mathematical functions
959
960 These mathematical functions are available if floating point is
961 supported (which is the normal state of affairs). They allow integers
962 as well as floating point numbers as arguments.
963
964 @defun sin arg
965 @defunx cos arg
966 @defunx tan arg
967 These are the ordinary trigonometric functions, with argument measured
968 in radians.
969 @end defun
970
971 @defun asin arg
972 The value of @code{(asin @var{arg})} is a number between @minus{}pi/2
973 and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
974 is out of range (outside [-1, 1]), then the result is a NaN.
975 @end defun
976
977 @defun acos arg
978 The value of @code{(acos @var{arg})} is a number between 0 and pi
979 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
980 is out of range (outside [-1, 1]), then the result is a NaN.
981 @end defun
982
983 @defun atan arg
984 The value of @code{(atan @var{arg})} is a number between @minus{}pi/2
985 and pi/2 (exclusive) whose tangent is @var{arg}.
986 @end defun
987
988 @defun sinh arg
989 @defunx cosh arg
990 @defunx tanh arg
991 These are the ordinary hyperbolic trigonometric functions.
992 @end defun
993
994 @defun asinh arg
995 @defunx acosh arg
996 @defunx atanh arg
997 These are the inverse hyperbolic trigonometric functions.
998 @end defun
999
1000 @defun exp arg
1001 This is the exponential function; it returns @i{e} to the power
1002 @var{arg}. @i{e} is a fundamental mathematical constant also called the
1003 base of natural logarithms.
1004 @end defun
1005
1006 @defun log arg &optional base
1007 This function returns the logarithm of @var{arg}, with base @var{base}.
1008 If you don't specify @var{base}, the base @var{e} is used. If @var{arg}
1009 is negative, the result is a NaN.
1010 @end defun
1011
1012 @ignore
1013 @defun expm1 arg
1014 This function returns @code{(1- (exp @var{arg}))}, but it is more
1015 accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
1016 is close to 1.
1017 @end defun
1018
1019 @defun log1p arg
1020 This function returns @code{(log (1+ @var{arg}))}, but it is more
1021 accurate than that when @var{arg} is so small that adding 1 to it would
1022 lose accuracy.
1023 @end defun
1024 @end ignore
1025
1026 @defun log10 arg
1027 This function returns the logarithm of @var{arg}, with base 10. If
1028 @var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
1029 @equiv{} @code{(log @var{x} 10)}, at least approximately.
1030 @end defun
1031
1032 @defun expt x y
1033 This function returns @var{x} raised to power @var{y}. If both
1034 arguments are integers and @var{y} is positive, the result is an
1035 integer; in this case, it is truncated to fit the range of possible
1036 integer values.
1037 @end defun
1038
1039 @defun sqrt arg
1040 This returns the square root of @var{arg}. If @var{arg} is negative,
1041 the value is a NaN.
1042 @end defun
1043
1044 @defun cube-root arg
1045 This returns the cube root of @var{arg}.
1046 @end defun
1047
1048 @node Random Numbers
1049 @section Random Numbers
1050 @cindex random numbers
1051
1052 A deterministic computer program cannot generate true random numbers.
1053 For most purposes, @dfn{pseudo-random numbers} suffice. A series of
1054 pseudo-random numbers is generated in a deterministic fashion. The
1055 numbers are not truly random, but they have certain properties that
1056 mimic a random series. For example, all possible values occur equally
1057 often in a pseudo-random series.
1058
1059 In XEmacs, pseudo-random numbers are generated from a ``seed'' number.
1060 Starting from any given seed, the @code{random} function always
1061 generates the same sequence of numbers. XEmacs always starts with the
1062 same seed value, so the sequence of values of @code{random} is actually
1063 the same in each XEmacs run! For example, in one operating system, the
1064 first call to @code{(random)} after you start XEmacs always returns
1065 -1457731, and the second one always returns -7692030. This
1066 repeatability is helpful for debugging.
1067
1068 If you want truly unpredictable random numbers, execute @code{(random
1069 t)}. This chooses a new seed based on the current time of day and on
1070 XEmacs's process @sc{id} number.
1071
1072 @defun random &optional limit
1073 This function returns a pseudo-random integer. Repeated calls return a
1074 series of pseudo-random integers.
1075
1076 If @var{limit} is a positive integer, the value is chosen to be
1077 nonnegative and less than @var{limit}.
1078
1079 If @var{limit} is @code{t}, it means to choose a new seed based on the
1080 current time of day and on XEmacs's process @sc{id} number.
1081 @c "XEmacs'" is incorrect usage!
1082
1083 On some machines, any integer representable in Lisp may be the result
1084 of @code{random}. On other machines, the result can never be larger
1085 than a certain maximum or less than a certain (negative) minimum.
1086 @end defun