Proposed standard python module: ieee754

[Gregory R. Warnes]

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>.