(nnmail-extra-headers): Add defvar.

[gnu-emacs] / lispref / numbers.texi

diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index fbbac56963ec4d9e2f9b71c10aea1bd925a27e1e..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, 2003
-@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


@@ -73,14 +73,21 @@ initial sign and optional final period.
 @cindex hex numbers
 @cindex octal numbers
 @cindex reading numbers in hex, octal, and binary
 @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
-(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,
-inclusively).  Case is not significant for the letter after @samp{#}
-(@samp{B}, @samp{O}, etc.) that denotes the radix.
+  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
 
   To understand how various functions work on integers, especially the
 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to


@@ -168,29 +175,34 @@ to write negative floating point numbers, as in @samp{-1.0}.
 @cindex negative infinity
 @cindex infinity
 @cindex NaN
 @cindex negative infinity
 @cindex infinity
 @cindex NaN

-   Most modern computers support the @acronym{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 @acronym{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):


@@ -211,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


@@ -251,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


@@ -275,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


@@ -308,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.


@@ -338,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


@@ -353,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


@@ -379,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.
 


@@ -402,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)


@@ -421,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).
 


@@ -437,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,


@@ -1043,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


@@ -1055,8 +1078,8 @@ 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
 
 @defun atan y &optional x
 @end defun
 
 @defun atan y &optional x


@@ -1108,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


@@ -1128,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