(nnmail-extra-headers): Add defvar.

[gnu-emacs] / lispref / numbers.texi

diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index 9689d5cedfec6d5a357c9751e0a5004c20dfd008..db28a2850a6afd6b145acee34d695a4cead1d8cd 100644 (file)
--- a/lispref/numbers.texi
+++ b/lispref/numbers.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @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   Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c   2004, 2005 Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/numbers
 @node Numbers, Strings and Characters, Lisp Data Types, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/numbers
 @node Numbers, Strings and Characters, Lisp Data Types, Top


@@ -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
 @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
 @ifnottex

--2**27
+-2**28

 @end ifnottex
 @end ifnottex

-@tex 
-@math{-2^{27}}
+@tex
+@math{-2^{28}}

 @end tex
 @end tex

-to 
+to

 @ifnottex
 @ifnottex

-2**27 - 1),
+2**28 - 1),

 @end ifnottex
 @end ifnottex

-@tex 
-@math{2^{27}-1}),
+@tex
+@math{2^{28}-1}),

 @end tex
 but some machines may provide a wider range.  Many examples in this
 @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
 @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.}
  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
  0               ; @r{The integer 0.}
 -0               ; @r{The integer 0.}
 @end example


@@ -70,23 +70,33 @@ initial sign and optional final period.
 @cindex integers in specific radix
 @cindex radix for reading an integer
 @cindex base for reading an integer
 @cindex integers in specific radix
 @cindex radix for reading an integer
 @cindex base for reading an integer

-  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
-(radix 8), @samp{#X@var{integer}} reads @var{integer} in hexadecimal
-(radix 16), and @samp{#@var{radix}r@var{integer}} reads @var{integer}
-in radix @var{radix} (where @var{radix} is between 2 and 36,
-inclusivley).  Case is not significant for the letter after @samp{#}
-(@samp{B}, @samp{O}, etc.) that denotes the radix.
+@cindex hex numbers
+@cindex octal numbers
+@cindex reading numbers in hex, octal, and binary
+  The syntax for integers in bases other than 10 uses @samp{#}
+followed by a letter that specifies the radix: @samp{b} for binary,
+@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
+specify radix @var{radix}.  Case is not significant for the letter
+that specifies the radix.  Thus, @samp{#b@var{integer}} reads
+@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
+@var{integer} in radix @var{radix}.  Allowed values of @var{radix} run
+from 2 to 36.  For example:
+
+@example
+#b101100 @result{} 44
+#o54 @result{} 44
+#x2c @result{} 44
+#24r1k @result{} 44
+@end example

 
   To understand how various functions work on integers, especially the
 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
 view the numbers in their binary form.
 
 
   To understand how various functions work on integers, especially the
 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
 
 @example

-0000  0000 0000  0000 0000  0000 0101
+0 0000  0000 0000  0000 0000  0000 0101

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -96,12 +106,12 @@ between groups of 8 bits, to make the binary integer easier to read.)
   The integer @minus{}1 looks like this:
 
 @example
   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
 @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
 complement} notation.)
 
   The negative integer, @minus{}5, is creating by subtracting 4 from


@@ -109,24 +119,24 @@ complement} notation.)
 @minus{}5 looks like this:
 
 @example
 @minus{}5 looks like this:
 
 @example

-1111  1111 1111  1111 1111  1111 1011
+1 1111  1111 1111  1111 1111  1111 1011

 @end example
 
 @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
 
 @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
 @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
 
 @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
 @end example
 
   Many of the functions described in this chapter accept markers for


@@ -135,6 +145,16 @@ arguments to such functions may be either numbers or markers, we often
 give these arguments the name @var{number-or-marker}.  When the argument
 value is a marker, its position value is used and its buffer is ignored.
 
 give these arguments the name @var{number-or-marker}.  When the argument
 value is a marker, its position value is used and its buffer is ignored.
 

+@defvar most-positive-fixnum
+The value of this variable is the largest integer that Emacs Lisp
+can handle.
+@end defvar
+
+@defvar most-negative-fixnum
+The value of this variable is the smallest integer that Emacs Lisp can
+handle.  It is negative.
+@end defvar
+

 @node Float Basics
 @section Floating Point Basics
 
 @node Float Basics
 @section Floating Point Basics
 


@@ -150,34 +170,39 @@ 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}.
 
 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
 @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
 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
 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

-doesn't try to distinguish them.  Here are the read syntaxes for
-these special floating point values:
+doesn't try to distinguish them (but it does report the sign, if you
+print it).  Here are the read syntaxes for these special floating
+point values:

 
 @table @asis
 @item positive infinity
 @samp{1.0e+INF}
 @item negative infinity
 @samp{-1.0e+INF}
 
 @table @asis
 @item positive infinity
 @samp{1.0e+INF}
 @item negative infinity
 @samp{-1.0e+INF}

-@item Not-a-number
-@samp{0.0e+NaN}.
+@item Not-a-number 
+@samp{0.0e+NaN} or @samp{-0.0e+NaN}.

 @end table
 
 @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).
+  To test whether a floating point value is a NaN, compare it with
+itself using @code{=}.  That returns @code{nil} for a NaN, and
+@code{t} for any other floating point value.
+
+  The value @code{-0.0} is distinguishable from ordinary zero in
+@acronym{IEEE} floating point, but Emacs Lisp @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):
 
   You can use @code{logb} to extract the binary exponent of a floating
 point number (or estimate the logarithm of an integer):


@@ -198,13 +223,12 @@ down to an integer.
 @node Predicates on Numbers
 @section Type Predicates for Numbers
 
 @node Predicates on Numbers
 @section Type Predicates for Numbers
 

-  The functions in this section test whether the argument is a number or
-whether it is a certain sort of number.  The functions @code{integerp}
-and @code{floatp} can take any type of Lisp object as argument (the
-predicates would not be of much use otherwise); but the @code{zerop}
-predicate requires a number as its argument.  See also
-@code{integer-or-marker-p} and @code{number-or-marker-p}, in
-@ref{Predicates on Markers}.
+  The functions in this section test for numbers, or for a specific
+type of number.  The functions @code{integerp} and @code{floatp} can
+take any type of Lisp object as argument (they would not be of much
+use otherwise), but the @code{zerop} predicate requires a number as
+its argument.  See also @code{integer-or-marker-p} and
+@code{number-or-marker-p}, in @ref{Predicates on Markers}.

 
 @defun floatp object
 This predicate tests whether its argument is a floating point
 
 @defun floatp object
 This predicate tests whether its argument is a floating point


@@ -238,7 +262,7 @@ considered non-negative.
 This predicate tests whether its argument is zero, and returns @code{t}
 if so, @code{nil} otherwise.  The argument must be a number.
 
 This predicate tests whether its argument is zero, and returns @code{t}
 if so, @code{nil} otherwise.  The argument must be a number.
 

-These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
+@code{(zerop x)} is equivalent to @code{(= x 0)}.

 @end defun
 
 @node Comparison of Numbers
 @end defun
 
 @node Comparison of Numbers


@@ -262,10 +286,11 @@ numbers or markers.  However, it is a good idea to use @code{=} if you
 can, even for comparing integers, just in case we change the
 representation of integers in a future Emacs version.
 
 can, even for comparing integers, just in case we change the
 representation of integers in a future Emacs version.
 

-  Sometimes it is useful to compare numbers with @code{equal}; it treats
-two numbers as equal if they have the same data type (both integers, or
-both floating point) and the same value.  By contrast, @code{=} can
-treat an integer and a floating point number as equal.
+  Sometimes it is useful to compare numbers with @code{equal}; it
+treats two numbers as equal if they have the same data type (both
+integers, or both floating point) and the same value.  By contrast,
+@code{=} can treat an integer and a floating point number as equal.
+@xref{Equality Predicates}.

 
   There is another wrinkle: because floating point arithmetic is not
 exact, it is often a bad idea to check for equality of two floating
 
   There is another wrinkle: because floating point arithmetic is not
 exact, it is often a bad idea to check for equality of two floating


@@ -295,6 +320,13 @@ This function tests whether its arguments are numerically equal, and
 returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
 returns @code{t} if so, @code{nil} otherwise.
 @end defun
 

+@defun eql value1 value2
+This function acts like @code{eq} except when both arguments are
+numbers.  It compares numbers by type and numberic value, so that
+@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
+@code{(eql 1 1)} both return @code{t}.
+@end defun
+

 @defun /= number-or-marker1 number-or-marker2
 This function tests whether its arguments are numerically equal, and
 returns @code{t} if they are not, and @code{nil} if they are.
 @defun /= number-or-marker1 number-or-marker2
 This function tests whether its arguments are numerically equal, and
 returns @code{t} if they are not, and @code{nil} if they are.


@@ -325,7 +357,7 @@ otherwise.
 
 @defun max number-or-marker &rest numbers-or-markers
 This function returns the largest of its arguments.
 
 @defun max number-or-marker &rest numbers-or-markers
 This function returns the largest of its arguments.

-If any of the argument is floating-point, the value is returned
+If any of the arguments is floating-point, the value is returned

 as floating point, even if it was given as an integer.
 
 @example
 as floating point, even if it was given as an integer.
 
 @example


@@ -340,7 +372,7 @@ as floating point, even if it was given as an integer.
 
 @defun min number-or-marker &rest numbers-or-markers
 This function returns the smallest of its arguments.
 
 @defun min number-or-marker &rest numbers-or-markers
 This function returns the smallest of its arguments.

-If any of the argument is floating-point, the value is returned
+If any of the arguments is floating-point, the value is returned

 as floating point, even if it was given as an integer.
 
 @example
 as floating point, even if it was given as an integer.
 
 @example


@@ -366,10 +398,16 @@ it unchanged.
 @end defun
 
 There are four functions to convert floating point numbers to integers;
 @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.
 
 This returns @var{number}, converted to an integer by rounding towards
 zero.
 


@@ -389,10 +427,8 @@ zero.
 This returns @var{number}, converted to an integer by rounding downward
 (towards negative infinity).
 
 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)
 
 @example
 (floor 1.2)


@@ -408,7 +444,7 @@ An @code{arith-error} results if @var{divisor} is 0.
 @end example
 @end defun
 
 @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).
 
 This returns @var{number}, converted to an integer by rounding upward
 (towards positive infinity).
 


@@ -424,7 +460,7 @@ This returns @var{number}, converted to an integer by rounding upward
 @end example
 @end defun
 
 @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,
 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,


@@ -455,8 +491,8 @@ commonly used.
 if any argument is floating.
 
   It is important to note that in Emacs Lisp, arithmetic functions
 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.
 
 @defun 1+ number-or-marker
 This function returns @var{number-or-marker} plus 1.


@@ -552,7 +588,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
 @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
 otherwise, it signals an @code{arith-error} error.
 
 @example


@@ -746,7 +782,7 @@ like this (with 8-bit binary numbers):
 (lsh 3 2)
      @result{} 12
 ;; @r{Decimal 3 becomes decimal 12.}
 (lsh 3 2)
      @result{} 12
 ;; @r{Decimal 3 becomes decimal 12.}

-00000011 @result{} 00001100       
+00000011 @result{} 00001100

 @end group
 @end example
 
 @end group
 @end example
 


@@ -757,14 +793,14 @@ On the other hand, shifting one place to the right looks like this:
 (lsh 6 -1)
      @result{} 3
 ;; @r{Decimal 6 becomes decimal 3.}
 (lsh 6 -1)
      @result{} 3
 ;; @r{Decimal 6 becomes decimal 3.}

-00000110 @result{} 00000011       
+00000110 @result{} 00000011

 @end group
 
 @group
 (lsh 5 -1)
      @result{} 2
 ;; @r{Decimal 5 becomes decimal 2.}
 @end group
 
 @group
 (lsh 5 -1)
      @result{} 2
 ;; @r{Decimal 5 becomes decimal 2.}

-00000101 @result{} 00000010       
+00000101 @result{} 00000010

 @end group
 @end example
 
 @end group
 @end example
 


@@ -775,19 +811,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
 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
 
 @example

-(lsh 134217727 1)          ; @r{left shift}
+(lsh 268435455 1)          ; @r{left shift}

      @result{} -2
 @end example
 
      @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
 
 @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
 
 @end group
 @end example
 


@@ -797,7 +833,7 @@ which becomes the following when left shifted:
 @example
 @group
 ;; @r{Decimal @minus{}2}
 @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
 @end group
 @end example
 @end defun


@@ -818,11 +854,11 @@ looks like this:
 
 @example
 @group
 
 @example
 @group

-(ash -6 -1) @result{} -3            
+(ash -6 -1) @result{} -3

 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}

-1111  1111 1111  1111 1111  1111 1010
-     @result{} 
-1111  1111 1111  1111 1111  1111 1101
+1 1111  1111 1111  1111 1111  1111 1010
+     @result{}
+1 1111  1111 1111  1111 1111  1111 1101

 @end group
 @end example
 
 @end group
 @end example
 


@@ -831,11 +867,11 @@ In contrast, shifting the pattern of bits one place to the right with
 
 @example
 @group
 
 @example
 @group

-(lsh -6 -1) @result{} 134217725
-;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
-1111  1111 1111  1111 1111  1111 1010
-     @result{} 
-0111  1111 1111  1111 1111  1111 1101
+(lsh -6 -1) @result{} 268435453
+;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
+1 1111  1111 1111  1111 1111  1111 1010
+     @result{}
+0 1111  1111 1111  1111 1111  1111 1101

 @end group
 @end example
 
 @end group
 @end example
 


@@ -845,34 +881,34 @@ Here are other examples:
 @c     with smallbook but not with regular book! --rjc 16mar92
 @smallexample
 @group
 @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
 @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
 (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
 @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
 @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
 @end group
 @end smallexample
 @end defun


@@ -909,23 +945,23 @@ because its binary representation consists entirely of ones.  If
 
 @smallexample
 @group
 
 @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
 @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)
 @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
 @end group
 @end smallexample
 @end defun


@@ -941,18 +977,18 @@ passed just one argument, it returns that argument.
 
 @smallexample
 @group
 
 @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
 @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
 @end group
 @end smallexample
 @end defun


@@ -968,18 +1004,18 @@ result is 0, which is an identity element for this operation.  If
 
 @smallexample
 @group
 
 @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
 @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
 @end group
 @end smallexample
 @end defun


@@ -992,11 +1028,11 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
 @var{integer}, and vice-versa.
 
 @example
 @var{integer}, and vice-versa.
 
 @example

-(lognot 5)             
+(lognot 5)

      @result{} -6
      @result{} -6

-;;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
+;;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}

 ;; @r{becomes}
 ;; @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
 
 @end example
 @end defun
 


@@ -1030,8 +1066,8 @@ pi/2
 @tex
 @math{\pi/2}
 @end tex
 @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
 @end defun
 
 @defun acos arg


@@ -1042,12 +1078,12 @@ pi
 @tex
 @math{\pi}
 @end tex
 @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
 
 @end defun
 

-@defun atan arg
-The value of @code{(atan @var{arg})} is a number between
+@defun atan y &optional x
+The value of @code{(atan @var{y})} is a number between

 @ifnottex
 @minus{}pi/2
 @end ifnottex
 @ifnottex
 @minus{}pi/2
 @end ifnottex


@@ -1061,7 +1097,10 @@ pi/2
 @tex
 @math{\pi/2}
 @end tex
 @tex
 @math{\pi/2}
 @end tex

-(exclusive) whose tangent is @var{arg}.
+(exclusive) whose tangent is @var{y}.  If the optional second
+argument @var{x} is given, the value of @code{(atan y x)} is the
+angle in radians between the vector @code{[@var{x}, @var{y}]} and the
+@code{X} axis.

 @end defun
 
 @defun exp arg
 @end defun
 
 @defun exp arg


@@ -1092,8 +1131,8 @@ If you don't specify @var{base}, the base
 @ifnottex
 @i{e}
 @end ifnottex
 @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
 @end defun
 
 @ignore


@@ -1112,20 +1151,20 @@ lose accuracy.
 
 @defun log10 arg
 This function returns the logarithm of @var{arg}, with base 10.  If
 
 @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
 This function returns @var{x} raised to power @var{y}.  If both
 arguments are integers and @var{y} is positive, the result is an
 @end defun
 
 @defun expt x y
 This function returns @var{x} raised to power @var{y}.  If both
 arguments are integers and @var{y} is positive, the result is an

-integer; in this case, it is truncated to fit the range of possible
-integer values.
+integer; in this case, overflow causes truncation, so watch out.

 @end defun
 
 @defun sqrt arg
 This returns the square root of @var{arg}.  If @var{arg} is negative,
 @end defun
 
 @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
 @end defun
 
 @node Random Numbers


@@ -1150,7 +1189,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
 
 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
 
 @defun random &optional limit
 This function returns a pseudo-random integer.  Repeated calls return a


@@ -1160,10 +1199,14 @@ 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
 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
 of @code{random}.  On other machines, the result can never be larger
 than a certain maximum or less than a certain (negative) minimum.
 @end defun
 @c "Emacs'" is incorrect usage!
 
 On some machines, any integer representable in Lisp may be the result
 of @code{random}.  On other machines, the result can never be larger
 than a certain maximum or less than a certain (negative) minimum.
 @end defun

+
+@ignore
+   arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e
+@end ignore