iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 757: edits, based on C-API WG feedback (#4026) 

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
This commit is contained in:
Sergey B Kirpichev 2024-10-15 12:43:41 +03:00 committed by GitHub
parent 388568986b
commit 68413fa107
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 22 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
peps/pep-0757.rst
View File

@ -49,14 +49,19 @@ Specification
Layout API
----------
Data needed by `GMP <https://gmplib.org/>`_-like import-export functions.
Data needed by `GMP <https://gmplib.org/>`_-like `import
<https://gmplib.org/manual/Integer-Import-and-Export#index-mpz_005fimport>`_-`export
<https://gmplib.org/manual/Integer-Import-and-Export#index-mpz_005fexport>`_
functions.
.. c:struct:: PyLongLayout
Layout of an array of digits, used by Python :class:`int` object.
Layout of an array of "digits" ("limbs" in the GMP terminology), used to
represent absolute value for arbitrary precision integers.
Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python
:class:`int` objects.
:class:`int` objects, used internally for integers with "big enough"
absolute value.
See also :data:`sys.int_info` which exposes similar information to Python.
@ -148,8 +153,9 @@ Export API
If *export_long->digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must be
called when the export is no longer needed.
On CPython 3.14, no memory copy is needed, it's just a thin wrapper to
expose Python int internal digits array.
On CPython 3.14, no memory copy is needed in :c:func:`PyLong_Export`, it's just
a thin wrapper to expose Python :class:`int` internal digits array.
.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
@ -167,7 +173,8 @@ create a Python :class:`int` object from a digits array.
A Python :class:`int` writer instance.
The instance must be destroyed by :c:func:`PyLongWriter_Finish`.
The instance must be destroyed by :c:func:`PyLongWriter_Finish` or
:c:func:`PyLongWriter_Discard`.
.. c:function:: PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
@ -182,13 +189,15 @@ create a Python :class:`int` object from a digits array.
*ndigits* is the number of digits in the *digits* array. It must be
greater than or equal to 0.
The caller must initialize the array of digits *digits* and then call
:c:func:`PyLongWriter_Finish` to get a Python :class:`int`. Digits must be
in the range [``0``; ``(1 << sys.int_info.bits_per_digit) - 1``]. Unused digits must
be set to ``0``.
The caller can either initialize the array of digits *digits* and then call
:c:func:`PyLongWriter_Finish` to get a Python :class:`int`, or call
:c:func:`PyLongWriter_Discard` to destroy the writer instance. Digits must
be in the range [``0``; ``(1 << sys.int_info.bits_per_digit) - 1``]. Unused
digits must be set to ``0``.
On CPython 3.14, the implementation is a thin wrapper to the private
:c:func:`!_PyLong_New()` function.
On CPython 3.14, the :c:func:`PyLongWriter_Create` implementation is a thin
wrapper to the private :c:func:`!_PyLong_New()` function.
.. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
@ -204,7 +213,7 @@ create a Python :class:`int` object from a digits array.
.. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
Discard the internal object and destroy the writer instance.
Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
Optimize import for small integers