added PEP 754, "IEEE 754 Floating Point Special Values", by Gregory R. Warnes (spell-checked & edited)
This commit is contained in:
David Goodger
parent
16bd9078c1
commit
cc783e1fc0
|
|
@ -115,6 +115,7 @@ Index by Category
|
|||
S 311 Simplified GIL Acquisition for Extensions Hammond
|
||||
S 312 Simple Implicit Lambda Suzi, Martelli
|
||||
S 313 Adding Roman Numeral Literals to Python Meyer
|
||||
S 754 IEEE 754 Floating Point Special Values Warnes
|
||||
|
||||
Finished PEPs (done, implemented in CVS)
|
||||
|
||||
|
|
@ -319,6 +320,7 @@ Numerical Index
|
|||
S 312 Simple Implicit Lambda Suzi, Martelli
|
||||
S 313 Adding Roman Numeral Literals to Python Meyer
|
||||
SR 666 Reject Foolish Indentation Creighton
|
||||
S 754 IEEE 754 Floating Point Special Values Warnes
|
||||
|
||||
|
||||
Key
|
||||
|
|
@ -396,6 +398,7 @@ Owners
|
|||
Stein, Greg gstein@lyra.org
|
||||
Suzi, Roman rnd@onego.ru
|
||||
Tirosh, Oren oren at hishome.net
|
||||
Warnes, Gregory R. warnes@users.sourceforge.net
|
||||
Warsaw, Barry barry@zope.com
|
||||
Wells, Cliff LogiplexSoftware@earthlink.net
|
||||
Wilson, Greg gvwilson@ddj.com
|
||||
|
|
|
|||
|
|
@ -0,0 +1,190 @@
|
|||
PEP: 754
|
||||
Title: IEEE 754 Floating Point Special Values
|
||||
Version: $Revision$
|
||||
Last-Modified: $Date$
|
||||
Author: Gregory R. Warnes <warnes@users.sourceforge.net>
|
||||
Status: Draft
|
||||
Type: Standard Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 28-Mar-2003
|
||||
Python-Version: 2.3
|
||||
Post-History:
|
||||
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
||||
This PEP proposes an API and a provides a reference module that
|
||||
generates and tests for IEEE 754 double-precision special values:
|
||||
positive infinity (Inf), negative infinity (-Inf), and not-a-number
|
||||
(NaN).
|
||||
|
||||
|
||||
Rationale
|
||||
=========
|
||||
|
||||
The IEEE 754 standard defines a set of binary representations and
|
||||
algorithmic rules for floating point arithmetic. Included in the
|
||||
standard is a set of constants for representing special values,
|
||||
including positive infinity (Inf), negative infinity (-Inf), and
|
||||
indeterminate or non-numeric results (NaN). Most modern CPUs
|
||||
implement the IEEE 754 standard, including the (Ultra)SPARC, PowerPC,
|
||||
and x86 processor series.
|
||||
|
||||
Currently, the handling of IEEE 754 special values in Python depends
|
||||
on the underlying C library. Unfortunately, there is little
|
||||
consistency between C libraries in how or whether these values are
|
||||
handled. For instance, on some systems "float('Inf')" will properly
|
||||
return the IEEE 754 constant for positive infinity. On many systems,
|
||||
however, this expression will instead generate an error message.
|
||||
|
||||
The output string representation for an IEEE 754 special value also
|
||||
varies by platform. For example, the expression "float(1e3000)",
|
||||
which is large enough to generate an overflow, should return a string
|
||||
representation corresponding to IEEE 754 positive infinity. Python
|
||||
2.1.3 on x86 Debian Linux returns "inf". On Sparc Solaris 8 with
|
||||
Python 2.2.1, this same expression returns "Infinity", and on
|
||||
MS-Windows 2000 with Active Python 2.2.1, it returns "1.#INF".
|
||||
|
||||
Adding to the confusion, some platforms generate one string on
|
||||
conversion from floating point and accept a different string for
|
||||
conversion to floating point. On these systems ::
|
||||
|
||||
float(str(x))
|
||||
|
||||
will generate an error when "x" is an IEEE special value.
|
||||
|
||||
In the past, some have recommended that programmers use expressions
|
||||
like::
|
||||
|
||||
Inf = 1e300**2
|
||||
NaN = Inf/Inf
|
||||
|
||||
to obtain positive infinity and not-a-number constants. However, the
|
||||
first expression generates an error on current Python interpreters. A
|
||||
possible alternative is to use::
|
||||
|
||||
Inf = 1e300000
|
||||
NaN = Inf/Inf
|
||||
|
||||
While this does not generate an error with current Python
|
||||
interpreters, it is still an ugly and potentially non-portable hack.
|
||||
In addition, defining NaN in this way does solve the problem of
|
||||
detecting such values. First, the IEEE 754 standard provides for an
|
||||
entire set of constant values for Not-a-Number. Second, the standard
|
||||
requires that ::
|
||||
|
||||
NaN != X
|
||||
|
||||
for all possible values of X, including NaN. As a consequence ::
|
||||
|
||||
NaN == NaN
|
||||
|
||||
should always evaluate to false. However, this behavior also is not
|
||||
consistently implemented. [e.g. Cygwin Python 2.2.2]
|
||||
|
||||
Due to the many platform and library inconsistencies in handling IEEE
|
||||
special values, it is impossible to consistently set or detect IEEE
|
||||
754 floating point values in normal Python code without resorting to
|
||||
directly manipulating bit-patterns.
|
||||
|
||||
This PEP proposes a standard Python API and provides a reference
|
||||
module implementation which allows for consistent handling of IEEE 754
|
||||
special values on all supported platforms.
|
||||
|
||||
|
||||
API Definition
|
||||
==============
|
||||
|
||||
Constants
|
||||
---------
|
||||
|
||||
NaN
|
||||
IEEE 754 "Not a Number" value
|
||||
|
||||
Inf, PosInf
|
||||
IEEE 754 Positive Infinity value
|
||||
|
||||
NegInf
|
||||
IEEE 754 Negative Infinity value
|
||||
|
||||
|
||||
Functions
|
||||
---------
|
||||
|
||||
is_NaN(value)
|
||||
Determine if the argument is a IEEE 754 NaN (Not a Number) value.
|
||||
|
||||
is_Inf(value), is_PosInf(value)
|
||||
Determine if the argument is a IEEE 754 positive infinity value
|
||||
|
||||
is_NegInf(value)
|
||||
Determine if the argument is a IEEE 754 negative infinity value
|
||||
|
||||
is_Finite(value)
|
||||
Determine if the argument is an finite IEEE 754 value (i.e., is
|
||||
not NaN, positive or negative infinity)
|
||||
|
||||
is_Infinite(value)
|
||||
Determine if the argument is an infinite IEEE 754 value (positive
|
||||
or negative infinity)
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
(Run under Python 2.2.1 on Solaris 8.)
|
||||
|
||||
>>> import fpconst
|
||||
>>> val = 1e30000 # should be cause overflow and result in "Inf"
|
||||
>>> val
|
||||
Infinity
|
||||
>>> fpconst.is_Inf(val)
|
||||
1
|
||||
>>> fpconst.Inf
|
||||
Infinity
|
||||
>>> nval = val/val # should result in NaN
|
||||
>>> nval
|
||||
NaN
|
||||
>>> fpconst.is_NaN(nval)
|
||||
1
|
||||
>>> fpconst.is_NaN(val)
|
||||
0
|
||||
|
||||
|
||||
Implementation
|
||||
--------------
|
||||
|
||||
The reference implementation is provided in the module "fpconst" [1]_,
|
||||
which is written in pure Python by taking advantage of the "struct"
|
||||
standard module to directly set or test for the bit patterns that
|
||||
define IEEE 754 special values. Care has been taken to generate
|
||||
proper results on both big-endian and little-endian machines.
|
||||
|
||||
The current implementation is pure Python, but some efficiency could
|
||||
be gained by translating the core routines into C.
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
See http://babbage.cs.qc.edu/courses/cs341/IEEE-754references.html for
|
||||
reference material on the IEEE 754 floating point standard.
|
||||
|
||||
.. [1] Further information on the reference package is available at
|
||||
http://software.biostat.washington.edu/statsoft/snake/fpconst.
|
||||
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
This document has been placed in the public domain.
|
||||
|
||||
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 70
|
||||
End:
|
||||
Loading…
Reference in New Issue