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.

Py_INFINITY

This macro expands to a constant expression of typedouble, thatrepresents the positive infinity.

It is equivalent to theINFINITY macro from the C11 standard<math.h> header.

Deprecated since version 3.15:The macro issoft deprecated.

Py_NAN

This macro expands to a constant expression of typedouble, thatrepresents a quiet not-a-number (qNaN) value.

On most platforms, this is equivalent to theNAN macro fromthe C11 standard<math.h> header.

Py_HUGE_VAL

Equivalent toINFINITY.

Deprecated since version 3.14:The macro issoft deprecated.

Py_MATH_E

The definition (accurate for adouble type) of themath.e constant.

Py_MATH_El

High precision (long double) definition ofe constant.

Deprecated since version 3.15, will be removed in version 3.20.

Py_MATH_PI

The definition (accurate for adouble type) of themath.pi constant.

Py_MATH_PIl

High precision (long double) definition ofpi constant.

Deprecated since version 3.15, will be removed in version 3.20.

Py_MATH_TAU

The definition (accurate for adouble type) of themath.tau constant.

Added in version 3.6.

Py_RETURN_NAN

Returnmath.nan from a function.

On most platforms, this is equivalent toreturnPyFloat_FromDouble(NAN).

Py_RETURN_INF(sign)

Returnmath.inf or-math.inf from a function,depending on the sign ofsign.

On most platforms, this is equivalent to the following:

returnPyFloat_FromDouble(copysign(INFINITY,sign));
Py_IS_FINITE(X)

Return1 if the given floating-point numberX is finite,that is, it is normal, subnormal or zero, but not infinite or NaN.Return0 otherwise.

Deprecated since version 3.14:The macro issoft deprecated. Useisfinite instead.

Py_IS_INFINITY(X)

Return1 if the given floating-point numberX is positive or negativeinfinity. Return0 otherwise.

Deprecated since version 3.14:The macro issoft deprecated. Useisinf instead.

Py_IS_NAN(X)

Return1 if the given floating-point numberX is a not-a-number (NaN)value. Return0 otherwise.

Deprecated since version 3.14:The macro issoft deprecated. Useisnan instead.

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:

  • The 2-byte format is the IEEE 754 binary16 half-precision format.

  • The 4-byte format is the IEEE 754 binary32 single-precision format.

  • The 8-byte format is the IEEE 754 binary64 double-precision format.

The NaN type may not be preserved on some platforms while unpacking (signalingNaNs become quiet NaNs), for example on x86 systems in 32-bit mode.

It’s assumed that thedouble type has the IEEE 754 binary64 doubleprecision format. What happens if it’s not true is partly accidental (alas).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. Thepacking of special numbers like INFs and NaNs (if such things exist on theplatform) may not be handled correctly, and attempting to unpack a bytes stringcontaining an IEEE INF or NaN may raise an exception.

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+6 andp+7), zero if youwant big-endian format (exponent first, atp). Use thePY_LITTLE_ENDIANconstant to select the native endian: it is equal to0 on bigendian processor, or1 on little endian processor.

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

intPyFloat_Pack2(doublex,char*p,intle)

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

intPyFloat_Pack4(doublex,char*p,intle)

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

intPyFloat_Pack8(doublex,char*p,intle)

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

CPython implementation detail: This function always succeeds in CPython.

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). Use thePY_LITTLE_ENDIAN constant toselect the native endian: it is equal to0 on big endian processor, or1on 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).

CPython implementation detail: These functions always succeed in CPython.

doublePyFloat_Unpack2(constchar*p,intle)

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

doublePyFloat_Unpack4(constchar*p,intle)

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

doublePyFloat_Unpack8(constchar*p,intle)

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