Mercurial > hg > xemacs-beta

comparison man/lispref/numbers.texi @ 0:376386a54a3c r19-14

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