@@ -113,6 +113,28 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
113
113
retrieved from the resulting value using :c:func: `PyLong_AsVoidPtr `.
114
114
115
115
116
+ .. c :function :: PyObject* PyLong_FromNativeBytes (const void* buffer, size_t n_bytes, int endianness)
117
+
118
+ Create a Python integer from the value contained in the first *n_bytes* of
119
+ *buffer*, interpreted as a two's-complement signed number.
120
+
121
+ *endianness* may be passed ``-1`` for the native endian that CPython was
122
+ compiled with, or else ``0`` for big endian and ``1`` for little.
123
+
124
+ .. versionadded:: 3.13
125
+
126
+
127
+ .. c:function:: PyObject* PyLong_FromUnsignedNativeBytes(const void* buffer, size_t n_bytes, int endianness)
128
+
129
+ Create a Python integer from the value contained in the first *n_bytes* of
130
+ *buffer*, interpreted as an unsigned number.
131
+
132
+ *endianness* may be passed ``-1`` for the native endian that CPython was
133
+ compiled with, or else ``0`` for big endian and ``1`` for little.
134
+
135
+ .. versionadded:: 3.13
136
+
137
+
116
138
.. XXX alias PyLong_AS_LONG (for now)
117
139
.. c:function:: long PyLong_AsLong(PyObject *obj)
118
140
@@ -332,6 +354,54 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
332
354
Returns ``NULL `` on error. Use :c:func: `PyErr_Occurred ` to disambiguate.
333
355
334
356
357
+ .. c :function :: Py_ssize_t PyLong_AsNativeBytes (PyObject *pylong, void * buffer, Py_ssize_t n_bytes, int endianness)
358
+
359
+ Copy the Python integer value to a native *buffer* of size *n_bytes*::
360
+
361
+ int value;
362
+ Py_ssize_t bytes = PyLong_AsNativeBytes(v, &value, sizeof (value), -1 );
363
+ if (bytes < 0 ) {
364
+ // Error occurred
365
+ return NULL;
366
+ }
367
+ else if (bytes <= (Py_ssize_t)sizeof (value)) {
368
+ // Success!
369
+ }
370
+ else {
371
+ // Overflow occurred, but 'value' contains truncated value
372
+ }
373
+
374
+ *endianness * may be passed ``-1 `` for the native endian that CPython was
375
+ compiled with, or ``0 `` for big endian and ``1 `` for little.
376
+
377
+ Return ``-1 `` with an exception raised if *pylong * cannot be interpreted as
378
+ an integer. Otherwise, return the size of the buffer required to store the
379
+ value. If this is equal to or less than *n_bytes *, the entire value was
380
+ copied.
381
+
382
+ Unless an exception is raised, all *n_bytes * of the buffer will be written
383
+ with as much of the value as can fit. This allows the caller to ignore all
384
+ non-negative results if the intent is to match the typical behavior of a
385
+ C-style downcast. No exception is set for this case.
386
+
387
+ Values are always copied as two's-complement, and sufficient buffer will be
388
+ requested to include a sign bit. For example, this may cause an value that
389
+ fits into 8 bytes when treated as unsigned to request 9 bytes, even though
390
+ all eight bytes were copied into the buffer. What has been omitted is the
391
+ zero sign bit, which is redundant when the intention is to treat the value as
392
+ unsigned.
393
+
394
+ Passing zero to *n_bytes * will return the requested buffer size.
395
+
396
+ .. note ::
397
+
398
+ When the value does not fit in the provided buffer, the requested size
399
+ returned from the function may be larger than necessary. Passing 0 to this
400
+ function is not an accurate way to determine the bit length of a value.
401
+
402
+ .. versionadded :: 3.13
403
+
404
+
335
405
.. c :function :: int PyUnstable_Long_IsCompact (const PyLongObject* op)
336
406
337
407
Return 1 if *op* is compact, 0 otherwise.
0 commit comments