Module float

ieeefloat a set of functions for dealing with IEEE-754 float objects.

On most platforms Python uses IEEE-754 double objects of length 64 bits to represent floats (some architectures such as older Crays and Vaxes don't). Thus an IEEE-754 double is the implementation of a python float object on most platforms.

IEEE-74 uses special bit patterns to represent the following states or classes of IEEE floating point numbers (IEEE-class):

• +/- NaN: Not a number (e.g. 0.0/0.0).
• inf: Positive or negative infinity (1.0/0.0).
• +/- zero: Zero maybe positive or negative under IEEE-754.

This module provides functions for working with python floats and their special values, if they contain IEEE-754 formatted values. Specifically:

• Pack and unpack a list of bytes representing an IEEE-754 double to a python float (takes care of little endian/big endian issues).
• Get the sign bit of a python float.
• Check the ordering of python floats allowing for NaNs (NaNs cannot normally be compared).
• Check if a value is finite (as opposed to NaN or inf).
• Copy the sign of one float to another irrespective of if it's IEEE-class.
• Check if a float is denormalised (and might be about to underflow).
• Check the IEEE-class of a python float (NaN, pos-inf, neg-inf, pos-zero, neg-zero, ...).
• Check that the current python float implementations uses IEEE-754 doubles.

It also provides constants containg specific bit patterns for NaN and +-inf as these values cannot be generated from strings via the constructor float(x) with some compiler implementations (typically older Microsoft Windows compilers).

As a convenience the names of functions and constants conform to those defined in the draft python PEP 754 'IEEE 754 Floating Point Special Values'.

Notes:

1. Binary data is documented as binary strings e.g. 0xF0 = 0b11110000.
2. The module doesn't support all the functions recommended by IEEE-754, the following features are missing:
   • Control of exception and rounding modes.
   • scalb(y, N).
   • logb(x).
   • nextafter(x,y).
   • Next towards.
3. Division by zero currently (python 2.5) raises exception and the resulting inf/NaN cannot be propogated.
4. A second module ieeefloatcapabilities (currently incomplete) provides tests of the capabilities of a floating point implementation on a specific python platform.
5. Development and conventions on byte order come from a little endian (Intel) platform.
6. To reduce overheads all functions that take python float arguments do _no type_ conversion thus if other numeric types are passed the functions will raise exceptions, (I am not sure this is the best behaviour however, as python functions should be polymorphic...).
7. In most cases conversion to C code for performance reasons would be trivial.

IEEE-754 double format:

• 63 sign bit.
• 62-52 exponent (offset by 1023 value - field-1023).
• 51-0 mantissa each bit n counts as 1/2^n, running from 1/2 which is the most significant bit to 1/2^51, The 1/0 bit is defined by the exponent field if it has any bits set if it has bits set then precede the mantissa with a 1 (normalised otherwise precede it by a 0 (denormalised).

Todo:

• Unit test suite.
• Test under Windows.
• Test under a Solaris Sparc box (big endian).
• Add example IEEE double.
• Check byte/nibble attributions.

Functions

isZero(float)

int getFloatClass(float)
Get the IEEE-class (NaN, inf etc) of a python float.

float packBytesAsPyFloat(bytes)
Pack 8 bytes into a python float.

str floatToBinaryString(obj)
Pack a python float into a binary string.

list of str floatAsByteArray(obj)
Unpack a python float as a list of 8 bytes.

bit getSignBit(obj)
Get the sign bit from a python float.

bool isPositive(obj)
Test if a python float is positive.

bool isNegative(obj)
Test if a python float 64 bit IEEE-74 double is negative.

bool areUnordered(obj1, obj2)
Test to see if two python float are unordered.

bool isFinite(obj)
Test to see if a python float is finite.

copySign(fromNumber, toDouble)
Copy the sign bit from one python float to another.

bool isDenormalised(obj)
Check to see if a python float is denormalised.

list of 7 bytes getMantissaBytes(obj)
Get the 7 bytes that makeup the mantissa of float.

list of 2 bytes getExponentBytes(obj)
Get the 2 bytes that makeup the exponent of a float.

bool isExpAllZeros(obj)
Check if the bits of the exponent of a float is zero.

bool isMantissaAllZeros(obj)
Check if the bits of the mantissa of a float is zero.

bool isExpAllOnes(obj)
Check if the bits of the exponent of a float is all 1 bits.

bool isNaN(obj)
Check to see if a python float is an IEEE-754 double not a number (NaN).

bool isInf(obj)
Check to see if a python float is an infinity.

bool isPosInf(obj)
Check to see if a python float is positive infinity.

bool isNegInf(obj)
Check to see if a python float is negative infinity.

float bitpatternToFloat(string, endian='big')
Convert a 64 bit IEEE-754 ascii bit pattern into a 64 bit Python float.

int bitpatternToInt(string, endian='big')
Convert a bit pattern into its integer representation.

Variables

SIGNBIT = 128
Bit pattern for the sign bit in byte 8 0b00000001 of a IEEE-754 double.

EXPONENT_ALL_ONES_BYTE_1 = 127
Value of the first byte (byte 8) in the mantissa of a IEEE-754 double that is all ones (0b11111110).

EXPONENT_ALL_ONES_BYTE_0 = 240
Value of the second byte (byte 7) in the mantissa of a IEEE-754 double that is all ones (0b00001111).

MANTISSA_NIBBLE_MASK = 15
Mask to select the bits from the first nibble of byte 7 of an IEEE-754 which is part of the mantissa (0b00001111).

EXPONENT_NIBBLE_MASK = 240
Mask to select the bits from the second nibble of byte 7 of an IEEE-754 which is part of the exponent (0b11110000).

EXPONENT_SIGN_MASK = 127
Mask to select only bits from byte 8 of an IEEE-754 double that are not part of the sign bit (0b11111110).

CLASS_POS_INF = 1

CLASS_NEG_INF = 2

CLASS_POS_NORMAL = 4

CLASS_NEG_NORMAL = 8

CLASS_POS_DENORMAL = 16

CLASS_NEG_DENORMAL = 32

CLASS_QUIET_NAN = 64

CLASS_SIGNAL_NAN = 128

CLASS_POS_ZERO = 256

CLASS_NEG_ZERO = 512

NAN_BYTES = [0, 0, 0, 0, 0, 0, 248, 127]
Bytes for an arbitary IEEE-754 not a number (NaN) in little endian format 0b00000000 00000000 00000000 00000000 00000000 00000000 00011111 11111110.

INF_BYTES = [0, 0, 0, 0, 0, 0, 240, 127]
Bytes for IEEE-754 positive infinity (inf) in little endian format 0b00000000 00000000 00000000 00000000 00000000 00000000 00001111 11111110.

nan = nan
One of a number of possible bit patterns used to represent an IEEE-754 double as a python float.

pos_inf = inf
The value of a positive IEEE-754 double infinity as a python float.

neg_inf = -inf
The value of a negative IEEE-754 double infinity as a python float.

PosZero = 0.0

NegZero = -0.0

PosEpsilonDenorm = 4.94065645841e-324

NegEpsilonDenorm = -4.94065645841e-324

PosEpsilonNorm = 2.22507385851e-308

NegEpsilonNorm = -2.22507385851e-308

PosMax = 1.79769313486e+308

NegMin = -1.79769313486e+308

PosInf = inf

NegInf = -inf

PosNaN_A = nan

NegNaN_A = nan

PosNaN_B = nan

NegNaN_B = nan

PosNaN_C = nan

NegNaN_C = nan

PosNaN = nan

NegNaN = nan

__package__ = None
hash(x)

Imports: pack, unpack, sys

Function Details

getFloatClass(float)

Get the IEEE-class (NaN, inf etc) of a python float.

Parameters:

• float (float) - Python float object.

Returns: int

An IEEE class value.

Raises:

• TypeError - If float is not a python float object.

packBytesAsPyFloat(bytes)

Pack 8 bytes into a python float.

The function is endian aware and the data should be input in little endian format. Thus byte 8 contains the most significant bit of the exponent and the sign bit.

Parameters:

• bytes (float) - 8 bytes to pack into a python (IEEE 754 double) float.

Returns: float

A python float

Raises:

• TypeError - If bytes contains < 8 bytes type of exception not determined.

floatToBinaryString(obj)

Pack a python float into a binary string.

This function assumes that the python type float it represents a 64bit double of 8 bytes. This function reverses the resulting string if the current architecture is big endian.

Parameters:

• obj (float) - A python float to pack.

Returns: str

A string of 8 bytes.

Raises:

• TypeError - If the input object isn't a python float.

floatAsByteArray(obj)

Unpack a python float as a list of 8 bytes.

This function assumes that the python type float it represents a 64bit double of 8 bytes.

Parameters:

• obj (float) - A python float to unpack.

Returns: list of str

A list of 7 bytes.

Raises:

• TypeError - If obj is not composed of 8 bytes.

getSignBit(obj)

Get the sign bit from a python float.

Parameters:

• obj (float) - A python float object.

Returns: bit

The float's sign bit, this has the value 1 if the float is negative otherwise 0 (positive).

Raises:

• TypeError - If the input object isn't a python float.

isPositive(obj)

Test if a python float is positive.

Parameters:

• obj (float) - A python float object.

Returns: bool

True if the float is positive otherwise False.

Raises:

• TypeError - If the input object isn't a python float.

isNegative(obj)

Test if a python float 64 bit IEEE-74 double is negative.

Parameters:

• obj (float) - A python float object.

Returns: bool

True if the float is negative.

Raises:

• TypeError - If the input object isn't a python float.

areUnordered(obj1, obj2)

Test to see if two python float are unordered.

Float comparison is unordered if either or both of the objects is 'not a number' (NaN).

Parameters:

• obj1 (float) - A python float object
• obj2 (float) - A python float object

Returns: bool

True if one of the args is a NaN.

Raises:

• TypeError - If the input objects aren't python floats.

isFinite(obj)

Test to see if a python float is finite.

To be finite a number mustn't be a NaN or +/- inf. A result of True guarantees that the number is bounded by +/- inf, -inf < x < inf.

Parameters:

• obj (float) - A python float object.

Returns: bool

True if the float is finite.

Raises:

• TypeError - If the input object isn't a python float.

copySign(fromNumber, toDouble)

Copy the sign bit from one python float to another.

This function is class agnostic the sign bit can be copied freely between ordinary floats, NaNs and +/- inf.

Parameters:

• fromNumber (float) - The python float to copy the sign bit from.
• toDouble (float) - The python float to copy the sign bit to.

Raises:

• TypeError - If toDouble isn't a python float or if fromNumber can't be converted to a float.

isDenormalised(obj)

Check to see if a python float is denormalised.

Denormalisation indicates that the number has no exponent set and all the precision is in the mantissa, this is an indication that the number is tending to towards underflow.

Parameters:

• obj (float) - Python float object to check.

Returns: bool

True if the number is denormalised.

Raises:

• TypeError - If toDouble isn't a python float or if obj isn't a float.

getMantissaBytes(obj)

Get the 7 bytes that makeup the mantissa of float.

The mantissa is returned as the 7 bytes in the mantissa in little endian order in the 7th byte the 2nd nibble of the byte is masked off as it contains part of the exponent. The second nibble of the 7th byte is therefore always has the value 0x0.

Parameters:

• obj (float) - Float object to extract the mantissa from.

Returns: list of 7 bytes

A list of 7 bytes in little endian order.

Raises:

• TypeError - If obj isn't a python float.

getExponentBytes(obj)

Get the 2 bytes that makeup the exponent of a float.

The exponent is returned as the 2 bytes in the exponent in little endian order in the 2nd byte the last bit is masked off as this is the sign bit. Therefore all values have the last bit set to zero. In the first byte the first nibble of the byte is also masked off as it contains part of the mantissa and thus always has the value 0x0.

Parameters:

• obj (float) - Float object to extract the exponent from.

Returns: list of 2 bytes

A list of 2 bytes in little endian order.

Raises:

• TypeError - If obj isn't a python float.

isExpAllZeros(obj)

Check if the bits of the exponent of a float is zero.

Parameters:

• obj (float) - Float object to check exponent for zero value.

Returns: bool

True if the exponent is zero.

Raises:

• TypeError - If obj isn't a python float.

isMantissaAllZeros(obj)

Check if the bits of the mantissa of a float is zero.

Parameters:

• obj (float) - Float object to check mantissa for zero value.

Returns: bool

True if the mantissa is zero.

Raises:

• TypeError - If obj isn't a python float.

isExpAllOnes(obj)

Check if the bits of the exponent of a float is all 1 bits.

Parameters:

• obj (float) - Float object to check exponent for 1 bits.

Returns: bool

True if all the bits in the exponent are one.

Raises:

• TypeError - If obj isn't a python float.

isNaN(obj)

Check to see if a python float is an IEEE-754 double not a number (NaN).

Parameters:

• obj (float) - Float object to check for not a number.

Returns: bool

True if object is not a number.

Raises:

• TypeError - If obj isn't a python float.

isInf(obj)

Check to see if a python float is an infinity.

The check returns true for either positive or negative infinities.

Parameters:

• obj (float) - Float object to check for infinity.

Returns: bool

True if object is an infinity.

Raises:

• TypeError - If obj isn't a python float.

isPosInf(obj)

Check to see if a python float is positive infinity.

Parameters:

• obj (float) - Float object to check for positive infinity.

Returns: bool

True if object is a positive infinity.

Raises:

• TypeError - If obj isn't a python float.

isNegInf(obj)

Check to see if a python float is negative infinity.

Parameters:

• obj (float) - Float object to check for negative infinity.

Returns: bool

True if object is a negative infinity.

Raises:

• TypeError - If obj isn't a python float.

bitpatternToFloat(string, endian='big')

Convert a 64 bit IEEE-754 ascii bit pattern into a 64 bit Python float.

Parameters:

• string (str) - The ascii bit pattern repesenting the IEEE-754 float.
• endian (str) - The endianness of the bit pattern (can be 'big' or 'little').

Returns: float

The 64 bit float corresponding to the IEEE-754 bit pattern.

Raises:

• TypeError - If 'string' is not a string, the length of the 'string' is not 64, or if 'string' does not consist solely of the characters '0' and '1'.

bitpatternToInt(string, endian='big')

Convert a bit pattern into its integer representation.

Parameters:

• string (str) - The ascii string repesenting binary data.
• endian (str) - The endianness of the bit pattern (can be 'big' or 'little').

Returns: int

The integer value.

Variables Details

nan

One of a number of possible bit patterns used to represent an IEEE-754 double as a python float. Do not use this value for comparisons of the form x==NaN as it will fail on some platforms use function isNaN instead.

Value:

nan