Skip to content

Commit 5e53a5b

Browse files
authored
Sync implementation with PEP (#8)
1 parent 167d75e commit 5e53a5b

File tree

5 files changed

+26
-20
lines changed

5 files changed

+26
-20
lines changed

Doc/c-api/long.rst

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -619,10 +619,12 @@ Export API
619619
620620
.. c:struct:: PyLongLayout
621621
622-
Layout of an array of digits, used by Python :class:`int` object.
622+
Layout of an array of "digits" ("limbs" in the GMP terminology), used to
623+
represent absolute value for arbitrary precision integers.
623624
624625
Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python
625-
:class:`int` objects.
626+
:class:`int` objects, used internally for integers with "big enough"
627+
absolute value.
626628
627629
See also :data:`sys.int_info` which exposes similar information to Python.
628630
@@ -655,6 +657,11 @@ Export API
655657
656658
See the :c:struct:`PyLongLayout` structure.
657659
660+
The function must not be called before Python initialization nor after
661+
Python finalization. The returned layout is valid until Python is
662+
finalized. The layout is the same for all Python sub-interpreters and
663+
so it can be cached.
664+
658665
659666
.. c:struct:: PyLongExport
660667
@@ -695,9 +702,6 @@ Export API
695702
On success, set *\*export_long* and return 0.
696703
On error, set an exception and return -1.
697704
698-
This function always succeeds if *obj* is a Python :class:`int` object or a
699-
subclass.
700-
701705
If *export_long.digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must be
702706
called when the export is no longer needed.
703707
@@ -718,7 +722,8 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
718722
719723
A Python :class:`int` writer instance.
720724
721-
The instance must be destroyed by :c:func:`PyLongWriter_Finish`.
725+
The instance must be destroyed by :c:func:`PyLongWriter_Finish` or
726+
:c:func:`PyLongWriter_Discard`.
722727
723728
724729
.. c:function:: PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
@@ -733,10 +738,11 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
733738
*ndigits* is the number of digits in the *digits* array. It must be
734739
greater than or equal to 0.
735740
736-
The caller must initialize the array of digits *digits* and then call
737-
:c:func:`PyLongWriter_Finish` to get a Python :class:`int`. Digits must be
738-
in the range [``0``; ``PyLong_BASE - 1``]. Unused digits must be set to
739-
``0``.
741+
The caller can either initialize the array of digits *digits* and then call
742+
:c:func:`PyLongWriter_Finish` to get a Python :class:`int`, or call
743+
:c:func:`PyLongWriter_Discard` to destroy the writer instance. Digits must
744+
be in the range [``0``; ``(1 << sys.int_info.bits_per_digit) - 1``]. Unused
745+
digits must be set to ``0``.
740746
741747
742748
.. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
@@ -749,4 +755,4 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
749755
750756
.. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
751757
752-
Discard the internal object and destroy the writer instance.
758+
Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.

Include/cpython/longintrepr.h

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -148,15 +148,15 @@ typedef struct PyLongLayout {
148148
// Digit size in bytes
149149
uint8_t digit_size;
150150

151-
// Word endian:
152-
// * 1 for most significant word first (big endian)
153-
// * -1 for least significant first (little endian)
151+
// Digits order:
152+
// * 1 for most significant digit first
153+
// * -1 for least significant first
154154
int8_t digits_order;
155155

156-
// Array endian:
156+
// Digit endianness:
157157
// * 1 for most significant byte first (big endian)
158158
// * -1 for least significant first (little endian)
159-
int8_t endian;
159+
int8_t endianness;
160160
} PyLongLayout;
161161

162162
PyAPI_FUNC(const PyLongLayout*) PyLong_GetNativeLayout(void);

Lib/test/test_capi/test_long.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -678,7 +678,7 @@ def test_long_layout(self):
678678
'bits_per_digit': int_info.bits_per_digit,
679679
'digit_size': int_info.sizeof_digit,
680680
'digits_order': -1,
681-
'endian': -1 if sys.byteorder == 'little' else 1,
681+
'endianness': -1 if sys.byteorder == 'little' else 1,
682682
}
683683
self.assertEqual(layout, expected)
684684

Modules/_testcapi/long.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -155,11 +155,11 @@ layout_to_dict(const PyLongLayout *layout)
155155
goto error;
156156
}
157157

158-
value = PyLong_FromLong(layout->endian);
158+
value = PyLong_FromLong(layout->endianness);
159159
if (value == NULL) {
160160
goto error;
161161
}
162-
res = PyDict_SetItemString(dict, "endian", value);
162+
res = PyDict_SetItemString(dict, "endianness", value);
163163
Py_DECREF(value);
164164
if (res < 0) {
165165
goto error;

Objects/longobject.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6779,7 +6779,7 @@ int PyLong_AsUInt64(PyObject *obj, uint64_t *value)
67796779
static const PyLongLayout PyLong_LAYOUT = {
67806780
.bits_per_digit = PyLong_SHIFT,
67816781
.digits_order = -1, // least significant first
6782-
.endian = PY_LITTLE_ENDIAN ? -1 : 1,
6782+
.endianness = PY_LITTLE_ENDIAN ? -1 : 1,
67836783
.digit_size = sizeof(digit),
67846784
};
67856785

0 commit comments

Comments
 (0)