*** empty log message ***

[bpt/emacs.git] / lispref / numbers.texi

diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index e2cfc93..3a4f4ae 100644 (file)
--- a/lispref/numbers.texi
+++ b/lispref/numbers.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/numbers
@@ -36,22 +36,22 @@ exact; they have a fixed, limited amount of precision.
 @section Integer Basics
 
   The range of values for an integer depends on the machine.  The
-minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
+minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
 @ifnottex
--2**27
+-2**28
 @end ifnottex
 @tex
-@math{-2^{27}}
+@math{-2^{28}}
 @end tex
 to
 @ifnottex
-2**27 - 1),
+2**28 - 1),
 @end ifnottex
 @tex
-@math{2^{27}-1}),
+@math{2^{28}-1}),
 @end tex
 but some machines may provide a wider range.  Many examples in this
-chapter assume an integer has 28 bits.
+chapter assume an integer has 29 bits.
 @cindex overflow
 
   The Lisp reader reads an integer as a sequence of digits with optional
@@ -62,7 +62,7 @@ initial sign and optional final period.
  1.              ; @r{The integer 1.}
 +1               ; @r{Also the integer 1.}
 -1               ; @r{The integer @minus{}1.}
- 268435457       ; @r{Also the integer 1, due to overflow.}
+ 536870913       ; @r{Also the integer 1, due to overflow.}
  0               ; @r{The integer 0.}
 -0               ; @r{The integer 0.}
 @end example
@@ -70,6 +70,9 @@ initial sign and optional final period.
 @cindex integers in specific radix
 @cindex radix for reading an integer
 @cindex base for reading an integer
+@cindex hex numbers
+@cindex octal numbers
+@cindex reading numbers in hex, octal, and binary
   In addition, the Lisp reader recognizes a syntax for integers in
 bases other than 10: @samp{#B@var{integer}} reads @var{integer} in
 binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal
@@ -83,10 +86,10 @@ inclusively).  Case is not significant for the letter after @samp{#}
 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
 view the numbers in their binary form.
 
-  In 28-bit binary, the decimal integer 5 looks like this:
+  In 29-bit binary, the decimal integer 5 looks like this:
 
 @example
-0000  0000 0000  0000 0000  0000 0101
+0 0000  0000 0000  0000 0000  0000 0101
 @end example
 
 @noindent
@@ -96,12 +99,12 @@ between groups of 8 bits, to make the binary integer easier to read.)
   The integer @minus{}1 looks like this:
 
 @example
-1111  1111 1111  1111 1111  1111 1111
+1 1111  1111 1111  1111 1111  1111 1111
 @end example
 
 @noindent
 @cindex two's complement
-@minus{}1 is represented as 28 ones.  (This is called @dfn{two's
+@minus{}1 is represented as 29 ones.  (This is called @dfn{two's
 complement} notation.)
 
   The negative integer, @minus{}5, is creating by subtracting 4 from
@@ -109,24 +112,24 @@ complement} notation.)
 @minus{}5 looks like this:
 
 @example
-1111  1111 1111  1111 1111  1111 1011
+1 1111  1111 1111  1111 1111  1111 1011
 @end example
 
-  In this implementation, the largest 28-bit binary integer value is
-134,217,727 in decimal.  In binary, it looks like this:
+  In this implementation, the largest 29-bit binary integer value is
+268,435,455 in decimal.  In binary, it looks like this:
 
 @example
-0111  1111 1111  1111 1111  1111 1111
+0 1111  1111 1111  1111 1111  1111 1111
 @end example
 
   Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 134,217,727, the value is the
-negative integer @minus{}134,217,728:
+outside their range, when you add 1 to 268,435,455, the value is the
+negative integer @minus{}268,435,456:
 
 @example
-(+ 1 134217727)
-     @result{} -134217728
-     @result{} 1000  0000 0000  0000 0000  0000 0000
+(+ 1 268435455)
+     @result{} -268435456
+     @result{} 1 0000  0000 0000  0000 0000  0000 0000
 @end example
 
   Many of the functions described in this chapter accept markers for
@@ -160,16 +163,16 @@ example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
 value is 1500.  They are all equivalent.  You can also use a minus sign
 to write negative floating point numbers, as in @samp{-1.0}.
 
-@cindex IEEE floating point
+@cindex @acronym{IEEE} floating point
 @cindex positive infinity
 @cindex negative infinity
 @cindex infinity
 @cindex NaN
-   Most modern computers support the IEEE floating point standard, which
-provides for positive infinity and negative infinity as floating point
+  Most modern computers support the @acronym{IEEE} floating point standard,
+which provides for positive infinity and negative infinity as floating point
 values.  It also provides for a class of values called NaN or
 ``not-a-number''; numerical functions return such values in cases where
-there is no correct answer.  For example, @code{(sqrt -1.0)} returns a
+there is no correct answer.  For example, @code{(/ 0.0 0.0)} returns a
 NaN.  For practical purposes, there's no significant difference between
 different NaN values in Emacs Lisp, and there's no rule for precisely
 which NaN value should be used in a particular case, so Emacs Lisp
@@ -186,8 +189,8 @@ these special floating point values:
 @end table
 
   In addition, the value @code{-0.0} is distinguishable from ordinary
-zero in IEEE floating point (although @code{equal} and @code{=} consider
-them equal values).
+zero in @acronym{IEEE} floating point (although @code{equal} and
+@code{=} consider them equal values).
 
   You can use @code{logb} to extract the binary exponent of a floating
 point number (or estimate the logarithm of an integer):
@@ -376,10 +379,16 @@ it unchanged.
 @end defun
 
 There are four functions to convert floating point numbers to integers;
-they differ in how they round.  These functions accept integer arguments
-also, and return such arguments unchanged.
-
-@defun truncate number
+they differ in how they round.  All accept an argument @var{number}
+and an optional argument @var{divisor}.  Both arguments may be
+integers or floating point numbers.  @var{divisor} may also be
+@code{nil}.  If @var{divisor} is @code{nil} or omitted, these
+functions convert @var{number} to an integer, or return it unchanged
+if it already is an integer.  If @var{divisor} is non-@code{nil}, they
+divide @var{number} by @var{divisor} and convert the result to an
+integer.  An @code{arith-error} results if @var{divisor} is 0.
+
+@defun truncate number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards
 zero.
 
@@ -399,10 +408,8 @@ zero.
 This returns @var{number}, converted to an integer by rounding downward
 (towards negative infinity).
 
-If @var{divisor} is specified, @code{floor} divides @var{number} by
-@var{divisor} and then converts to an integer; this uses the kind of
-division operation that corresponds to @code{mod}, rounding downward.
-An @code{arith-error} results if @var{divisor} is 0.
+If @var{divisor} is specified, this uses the kind of division
+operation that corresponds to @code{mod}, rounding downward.
 
 @example
 (floor 1.2)
@@ -418,7 +425,7 @@ An @code{arith-error} results if @var{divisor} is 0.
 @end example
 @end defun
 
-@defun ceiling number
+@defun ceiling number &optional divisor
 This returns @var{number}, converted to an integer by rounding upward
 (towards positive infinity).
 
@@ -434,7 +441,7 @@ This returns @var{number}, converted to an integer by rounding upward
 @end example
 @end defun
 
-@defun round number
+@defun round number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards the
 nearest integer.  Rounding a value equidistant between two integers
 may choose the integer closer to zero, or it may prefer an even integer,
@@ -465,8 +472,8 @@ commonly used.
 if any argument is floating.
 
   It is important to note that in Emacs Lisp, arithmetic functions
-do not check for overflow.  Thus @code{(1+ 134217727)} may evaluate to
-@minus{}134217728, depending on your hardware.
+do not check for overflow.  Thus @code{(1+ 268435455)} may evaluate to
+@minus{}268435456, depending on your hardware.
 
 @defun 1+ number-or-marker
 This function returns @var{number-or-marker} plus 1.
@@ -562,7 +569,7 @@ machines round in the standard fashion.
 @cindex @code{arith-error} in division
 If you divide an integer by 0, an @code{arith-error} error is signaled.
 (@xref{Errors}.)  Floating point division by zero returns either
-infinity or a NaN if your machine supports IEEE floating point;
+infinity or a NaN if your machine supports @acronym{IEEE} floating point;
 otherwise, it signals an @code{arith-error} error.
 
 @example
@@ -785,19 +792,19 @@ value of a positive integer by two, rounding downward.
 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
 not check for overflow, so shifting left can discard significant bits
 and change the sign of the number.  For example, left shifting
-134,217,727 produces @minus{}2 on a 28-bit machine:
+268,435,455 produces @minus{}2 on a 29-bit machine:
 
 @example
-(lsh 134217727 1)          ; @r{left shift}
+(lsh 268435455 1)          ; @r{left shift}
      @result{} -2
 @end example
 
-In binary, in the 28-bit implementation, the argument looks like this:
+In binary, in the 29-bit implementation, the argument looks like this:
 
 @example
 @group
-;; @r{Decimal 134,217,727}
-0111  1111 1111  1111 1111  1111 1111
+;; @r{Decimal 268,435,455}
+0 1111  1111 1111  1111 1111  1111 1111
 @end group
 @end example
 
@@ -807,7 +814,7 @@ which becomes the following when left shifted:
 @example
 @group
 ;; @r{Decimal @minus{}2}
-1111  1111 1111  1111 1111  1111 1110
+1 1111  1111 1111  1111 1111  1111 1110
 @end group
 @end example
 @end defun
@@ -830,9 +837,9 @@ looks like this:
 @group
 (ash -6 -1) @result{} -3
 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
-1111  1111 1111  1111 1111  1111 1010
+1 1111  1111 1111  1111 1111  1111 1010
      @result{}
-1111  1111 1111  1111 1111  1111 1101
+1 1111  1111 1111  1111 1111  1111 1101
 @end group
 @end example
 
@@ -841,11 +848,11 @@ In contrast, shifting the pattern of bits one place to the right with
 
 @example
 @group
-(lsh -6 -1) @result{} 134217725
-;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
-1111  1111 1111  1111 1111  1111 1010
+(lsh -6 -1) @result{} 268435453
+;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
+1 1111  1111 1111  1111 1111  1111 1010
      @result{}
-0111  1111 1111  1111 1111  1111 1101
+0 1111  1111 1111  1111 1111  1111 1101
 @end group
 @end example
 
@@ -855,34 +862,34 @@ Here are other examples:
 @c     with smallbook but not with regular book! --rjc 16mar92
 @smallexample
 @group
-                   ;  @r{             28-bit binary values}
+                   ;  @r{             29-bit binary values}
 
-(lsh 5 2)          ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 20         ;      =  @r{0000  0000 0000  0000 0000  0001 0100}
+(lsh 5 2)          ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 20         ;      =  @r{0 0000  0000 0000  0000 0000  0001 0100}
 @end group
 @group
 (ash 5 2)
      @result{} 20
-(lsh -5 2)         ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
-     @result{} -20        ;      =  @r{1111  1111 1111  1111 1111  1110 1100}
+(lsh -5 2)         ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} -20        ;      =  @r{1 1111  1111 1111  1111 1111  1110 1100}
 (ash -5 2)
      @result{} -20
 @end group
 @group
-(lsh 5 -2)         ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 1          ;      =  @r{0000  0000 0000  0000 0000  0000 0001}
+(lsh 5 -2)         ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 1          ;      =  @r{0 0000  0000 0000  0000 0000  0000 0001}
 @end group
 @group
 (ash 5 -2)
      @result{} 1
 @end group
 @group
-(lsh -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
-     @result{} 4194302    ;      =  @r{0011  1111 1111  1111 1111  1111 1110}
+(lsh -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} 134217726  ;      =  @r{0 0111  1111 1111  1111 1111  1111 1110}
 @end group
 @group
-(ash -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
-     @result{} -2         ;      =  @r{1111  1111 1111  1111 1111  1111 1110}
+(ash -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} -2         ;      =  @r{1 1111  1111 1111  1111 1111  1111 1110}
 @end group
 @end smallexample
 @end defun
@@ -919,23 +926,23 @@ because its binary representation consists entirely of ones.  If
 
 @smallexample
 @group
-                   ; @r{               28-bit binary values}
+                   ; @r{               29-bit binary values}
 
-(logand 14 13)     ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
-                   ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
-     @result{} 12         ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
+(logand 14 13)     ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
+                   ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
+     @result{} 12         ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
 @end group
 
 @group
-(logand 14 13 4)   ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
-                   ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
-                   ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
-     @result{} 4          ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
+(logand 14 13 4)   ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
+                   ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
+                   ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
+     @result{} 4          ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
 @end group
 
 @group
 (logand)
-     @result{} -1         ; -1  =  @r{1111  1111 1111  1111 1111  1111 1111}
+     @result{} -1         ; -1  =  @r{1 1111  1111 1111  1111 1111  1111 1111}
 @end group
 @end smallexample
 @end defun
@@ -951,18 +958,18 @@ passed just one argument, it returns that argument.
 
 @smallexample
 @group
-                   ; @r{              28-bit binary values}
+                   ; @r{              29-bit binary values}
 
-(logior 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 13         ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
+(logior 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 13         ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
 @end group
 
 @group
-(logior 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-                   ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
-     @result{} 15         ; 15  =  @r{0000  0000 0000  0000 0000  0000 1111}
+(logior 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+                   ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
+     @result{} 15         ; 15  =  @r{0 0000  0000 0000  0000 0000  0000 1111}
 @end group
 @end smallexample
 @end defun
@@ -978,18 +985,18 @@ result is 0, which is an identity element for this operation.  If
 
 @smallexample
 @group
-                   ; @r{              28-bit binary values}
+                   ; @r{              29-bit binary values}
 
-(logxor 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 9          ;  9  =  @r{0000  0000 0000  0000 0000  0000 1001}
+(logxor 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 9          ;  9  =  @r{0 0000  0000 0000  0000 0000  0000 1001}
 @end group
 
 @group
-(logxor 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-                   ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
-     @result{} 14         ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
+(logxor 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+                   ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
+     @result{} 14         ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
 @end group
 @end smallexample
 @end defun
@@ -1004,9 +1011,9 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
 @example
 (lognot 5)
      @result{} -6
-;;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
+;;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
 ;; @r{becomes}
-;; -6  =  @r{1111  1111 1111  1111 1111  1111 1010}
+;; -6  =  @r{1 1111  1111 1111  1111 1111  1111 1010}
 @end example
 @end defun
 
@@ -1040,8 +1047,8 @@ pi/2
 @tex
 @math{\pi/2}
 @end tex
-(inclusive) whose sine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
+range (outside [-1, 1]), it signals a @code{domain-error} error.
 @end defun
 
 @defun acos arg
@@ -1052,8 +1059,8 @@ pi
 @tex
 @math{\pi}
 @end tex
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
+of range (outside [-1, 1]), it signals a @code{domain-error} error.
 @end defun
 
 @defun atan y &optional x
@@ -1105,8 +1112,8 @@ If you don't specify @var{base}, the base
 @ifnottex
 @i{e}
 @end ifnottex
-is used.  If @var{arg}
-is negative, the result is a NaN.
+is used.  If @var{arg} is negative, it signals a @code{domain-error}
+error.
 @end defun
 
 @ignore
@@ -1125,8 +1132,9 @@ lose accuracy.
 
 @defun log10 arg
 This function returns the logarithm of @var{arg}, with base 10.  If
-@var{arg} is negative, the result is a NaN.  @code{(log10 @var{x})}
-@equiv{} @code{(log @var{x} 10)}, at least approximately.
+@var{arg} is negative, it signals a @code{domain-error} error.
+@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
+approximately.
 @end defun
 
 @defun expt x y
@@ -1138,7 +1146,7 @@ integer values.
 
 @defun sqrt arg
 This returns the square root of @var{arg}.  If @var{arg} is negative,
-the value is a NaN.
+it signals a @code{domain-error} error.
 @end defun
 
 @node Random Numbers
@@ -1163,7 +1171,7 @@ repeatability is helpful for debugging.
 
 If you want random numbers that don't always come out the same, execute
 @code{(random t)}.  This chooses a new seed based on the current time of
-day and on Emacs's process @sc{id} number.
+day and on Emacs's process @acronym{ID} number.
 
 @defun random &optional limit
 This function returns a pseudo-random integer.  Repeated calls return a
@@ -1173,7 +1181,7 @@ If @var{limit} is a positive integer, the value is chosen to be
 nonnegative and less than @var{limit}.
 
 If @var{limit} is @code{t}, it means to choose a new seed based on the
-current time of day and on Emacs's process @sc{id} number.
+current time of day and on Emacs's process @acronym{ID} number.
 @c "Emacs'" is incorrect usage!
 
 On some machines, any integer representable in Lisp may be the result