Debian Codegraph @

Doc/c-api/float.rst

raw
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.