8000 Remove Py_digit type; update the doc · python/cpython@4aa25f6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4aa25f6

Browse files
vstinnervstinner
committed
Remove Py_digit type; update the doc
1 parent d70a121 commit 4aa25f6

File tree

5 files changed

+44
-67
lines changed

5 files changed

+44
-67
lines changed

‎Doc/c-api/long.rst

Lines changed: 23 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -615,21 +615,6 @@ Export API
615615
616616
.. versionadded:: 3.14
617617
618-
.. c:type:: Py_digit
619-
620-
A single unsigned digit in the range [``0``; ``PyLong_BASE - 1``].
621-
622-
It is usually used in an *array of digits*, such as the
623-
:c:member:`PyLong_DigitArray.digits` array.
624-
625-
Its size depend on the :c:macro:`!PYLONG_BITS_IN_DIGIT` macro:
626-
see the ``configure`` :option:`--enable-big-digits` option.
627-
628-
See :c:member:`PyLongLayout.bits_per_digit` for the number of bits per
629-
digit and :c:member:`PyLongLayout.digit_size` for the size of a digit (in
630-
bytes).
631-
632-
633618
.. c:struct:: PyLongLayout
634619
635620
Layout of an array of digits, used by Python :class:`int` object.
@@ -669,11 +654,23 @@ Export API
669654
See the :c:struct:`PyLongLayout` structure.
670655
671656
672-
.. c:struct:: PyLong_DigitArray
657+
.. c:struct:: PyLongExport
658+
659+
Export of a Python :class:`int` object.
673660
674-
A Python :class:`int` object exported as an array of digits.
661+
There are two cases:
675662
676-
.. c:member:: int negative
663+
* If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member.
664+
Calling :c:func:`PyLong_FreeExport` is optional in this case.
665+
* If :c:member:`digits` is not ``NULL``, use :c:member:`negative`,
666+
:c:member:`ndigits` and :c:member:`digits` members.
667+
Calling :c:func:`PyLong_FreeExport` is mandatory in this case.
668+
669+
.. c:member:: int64_t value
670+
671+
Integer value if :c:member:`digits` is ``NULL``.
672+
673+
.. c:member:: uint8_t negative
677674
678675
1 if the number is negative, 0 otherwise.
679676
@@ -683,26 +680,26 @@ Export API
683680
684681
.. c:member:: const void *digits
685682
686-
Read-only array of unsigned digits.
683+
Read-only array of unsigned digits. Can be ``NULL``.
687684
688685
689-
.. c:function:: int PyLong_Export(PyObject *obj, PyLong_DigitArray *array)
686+
.. c:function:: int PyLong_Export(PyObject *obj, PyLongExport *export_long)
690687
691-
Export a Python :class:`int` object as an array of digits.
688+
Export a Python :class:`int` object.
692689
693-
On success, set *\*array* and return 0.
690+
On success, set *\*export_long* and return 0.
694691
On error, set an exception and return -1.
695692
696693
This function always succeeds if *obj* is a Python :class:`int` object or a
697694
subclass.
698695
699-
:c:func:`PyLong_FreeExport` must be called once done with using
700-
*array*.
696+
If *export_long.digits* is not ``NULL, :c:func:`PyLong_FreeExport` must be
697+
called when the export is no longer needed.
701698
702699
703-
.. c:function:: void PyLong_FreeExport(PyLong_DigitArray *array)
700+
.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
704701
705-
Release the export *array* created by :c:func:`PyLong_Export`.
702+
Release the export *export_long* created by :c:func:`PyLong_Export`.
706703
707704
708705
PyLongWriter API
@@ -748,21 +745,3 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
748745
.. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
749746
750747
Discard the internal object and destroy the writer instance.
751-
752-
753-
Example creating an integer from an array of digits::
754-
755-
PyObject *
756-
long_import(int negative, Py_ssize_t ndigits, Py_digit *digits)
757-
{
758-
void *writer_digits;
759-
PyLongWriter *writer = PyLongWriter_Create(negative, ndigits,
760-
&writer_digits);
761-
if (writer == NULL) {
762-
return NULL;
763-
}
764-
765-
assert(layout.digit_size == sizeof(Py_digit));
766-
memcpy(writer_digits, digits, ndigits * sizeof(Py_digit));
767-
return PyLongWriter_Finish(writer);
768-
}

‎Doc/whatsnew/3.14.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -531,8 +531,8 @@ New Features
531531
* Add a new import and export API for Python :class:`int` objects:
532532

533533
* :c:func:`PyLong_GetNativeLayout`;
534-
* :c:func:`PyLong_AsDigitArray`;
535-
* :c:func:`PyLong_FreeDigitArray`;
534+
* :c:func:`PyLong_Export`;
535+
* :c:func:`PyLong_FreeExport`;
536536
* :c:func:`PyLongWriter_Create`;
537537
* :c:func:`PyLongWriter_Finish`;
538538
* :c:func:`PyLongWriter_Discard`.

‎Include/cpython/longintrepr.h

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,8 @@ typedef long stwodigits; /* signed variant of twodigits */
5858
#else
5959
#error "PYLONG_BITS_IN_DIGIT should be 15 or 30"
6060
#endif
61-
#define PyLong_BASE ((Py_digit)1 << PyLong_SHIFT)
62-
#define PyLong_MASK ((Py_digit)(PyLong_BASE - 1))
63-
64-
typedef digit Py_digit;
61+
#define PyLong_BASE ((digit)1 << PyLong_SHIFT)
62+
#define PyLong_MASK ((digit)(PyLong_BASE - 1))
6563

6664
/* Long integer representation.
6765

‎Misc/NEWS.d/next/C API/2024-07-03-17-26-53.gh-issue-102471.XpmKYk.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
Add a new import and export API for Python :class:`int` objects:
22

33
* :c:func:`PyLong_GetNativeLayout`;
4-
* :c:func:`PyLong_AsDigitArray`;
5-
* :c:func:`PyLong_FreeDigitArray`;
4+
* :c:func:`PyLong_Export`;
5+
* :c:func:`PyLong_FreeExport`;
66
* :c:func:`PyLongWriter_Create`;
77
* :c:func:`PyLongWriter_Finish`;
88
* :c:func:`PyLongWriter_Discard`.

‎Modules/_testcapi/long.c

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -186,21 +186,21 @@ pylong_export(PyObject *module, PyObject *obj)
186186
// PyLong_FreeExport() is not needed in this case
187187
}
188188

189-
assert(PyLong_GetNativeLayout()->digit_size == sizeof(Py_digit));
190-
const Py_digit *export_long_digits = export_long.digits;
189+
assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
190+
const digit *export_long_digits = export_long.digits;
191191

192192
PyObject *digits = PyList_New(0);
193193
for (Py_ssize_t i=0; i < export_long.ndigits; i++) {
194-
PyObject *digit = PyLong_FromUnsignedLong(export_long_digits[i]);
195-
if (digit == NULL) {
194+
PyObject *item = PyLong_FromUnsignedLong(export_long_digits[i]);
195+
if (item == NULL) {
196196
goto error;
197197
}
198198

199-
if (PyList_Append(digits, digit) < 0) {
200-
Py_DECREF(digit);
199+
if (PyList_Append(digits, item) < 0) {
200+
Py_DECREF(item);
201201
goto error;
202202
}
203-
Py_DECREF(digit);
203+
Py_DECREF(item);
204204
}
205205

206206
PyObject *res = Py_BuildValue("(iN)", export_long.negative, digits);
@@ -230,7 +230,7 @@ pylongwriter_create(PyObject *module, PyObject *args)
230230
}
231231
Py_ssize_t ndigits = PyList_GET_SIZE(list);
232232

233-
Py_digit *digits = PyMem_Malloc(ndigits * sizeof(Py_digit));
233+
digit *digits = PyMem_Malloc(ndigits * sizeof(digit));
234234
if (digits == NULL) {
235235
PyErr_NoMemory();
236236
return NULL;
@@ -239,16 +239,16 @@ pylongwriter_create(PyObject *module, PyObject *args)
239239
for (Py_ssize_t i=0; i < ndigits; i++) {
240240
PyObject *item = PyList_GET_ITEM(list, i);
241241

242-
long digit = PyLong_AsLong(item);
243-
if (digit == -1 && PyErr_Occurred()) {
242+
long num = PyLong_AsLong(item);
243+
if (num == -1 && PyErr_Occurred()) {
244244
goto error;
245245
}
246246

247-
if (digit < 0 || digit >= PyLong_BASE) {
248-
PyErr_SetString(PyExc_ValueError, "digit doesn't fit into Py_digit");
247+
if (num < 0 || num >= PyLong_BASE) {
248+
PyErr_SetString(PyExc_ValueError, "digit doesn't fit into digit");
249249
goto error;
250250
}
251-
digits[i] = (Py_digit)digit;
251+
digits[i] = (digit)num;
252252
}
253253

254254
void *writer_digits;
@@ -257,8 +257,8 @@ pylongwriter_create(PyObject *module, PyObject *args)
257257
if (writer == NULL) {
258258
goto error;
259259
}
260-
assert(PyLong_GetNativeLayout()->digit_size == sizeof(Py_digit));
261-
memcpy(writer_digits, digits, ndigits * sizeof(Py_digit));
260+
assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
261+
memcpy(writer_digits, digits, ndigits * sizeof(digit));
262262
PyObject *res = PyLongWriter_Finish(writer);
263263
PyMem_Free(digits);
264264

0 commit comments

Comments
 (0)
0