Floating-point numbers are useful for representing numbers that are
not integral. The range of floating-point numbers is
the same as the range of the C data type @code{double} on the machine
-you are using. On all computers currently supported by Emacs, this is
-double-precision @acronym{IEEE} floating point.
+you are using. On all computers supported by Emacs, this is
+@acronym{IEEE} binary64 floating point format, which is standardized by
+@url{https://standards.ieee.org/standard/754-2019.html,,IEEE Std 754-2019}
+and is discussed further in David Goldberg's paper
+``@url{https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html,
+What Every Computer Scientist Should Know About Floating-Point Arithmetic}''.
The read syntax for floating-point numbers requires either a decimal
point, an exponent, or both. Optional signs (@samp{+} or @samp{-})
@defun cl-float-limits
This function makes sure that the Common Lisp floating-point parameters
like @code{cl-most-positive-float} have been initialized. Until it is
-called, these parameters will be @code{nil}.
-@c If this version of Emacs does not support floats, the parameters will
-@c remain @code{nil}.
+called, these parameters have unspecified values.
If the parameters have already been initialized, the function returns
immediately.
-
-The algorithm makes assumptions that will be valid for almost all
-machines, but will fail if the machine's arithmetic is extremely
-unusual, e.g., decimal.
@end defun
Since true Common Lisp supports up to four different kinds of floating-point
numbers, it has families of constants like
@code{most-positive-single-float}, @code{most-positive-double-float},
-@code{most-positive-long-float}, and so on. Emacs has only one
-kind of floating-point number, so this package just uses single constants.
+@code{most-positive-long-float}, and so on. This package uses just
+one set of constants because Emacs has only one kind of
+floating-point number, namely the IEEE binary64 floating-point format.
+@xref{Float Basics,,,elisp,GNU Emacs Lisp Reference Manual}.
@defvar cl-most-positive-float
-This constant equals the largest value a Lisp float can hold.
-For those systems whose arithmetic supports infinities, this is
-the largest @emph{finite} value. For IEEE machines, the value
-is approximately @code{1.79e+308}.
+This constant equals the largest finite value a Lisp float can hold.
+For IEEE binary64 format, this equals @code{(- (expt 2 1024) (- 2
+971))}, which equals @code{1.7976931348623157e+308}.
@end defvar
@defvar cl-most-negative-float
-This constant equals the most negative value a Lisp float can hold.
-(It is assumed to be equal to @code{(- cl-most-positive-float)}.)
+This constant equals the most negative finite value a Lisp float can hold.
+For IEEE binary64 format, this equals @code{(- cl-most-positive-float)}.
@end defvar
-@defvar cl-least-positive-float
-This constant equals the smallest Lisp float value greater than zero.
-For IEEE machines, it is about @code{4.94e-324} if denormals are
-supported or @code{2.22e-308} if not.
+@defvar cl-least-positive-normalized-float
+This constant equals the smallest positive Lisp float that is
+@dfn{normalized}, i.e., that has full precision.
+For IEEE binary64 format, this equals @code{(expt 2 -1022)},
+which equals @code{2.2250738585072014e-308}.
@end defvar
-@defvar cl-least-positive-normalized-float
-This constant equals the smallest @emph{normalized} Lisp float greater
-than zero, i.e., the smallest value for which IEEE denormalization
-will not result in a loss of precision. For IEEE machines, this
-value is about @code{2.22e-308}. For machines that do not support
-the concept of denormalization and gradual underflow, this constant
-will always equal @code{cl-least-positive-float}.
+@defvar cl-least-positive-float
+This constant equals the smallest Lisp float value greater than zero.
+For IEEE binary64 format, this equals @code{5e-324} (which equals
+@code{(expt 2 -1074)}) if subnormal numbers are supported, and
+@code{cl-least-positive-normalized-float} otherwise.
@end defvar
@defvar cl-least-negative-float
@defvar cl-float-epsilon
This constant is the smallest positive Lisp float that can be added
to 1.0 to produce a distinct value. Adding a smaller number to 1.0
-will yield 1.0 again due to roundoff. For IEEE machines, epsilon
-is about @code{2.22e-16}.
+will yield 1.0 again due to roundoff. For IEEE binary64 format, this
+equals @code{(expt 2 -52)}, which equals @code{2.220446049250313e-16}.
@end defvar
@defvar cl-float-negative-epsilon
This is the smallest positive value that can be subtracted from
-1.0 to produce a distinct value. For IEEE machines, it is about
-@code{1.11e-16}.
+1.0 to produce a distinct value. For IEEE binary64 format, this
+equals @code{(expt 2 -53)}, which equals @code{1.1102230246251565e-16}.
@end defvar
@node Sequences
(defconst cl-most-positive-float nil
"The largest value that a Lisp float can hold.
If your system supports infinities, this is the largest finite value.
-For IEEE machines, this is approximately 1.79e+308.
+For Emacs, this equals 1.7976931348623157e+308.
Call `cl-float-limits' to set this.")
(defconst cl-most-negative-float nil
(defconst cl-least-positive-float nil
"The smallest value greater than zero that a Lisp float can hold.
-For IEEE machines, it is about 4.94e-324 if denormals are supported,
-or 2.22e-308 if they are not.
+For Emacs, this equals 5e-324 if subnormal numbers are supported,
+`cl-least-positive-normalized-float' if they are not.
Call `cl-float-limits' to set this.")
(defconst cl-least-negative-float nil
(defconst cl-least-positive-normalized-float nil
"The smallest normalized Lisp float greater than zero.
-This is the smallest value for which IEEE denormalization does not lose
-precision. For IEEE machines, this value is about 2.22e-308.
-For machines that do not support the concept of denormalization
-and gradual underflow, this constant equals `cl-least-positive-float'.
+This is the smallest value that has full precision.
+For Emacs, this equals 2.2250738585072014e-308.
Call `cl-float-limits' to set this.")
(defconst cl-least-negative-normalized-float nil
(defconst cl-float-epsilon nil
"The smallest positive float that adds to 1.0 to give a distinct value.
Adding a number less than this to 1.0 returns 1.0 due to roundoff.
-For IEEE machines, epsilon is about 2.22e-16.
+For Emacs, this equals 2.220446049250313e-16.
Call `cl-float-limits' to set this.")
(defconst cl-float-negative-epsilon nil
"The smallest positive float that subtracts from 1.0 to give a distinct value.
-For IEEE machines, it is about 1.11e-16.
+For Emacs, this equals 1.1102230246251565e-16.
Call `cl-float-limits' to set this.")
projects / emacs.git / commitdiff