Proposed standard python module: ieee754
Gregory R. Warnes
warnes at warnes.net
Thu Mar 27 17:51:06 EST 2003
I've written a small pure-python module for handling IEEE 754 special
values that I would like to propose as an addition to the standard python
library. I've included the README file which describes the module
below.
1) What is the mechanism for submitting this for inclusion?
2) Also, can others please inspect the code?
Thanks
-Greg
>From the README:
INTRODUCTION
[The ieee754 python module] implements constants and functions for
working with IEEE754 double-precision special values. It provides
constants for Not-a-Number (NaN), Positive Infinity (Inf), and Negative
Infinity(-Inf), as well as functions to test for these values.
WHY THIS MODULE IS NEEDED:
Handling of IEEE 754 special values in python depends on the
underlying C library. For instance, on some systems "float('Inf')"
will properly return the IEEE 754 value for infinity. On other sytems
(notably MS-Windows) this generates an error.
Likewise the string represenation of an IEEE 754 special value
generated from a floating point value also varies by platform. For
example, the command "float(1e3000)", returns 'inf' on Python 2.1.3 on
Debian Linux ('testing'). On Solaris 8 with python 2.2.1, this
returns 'Infinity', and on MS-Windows 2000 with Active Python 2.2.1,
this returns '1.#INF'.
In the past, it has been recommendations to use
Inf = 1e300**2
NaN = Inf/Inf
to define positive infinity and not-a-number. However, the first
expression generates an error on all of the python interpreted I
have available, and is not easily understandable even if it works.
In addition, this does not permit detection of NaN values, since
the IEEE 754 standard requires that
NaN != x
for all possible values of x, including NaN.
Consequently, it is impossible to consistently set or detect IEEE
754 floating point values in normal python code without resorting
to manipulating bit-patterns directly.
The ieee754 module performs the necessary bit-pattern manipulation
to directly set and test for the patterns that define IEEE 754
special values, relieving the programmer of this burden.
CONSTANTS
NaN I
IEEE 754 'Not a Number' value
Inf
IEEE 754 Positive Infinity value
NegInf
IEEE 754 Negative Infinity value
PosInf
IEEE 754 Positive Infinity value
FUNCTIONS
is_NaN(value)
Determine if the argument is a IEEE 754 NaN (Not a Number) value.
is_Inf(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 inifinity)
is_Infinite(value)
Determine if the argument is an infinite IEEE 754 value (positive
or negative inifinity)
sign(dval)
Extract the sign bit from a double-precision floating point value
mantissa(dval)
Extract the mantissa bits from a double-precision floating
point value.
exponent(dval)
Extract the exponentent bits from a double-precision floating
point value.
Note that for normalized values, the exponent has an offset of
1023. As a consequence, the actual exponent is obtained by
subtracting 1023 from the value returned by this function.
EXAMPLE
(Run under Python 2.2.1 on Solaris 8)
>>> import ieee754
>>> val = 1e30000 # should be cause overflow and result in 'Inf'
>>> val
Infinity
>>> ieee754.is_Inf(val)
1
>>> ieee754.Inf
Infinity
>>> nval = val/val # should result in NaN
>>> nval
NaN
>>> ieee754.is_NaN(nval)
1
>>> ieee754.is_NaN(val)
0
IMPLEMENTATION
The code is implemented 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.
Further information on this package is available at
<http://software.biostat.washington.edu/statsoft/snake/ieee754>.
More information about the Python-list
mailing list