| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _floatobjects: |
| 4 |
|
| 5 |
Floating-Point Objects |
| 6 |
====================== |
| 7 |
|
| 8 |
.. index:: pair: object; floating-point |
| 9 |
|
| 10 |
|
| 11 |
.. c:type:: PyFloatObject |
| 12 |
|
| 13 |
This subtype of :c:type:`PyObject` represents a Python floating-point object. |
| 14 |
|
| 15 |
|
| 16 |
.. c:var:: PyTypeObject PyFloat_Type |
| 17 |
|
| 18 |
This instance of :c:type:`PyTypeObject` represents the Python floating-point |
| 19 |
type. This is the same object as :class:`float` in the Python layer. |
| 20 |
|
| 21 |
|
| 22 |
.. c:function:: int PyFloat_Check(PyObject *p) |
| 23 |
|
| 24 |
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of |
| 25 |
:c:type:`PyFloatObject`. This function always succeeds. |
| 26 |
|
| 27 |
|
| 28 |
.. c:function:: int PyFloat_CheckExact(PyObject *p) |
| 29 |
|
| 30 |
Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of |
| 31 |
:c:type:`PyFloatObject`. This function always succeeds. |
| 32 |
|
| 33 |
|
| 34 |
.. c:function:: PyObject* PyFloat_FromString(PyObject *str) |
| 35 |
|
| 36 |
Create a :c:type:`PyFloatObject` object based on the string value in *str*, or |
| 37 |
``NULL`` on failure. |
| 38 |
|
| 39 |
|
| 40 |
.. c:function:: PyObject* PyFloat_FromDouble(double v) |
| 41 |
|
| 42 |
Create a :c:type:`PyFloatObject` object from *v*, or ``NULL`` on failure. |
| 43 |
|
| 44 |
|
| 45 |
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat) |
| 46 |
|
| 47 |
Return a C :c:expr:`double` representation of the contents of *pyfloat*. If |
| 48 |
*pyfloat* is not a Python floating-point object but has a :meth:`~object.__float__` |
| 49 |
method, this method will first be called to convert *pyfloat* into a float. |
| 50 |
If :meth:`!__float__` is not defined then it falls back to :meth:`~object.__index__`. |
| 51 |
This method returns ``-1.0`` upon failure, so one should call |
| 52 |
:c:func:`PyErr_Occurred` to check for errors. |
| 53 |
|
| 54 |
.. versionchanged:: 3.8 |
| 55 |
Use :meth:`~object.__index__` if available. |
| 56 |
|
| 57 |
|
| 58 |
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat) |
| 59 |
|
| 60 |
Return a C :c:expr:`double` representation of the contents of *pyfloat*, but |
| 61 |
without error checking. |
| 62 |
|
| 63 |
|
| 64 |
.. c:function:: PyObject* PyFloat_GetInfo(void) |
| 65 |
|
| 66 |
Return a structseq instance which contains information about the |
| 67 |
precision, minimum and maximum values of a float. It's a thin wrapper |
| 68 |
around the header file :file:`float.h`. |
| 69 |
|
| 70 |
|
| 71 |
.. c:function:: double PyFloat_GetMax() |
| 72 |
|
| 73 |
Return the maximum representable finite float *DBL_MAX* as C :c:expr:`double`. |
| 74 |
|
| 75 |
|
| 76 |
.. c:function:: double PyFloat_GetMin() |
| 77 |
|
| 78 |
Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`. |
| 79 |
|
| 80 |
|
| 81 |
.. c:macro:: Py_INFINITY |
| 82 |
|
| 83 |
This macro expands to a constant expression of type :c:expr:`double`, that |
| 84 |
represents the positive infinity. |
| 85 |
|
| 86 |
On most platforms, this is equivalent to the :c:macro:`!INFINITY` macro from |
| 87 |
the C11 standard ``<math.h>`` header. |
| 88 |
|
| 89 |
|
| 90 |
.. c:macro:: Py_NAN |
| 91 |
|
| 92 |
This macro expands to a constant expression of type :c:expr:`double`, that |
| 93 |
represents a quiet not-a-number (qNaN) value. |
| 94 |
|
| 95 |
On most platforms, this is equivalent to the :c:macro:`!NAN` macro from |
| 96 |
the C11 standard ``<math.h>`` header. |
| 97 |
|
| 98 |
|
| 99 |
.. c:macro:: Py_HUGE_VAL |
| 100 |
|
| 101 |
Equivalent to :c:macro:`!INFINITY`. |
| 102 |
|
| 103 |
.. deprecated:: 3.14 |
| 104 |
The macro is :term:`soft deprecated`. |
| 105 |
|
| 106 |
|
| 107 |
.. c:macro:: Py_MATH_E |
| 108 |
|
| 109 |
The definition (accurate for a :c:expr:`double` type) of the :data:`math.e` constant. |
| 110 |
|
| 111 |
|
| 112 |
.. c:macro:: Py_MATH_El |
| 113 |
|
| 114 |
High precision (long double) definition of :data:`~math.e` constant. |
| 115 |
|
| 116 |
|
| 117 |
.. c:macro:: Py_MATH_PI |
| 118 |
|
| 119 |
The definition (accurate for a :c:expr:`double` type) of the :data:`math.pi` constant. |
| 120 |
|
| 121 |
|
| 122 |
.. c:macro:: Py_MATH_PIl |
| 123 |
|
| 124 |
High precision (long double) definition of :data:`~math.pi` constant. |
| 125 |
|
| 126 |
|
| 127 |
.. c:macro:: Py_MATH_TAU |
| 128 |
|
| 129 |
The definition (accurate for a :c:expr:`double` type) of the :data:`math.tau` constant. |
| 130 |
|
| 131 |
.. versionadded:: 3.6 |
| 132 |
|
| 133 |
|
| 134 |
.. c:macro:: Py_RETURN_NAN |
| 135 |
|
| 136 |
Return :data:`math.nan` from a function. |
| 137 |
|
| 138 |
On most platforms, this is equivalent to ``return PyFloat_FromDouble(NAN)``. |
| 139 |
|
| 140 |
|
| 141 |
.. c:macro:: Py_RETURN_INF(sign) |
| 142 |
|
| 143 |
Return :data:`math.inf` or :data:`-math.inf <math.inf>` from a function, |
| 144 |
depending on the sign of *sign*. |
| 145 |
|
| 146 |
On most platforms, this is equivalent to the following:: |
| 147 |
|
| 148 |
return PyFloat_FromDouble(copysign(INFINITY, sign)); |
| 149 |
|
| 150 |
|
| 151 |
.. c:macro:: Py_IS_FINITE(X) |
| 152 |
|
| 153 |
Return ``1`` if the given floating-point number *X* is finite, |
| 154 |
that is, it is normal, subnormal or zero, but not infinite or NaN. |
| 155 |
Return ``0`` otherwise. |
| 156 |
|
| 157 |
.. deprecated:: 3.14 |
| 158 |
The macro is :term:`soft deprecated`. Use :c:macro:`!isfinite` instead. |
| 159 |
|
| 160 |
|
| 161 |
.. c:macro:: Py_IS_INFINITY(X) |
| 162 |
|
| 163 |
Return ``1`` if the given floating-point number *X* is positive or negative |
| 164 |
infinity. Return ``0`` otherwise. |
| 165 |
|
| 166 |
.. deprecated:: 3.14 |
| 167 |
The macro is :term:`soft deprecated`. Use :c:macro:`!isinf` instead. |
| 168 |
|
| 169 |
|
| 170 |
.. c:macro:: Py_IS_NAN(X) |
| 171 |
|
| 172 |
Return ``1`` if the given floating-point number *X* is a not-a-number (NaN) |
| 173 |
value. Return ``0`` otherwise. |
| 174 |
|
| 175 |
.. deprecated:: 3.14 |
| 176 |
The macro is :term:`soft deprecated`. Use :c:macro:`!isnan` instead. |
| 177 |
|
| 178 |
|
| 179 |
Pack and Unpack functions |
| 180 |
------------------------- |
| 181 |
|
| 182 |
The pack and unpack functions provide an efficient platform-independent way to |
| 183 |
store floating-point values as byte strings. The Pack routines produce a bytes |
| 184 |
string from a C :c:expr:`double`, and the Unpack routines produce a C |
| 185 |
:c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the |
| 186 |
number of bytes in the bytes string. |
| 187 |
|
| 188 |
On platforms that appear to use IEEE 754 formats these functions work by |
| 189 |
copying bits. On other platforms, the 2-byte format is identical to the IEEE |
| 190 |
754 binary16 half-precision format, the 4-byte format (32-bit) is identical to |
| 191 |
the IEEE 754 binary32 single precision format, and the 8-byte format to the |
| 192 |
IEEE 754 binary64 double precision format, although the packing of INFs and |
| 193 |
NaNs (if such things exist on the platform) isn't handled correctly, and |
| 194 |
attempting to unpack a bytes string containing an IEEE INF or NaN will raise an |
| 195 |
exception. |
| 196 |
|
| 197 |
Note that NaN type may not be preserved on IEEE platforms (signaling NaNs become |
| 198 |
quiet NaNs), for example on x86 systems in 32-bit mode. |
| 199 |
|
| 200 |
On non-IEEE platforms with more precision, or larger dynamic range, than IEEE |
| 201 |
754 supports, not all values can be packed; on non-IEEE platforms with less |
| 202 |
precision, or smaller dynamic range, not all values can be unpacked. What |
| 203 |
happens in such cases is partly accidental (alas). |
| 204 |
|
| 205 |
.. versionadded:: 3.11 |
| 206 |
|
| 207 |
Pack functions |
| 208 |
^^^^^^^^^^^^^^ |
| 209 |
|
| 210 |
The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an |
| 211 |
:c:expr:`int` argument, non-zero if you want the bytes string in little-endian |
| 212 |
format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` and ``p+7``), zero if you |
| 213 |
want big-endian format (exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` |
| 214 |
constant can be used to use the native endian: it is equal to ``1`` on big |
| 215 |
endian processor, or ``0`` on little endian processor. |
| 216 |
|
| 217 |
Return value: ``0`` if all is OK, ``-1`` if error (and an exception is set, |
| 218 |
most likely :exc:`OverflowError`). |
| 219 |
|
| 220 |
There are two problems on non-IEEE platforms: |
| 221 |
|
| 222 |
* What this does is undefined if *x* is a NaN or infinity. |
| 223 |
* ``-0.0`` and ``+0.0`` produce the same bytes string. |
| 224 |
|
| 225 |
.. c:function:: int PyFloat_Pack2(double x, char *p, int le) |
| 226 |
|
| 227 |
Pack a C double as the IEEE 754 binary16 half-precision format. |
| 228 |
|
| 229 |
.. c:function:: int PyFloat_Pack4(double x, char *p, int le) |
| 230 |
|
| 231 |
Pack a C double as the IEEE 754 binary32 single precision format. |
| 232 |
|
| 233 |
.. c:function:: int PyFloat_Pack8(double x, char *p, int le) |
| 234 |
|
| 235 |
Pack a C double as the IEEE 754 binary64 double precision format. |
| 236 |
|
| 237 |
|
| 238 |
Unpack functions |
| 239 |
^^^^^^^^^^^^^^^^ |
| 240 |
|
| 241 |
The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an |
| 242 |
:c:expr:`int` argument, non-zero if the bytes string is in little-endian format |
| 243 |
(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian |
| 244 |
(exponent first, at *p*). The :c:macro:`PY_BIG_ENDIAN` constant can be used to |
| 245 |
use the native endian: it is equal to ``1`` on big endian processor, or ``0`` |
| 246 |
on little endian processor. |
| 247 |
|
| 248 |
Return value: The unpacked double. On error, this is ``-1.0`` and |
| 249 |
:c:func:`PyErr_Occurred` is true (and an exception is set, most likely |
| 250 |
:exc:`OverflowError`). |
| 251 |
|
| 252 |
Note that on a non-IEEE platform this will refuse to unpack a bytes string that |
| 253 |
represents a NaN or infinity. |
| 254 |
|
| 255 |
.. c:function:: double PyFloat_Unpack2(const char *p, int le) |
| 256 |
|
| 257 |
Unpack the IEEE 754 binary16 half-precision format as a C double. |
| 258 |
|
| 259 |
.. c:function:: double PyFloat_Unpack4(const char *p, int le) |
| 260 |
|
| 261 |
Unpack the IEEE 754 binary32 single precision format as a C double. |
| 262 |
|
| 263 |
.. c:function:: double PyFloat_Unpack8(const char *p, int le) |
| 264 |
|
| 265 |
Unpack the IEEE 754 binary64 double precision format as a C double. |