Package lib :: Module float
[hide private]
[frames] | no frames]

Module float

source code

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):

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

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

Todo:

Functions [hide private]
 
isZero(float) source code
int
getFloatClass(float)
Get the IEEE-class (NaN, inf etc) of a python float.
source code
float
packBytesAsPyFloat(bytes)
Pack 8 bytes into a python float.
source code
str
floatToBinaryString(obj)
Pack a python float into a binary string.
source code
list of str
floatAsByteArray(obj)
Unpack a python float as a list of 8 bytes.
source code
bit
getSignBit(obj)
Get the sign bit from a python float.
source code
bool
isPositive(obj)
Test if a python float is positive.
source code
bool
isNegative(obj)
Test if a python float 64 bit IEEE-74 double is negative.
source code
bool
areUnordered(obj1, obj2)
Test to see if two python float are unordered.
source code
bool
isFinite(obj)
Test to see if a python float is finite.
source code
 
copySign(fromNumber, toDouble)
Copy the sign bit from one python float to another.
source code
bool
isDenormalised(obj)
Check to see if a python float is denormalised.
source code
list of 7 bytes
getMantissaBytes(obj)
Get the 7 bytes that makeup the mantissa of float.
source code
list of 2 bytes
getExponentBytes(obj)
Get the 2 bytes that makeup the exponent of a float.
source code
bool
isExpAllZeros(obj)
Check if the bits of the exponent of a float is zero.
source code
bool
isMantissaAllZeros(obj)
Check if the bits of the mantissa of a float is zero.
source code
bool
isExpAllOnes(obj)
Check if the bits of the exponent of a float is all 1 bits.
source code
bool
isNaN(obj)
Check to see if a python float is an IEEE-754 double not a number (NaN).
source code
bool
isInf(obj)
Check to see if a python float is an infinity.
source code
bool
isPosInf(obj)
Check to see if a python float is positive infinity.
source code
bool
isNegInf(obj)
Check to see if a python float is negative infinity.
source code
float
bitpatternToFloat(string, endian='big')
Convert a 64 bit IEEE-754 ascii bit pattern into a 64 bit Python float.
source code
int
bitpatternToInt(string, endian='big')
Convert a bit pattern into its integer representation.
source code
Variables [hide private]
  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__ = 'lib'

Imports: pack, unpack, sys, is_float


Function Details [hide private]

getFloatClass(float)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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)

source code 

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')

source code 

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')

source code 

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 [hide private]

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