@@ -76,3 +76,89 @@ Floating Point Objects
76
76
.. c:function:: double PyFloat_GetMin()
77
77
78
78
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
79
+
80
+
81
+ Pack and Unpack functions
82
+ =========================
83
+
84
+ The pack and unpack functions provide an efficient platform-independent way to
85
+ store floating-point values as byte strings. The Pack routines produce a bytes
86
+ string from a C :c:type:`double`, and the Unpack routines produce a C
87
+ :c:type:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
88
+ number of bytes in the bytes string.
89
+
90
+ On platforms that appear to use IEEE 754 formats these functions work by
91
+ copying bits. On other platforms, the 2-byte format is identical to the IEEE
92
+ 754 binary16 half-precision format, the 4-byte format (32-bit) is identical to
93
+ the IEEE 754 binary32 single precision format, and the 8-byte format to the
94
+ IEEE 754 binary64 double precision format, although the packing of INFs and
95
+ NaNs (if such things exist on the platform) isn't handled correctly, and
96
+ attempting to unpack a bytes string containing an IEEE INF or NaN will raise an
97
+ exception.
98
+
99
+ On non-IEEE platforms with more precision, or larger dynamic range, than IEEE
100
+ 754 supports, not all values can be packed; on non-IEEE platforms with less
101
+ precision, or smaller dynamic range, not all values can be unpacked. What
102
+ happens in such cases is partly accidental (alas).
103
+
104
+ .. versionadded:: 3.11
105
+
106
+ Pack functions
107
+ --------------
108
+
109
+ The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
110
+ :c:type:`int` argument, non-zero if you want the bytes string in little-endian
111
+ format (exponent last, at ``p+1 ``, ``p+3 ``, or ``p+6 `` ``p+7 ``), zero if you
112
+ want big-endian format (exponent first, at *p *). The :c:data:`PY_BIG_ENDIAN`
113
+ constant can be used to use the native endian: it is equal to ``1`` on big
114
+ endian processor, or ``0`` on little endian processor.
115
+
116
+ Return value: ``0`` if all is OK, ``-1`` if error (and an exception is set,
117
+ most likely :exc: `OverflowError `).
118
+
119
+ There are two problems on non-IEEE platforms:
120
+
121
+ * What this does is undefined if *x* is a NaN or infinity.
122
+ * ``-0.0`` and ``+0.0`` produce the same bytes string.
123
+
124
+ .. c:function:: int PyFloat_Pack2(double x, unsigned char *p, int le)
125
+
126
+ Pack a C double as the IEEE 754 binary16 half-precision format.
127
+
128
+ .. c :function :: int PyFloat_Pack4 (double x, unsigned char *p, int le)
129
+
130
+ Pack a C double as the IEEE 754 binary32 single precision format.
131
+
132
+ .. c :function :: int PyFloat_Pack8 (double x, unsigned char *p, int le)
133
+
134
+ Pack a C double as the IEEE 754 binary64 double precision format.
135
+
136
+
137
+ Unpack functions
138
+ ----------------
139
+
140
+ The unpack routines read 2, 4 or 8 bytes, starting at *p *. *le * is an
141
+ :c:type: `int ` argument, non-zero if the bytes string is in little-endian format
142
+ (exponent last, at ``p+1 ``, ``p+3 `` or ``p+6 `` and ``p+7 ``), zero if big-endian
143
+ (exponent first, at *p *). The :c:data:`PY_BIG_ENDIAN` constant can be used to
144
+ use the native endian: it is equal to ``1`` on big endian processor, or ``0``
145
+ on little endian processor.
146
+
147
+ Return value: The unpacked double. On error, this is ``-1.0`` and
148
+ :c:func:`PyErr_Occurred` is true (and an exception is set, most likely
149
+ :exc: `OverflowError `).
150
+
151
+ Note that on a non-IEEE platform this will refuse to unpack a bytes string that
152
+ represents a NaN or infinity.
153
+
154
+ .. c:function:: double PyFloat_Unpack2(const unsigned char *p, int le)
155
+
156
+ Unpack the IEEE 754 binary16 half-precision format as a C double.
157
+
158
+ .. c :function :: double PyFloat_Unpack4 (const unsigned char *p, int le)
159
+
160
+ Unpack the IEEE 754 binary32 single precision format as a C double.
161
+
162
+ .. c :function :: double PyFloat_Unpack8 (const unsigned char *p, int le)
163
+
164
+ Unpack the IEEE 754 binary64 double precision format as a C double.
0 commit comments