Floating-Point Objects

typePyFloatObject

This subtype ofPyObject represents a Python floating-point object.

PyTypeObjectPyFloat_Type
Part of theStable ABI.

This instance ofPyTypeObject represents the Python floating-pointtype. This is the same object asfloat in the Python layer.

intPyFloat_Check(PyObject*p)

Return true if its argument is aPyFloatObject or a subtype ofPyFloatObject. This function always succeeds.

intPyFloat_CheckExact(PyObject*p)

Return true if its argument is aPyFloatObject, but not a subtype ofPyFloatObject. This function always succeeds.

PyObject*PyFloat_FromString(PyObject*str)
Return value: New reference. Part of theStable ABI.

Create aPyFloatObject object based on the string value instr, orNULL on failure.

PyObject*PyFloat_FromDouble(doublev)
Return value: New reference. Part of theStable ABI.

Create aPyFloatObject object fromv, orNULL on failure.

doublePyFloat_AsDouble(PyObject*pyfloat)
Part of theStable ABI.

Return a Cdouble representation of the contents ofpyfloat. Ifpyfloat is not a Python floating-point object but has a__float__()method, this method will first be called to convertpyfloat into a float.If__float__() is not defined then it falls back to__index__().This method returns-1.0 upon failure, so one should callPyErr_Occurred() to check for errors.

Changed in version 3.8:Use__index__() if available.

doublePyFloat_AS_DOUBLE(PyObject*pyfloat)

Return a Cdouble representation of the contents ofpyfloat, butwithout error checking.

PyObject*PyFloat_GetInfo(void)
Return value: New reference. Part of theStable ABI.

Return a structseq instance which contains information about theprecision, minimum and maximum values of a float. It’s a thin wrapperaround the header filefloat.h.

doublePyFloat_GetMax()
Part of theStable ABI.

Return the maximum representable finite floatDBL_MAX as Cdouble.

doublePyFloat_GetMin()
Part of theStable ABI.

Return the minimum normalized positive floatDBL_MIN as Cdouble.

Pack and Unpack functions

The pack and unpack functions provide an efficient platform-independent way tostore floating-point values as byte strings. The Pack routines produce a bytesstring from a Cdouble, and the Unpack routines produce a Cdouble from such a bytes string. The suffix (2, 4 or 8) specifies thenumber of bytes in the bytes string.

On platforms that appear to use IEEE 754 formats these functions work bycopying bits. On other platforms, the 2-byte format is identical to the IEEE754 binary16 half-precision format, the 4-byte format (32-bit) is identical tothe IEEE 754 binary32 single precision format, and the 8-byte format to theIEEE 754 binary64 double precision format, although the packing of INFs andNaNs (if such things exist on the platform) isn’t handled correctly, andattempting to unpack a bytes string containing an IEEE INF or NaN will raise anexception.

On non-IEEE platforms with more precision, or larger dynamic range, than IEEE754 supports, not all values can be packed; on non-IEEE platforms with lessprecision, or smaller dynamic range, not all values can be unpacked. Whathappens in such cases is partly accidental (alas).

Added in version 3.11.

Pack functions

The pack routines write 2, 4 or 8 bytes, starting atp.le is anint argument, non-zero if you want the bytes string in little-endianformat (exponent last, atp+1,p+3, orp+6p+7), zero if youwant big-endian format (exponent first, atp). ThePY_BIG_ENDIANconstant can be used to use the native endian: it is equal to1 on bigendian processor, or0 on little endian processor.

Return value:0 if all is OK,-1 if error (and an exception is set,most likelyOverflowError).

There are two problems on non-IEEE platforms:

  • What this does is undefined ifx is a NaN or infinity.

  • -0.0 and+0.0 produce the same bytes string.

intPyFloat_Pack2(doublex,unsignedchar*p,intle)

Pack a C double as the IEEE 754 binary16 half-precision format.

intPyFloat_Pack4(doublex,unsignedchar*p,intle)

Pack a C double as the IEEE 754 binary32 single precision format.

intPyFloat_Pack8(doublex,unsignedchar*p,intle)

Pack a C double as the IEEE 754 binary64 double precision format.

Unpack functions

The unpack routines read 2, 4 or 8 bytes, starting atp.le is anint argument, non-zero if the bytes string is in little-endian format(exponent last, atp+1,p+3 orp+6 andp+7), zero if big-endian(exponent first, atp). ThePY_BIG_ENDIAN constant can be used touse the native endian: it is equal to1 on big endian processor, or0on little endian processor.

Return value: The unpacked double. On error, this is-1.0 andPyErr_Occurred() is true (and an exception is set, most likelyOverflowError).

Note that on a non-IEEE platform this will refuse to unpack a bytes string thatrepresents a NaN or infinity.

doublePyFloat_Unpack2(constunsignedchar*p,intle)

Unpack the IEEE 754 binary16 half-precision format as a C double.

doublePyFloat_Unpack4(constunsignedchar*p,intle)

Unpack the IEEE 754 binary32 single precision format as a C double.

doublePyFloat_Unpack8(constunsignedchar*p,intle)

Unpack the IEEE 754 binary64 double precision format as a C double.