PyLong_Export API returns PyLongExport_Kind

Author: skirpichev

Doc/c-api/long.rst

@@ -619,7 +619,8 @@ Export API
 
 .. c:struct:: PyLongLayout
 
-   Layout of an array of digits, used by Python :class:`int` object.
+   Layout of an array of digits, used by Python :class:`int` object to
+   represent "big enough" integers.
 
    Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python
    :class:`int` objects.
@@ -641,7 +642,7 @@ Export API
       - ``1`` for most significant digit first
       - ``-1`` for least significant digit first
 
-   .. c:member:: int8_t endian
+   .. c:member:: int8_t endianness
 
       Digit endianness:
 
@@ -655,56 +656,60 @@ Export API
 
    See the :c:struct:`PyLongLayout` structure.
 
+   The function must not be called before Python initialization nor after
+   Python finalization. The returned layout is valid until Python is
+   finalized. The layout is the same for all Python sub-interpreters and
+   so it can be cached.
 
-.. c:struct:: PyLongExport
 
-   Export of a Python :class:`int` object.
+.. c:type:: PyLongExport_Kind
+
+    The enum value used to represent different results of
+    :c:func:`PyLong_Export`.
+
 
-   There are two cases:
+.. c:struct:: PyLongExport
 
-   * If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member.
-     Calling :c:func:`PyLong_FreeExport` is optional in this case.
-   * If :c:member:`digits` is not ``NULL``, use :c:member:`negative`,
-     :c:member:`ndigits` and :c:member:`digits` members.
-     Calling :c:func:`PyLong_FreeExport` is mandatory in this case.
+   Export of a Python :class:`int` object.
 
-   .. c:member:: int64_t value
+   .. c:struct:: digit_array
 
-      The native integer value of the exported :class:`int` object.
-      Only valid if :c:member:`digits` is ``NULL``.
+      Export an integer as an array of digits; corresponds to
+      ``PyLongExport_DigitArray`` value of the enum
+      :c:type:`PyLongExport_Kind`.
 
-   .. c:member:: uint8_t negative
+      .. c:member:: Py_ssize_t ndigits
 
-      1 if the number is negative, 0 otherwise.
-      Only valid if :c:member:`digits` is not ``NULL``.
+         Number of digits in :c:member:`digits` array.
 
-   .. c:member:: Py_ssize_t ndigits
+      .. c:member:: const void *digits
 
-      Number of digits in :c:member:`digits` array.
-      Only valid if :c:member:`digits` is not ``NULL``.
+         Read-only array of unsigned digits.
 
-   .. c:member:: const void *digits
+      .. c:member:: uint8_t negative
 
-      Read-only array of unsigned digits. Can be ``NULL``.
+         1 if the number is negative, 0 otherwise.
 
 
-.. c:function:: int PyLong_Export(PyObject *obj, PyLongExport *export_long)
+.. c:function:: PyLongExport_Kind PyLong_Export(PyObject *obj, PyLongExport *export)
 
    Export a Python :class:`int` object.
 
-   On success, set *\*export_long* and return 0.
-   On error, set an exception and return -1.
+   On success, set *\*export* and return an appropriate export type
+   for the given value, see the :c:struct:`PyLongExport` struct.
+   :c:func:`PyLong_FreeExport` must be called when the export is no
+   longer needed.  Currently the only available type is
+   ``PyLongExport_DigitArray``.
+
+   On error, set an exception and return ``PyLongExport_Error``.
 
    This function always succeeds if *obj* is a Python :class:`int` object or a
    subclass.
 
-   If *export_long.digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must be
-   called when the export is no longer needed.
-
 
-.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
+.. c:function:: void PyLong_FreeExport(PyLongExport *export)
 
-   Release the export *export_long* created by :c:func:`PyLong_Export`.
+   Release the *export* created by :c:func:`PyLong_Export`.
 
 
 PyLongWriter API

Include/cpython/longintrepr.h

@@ -148,29 +148,37 @@ typedef struct PyLongLayout {
     // Digit size in bytes
     uint8_t digit_size;
 
-    // Word endian:
-    // * 1 for most significant word first (big endian)
+    // Digits order:
+    // * 1 for most significant digit first (big endian)
     // * -1 for least significant first (little endian)
     int8_t digits_order;
 
-    // Array endian:
+    // Digit endianness:
     // * 1 for most significant byte first (big endian)
     // * -1 for least significant first (little endian)
-    int8_t endian;
+    int8_t endianness;
 } PyLongLayout;
 
 PyAPI_FUNC(const PyLongLayout*) PyLong_GetNativeLayout(void);
 
+typedef enum {
+    PyLongExport_Error = -1,
+    PyLongExport_DigitArray = 0,
+} PyLongExport_Kind;
+
 typedef struct PyLongExport {
-    int64_t value;
-    uint8_t negative;
-    Py_ssize_t ndigits;
-    const void *digits;
     // Member used internally, must not be used for other purpose.
     Py_uintptr_t _reserved;
+    union {
+        struct {
+            Py_ssize_t ndigits;
+            const void *digits;
+            uint8_t negative;
+        } digit_array;
+    };
 } PyLongExport;
 
-PyAPI_FUNC(int) PyLong_Export(
+PyAPI_FUNC(PyLongExport_Kind) PyLong_Export(
     PyObject *obj,
     PyLongExport *export_long);
 PyAPI_FUNC(void) PyLong_FreeExport(

Lib/test/test_capi/test_long.py

@@ -678,7 +678,7 @@ def test_long_layout(self):
             'bits_per_digit': int_info.bits_per_digit,
             'digit_size': int_info.sizeof_digit,
             'digits_order': -1,
-            'endian': -1 if sys.byteorder == 'little' else 1,
+            'endianness': -1 if sys.byteorder == 'little' else 1,
         }
         self.assertEqual(layout, expected)
 
@@ -689,12 +689,9 @@ def test_long_export(self):
 
         pylong_export = _testcapi.pylong_export
 
-        # value fits into int64_t
-        self.assertEqual(pylong_export(0), 0)
-        self.assertEqual(pylong_export(123), 123)
-        self.assertEqual(pylong_export(-123), -123)
-
-        # use an array, doesn't fit into int64_t
+        self.assertEqual(pylong_export(0), (0, [0]))
+        self.assertEqual(pylong_export(123), (0, [123]))
+        self.assertEqual(pylong_export(-123), (1, [123]))
         self.assertEqual(pylong_export(base**10 * 2 + 1),
                          (0, [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2]))
         self.assertEqual(pylong_export(-(base**10 * 2 + 1)),

Modules/_testcapi/long.c

@@ -155,11 +155,11 @@ layout_to_dict(const PyLongLayout *layout)
         goto error;
     }
 
-    value = PyLong_FromLong(layout->endian);
+    value = PyLong_FromLong(layout->endianness);
     if (value == NULL) {
         goto error;
     }
-    res = PyDict_SetItemString(dict, "endian", value);
+    res = PyDict_SetItemString(dict, "endianness", value);
     Py_DECREF(value);
     if (res < 0) {
         goto error;
@@ -177,20 +177,15 @@ static PyObject *
 pylong_export(PyObject *module, PyObject *obj)
 {
     PyLongExport export_long;
-    if (PyLong_Export(obj, &export_long) < 0) {
+    if (PyLong_Export(obj, &export_long) == PyLongExport_Error) {
         return NULL;
     }
 
-    if (export_long.digits == NULL) {
-        return PyLong_FromInt64(export_long.value);
-        // PyLong_FreeExport() is not needed in this case
-    }
-
     assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
-    const digit *export_long_digits = export_long.digits;
+    const digit *export_long_digits = export_long.digit_array.digits;
 
     PyObject *digits = PyList_New(0);
-    for (Py_ssize_t i=0; i < export_long.ndigits; i++) {
+    for (Py_ssize_t i=0; i < export_long.digit_array.ndigits; i++) {
         PyObject *item = PyLong_FromUnsignedLong(export_long_digits[i]);
         if (item == NULL) {
             goto error;
@@ -203,7 +198,8 @@ pylong_export(PyObject *module, PyObject *obj)
         Py_DECREF(item);
     }
 
-    PyObject *res = Py_BuildValue("(iN)", export_long.negative, digits);
+    PyObject *res = Py_BuildValue("(iN)", export_long.digit_array.negative,
+                                  digits);
 
     PyLong_FreeExport(&export_long);
     assert(export_long._reserved == 0);

Objects/longobject.c

@@ -6779,7 +6779,7 @@ int PyLong_AsUInt64(PyObject *obj, uint64_t *value)
 static const PyLongLayout PyLong_LAYOUT = {
     .bits_per_digit = PyLong_SHIFT,
     .digits_order = -1,  // least significant first
-    .endian = PY_LITTLE_ENDIAN ? -1 : 1,
+    .endianness = PY_LITTLE_ENDIAN ? -1 : 1,
     .digit_size = sizeof(digit),
 };
 
@@ -6790,45 +6790,23 @@ const PyLongLayout* PyLong_GetNativeLayout(void)
 }
 
 
-int
+PyLongExport_Kind
 PyLong_Export(PyObject *obj, PyLongExport *export_long)
 {
     if (!PyLong_Check(obj)) {
         PyErr_Format(PyExc_TypeError, "expect int, got %T", obj);
-        return -1;
+        return PyLongExport_Error;
     }
 
-    // Fast-path: try to convert to a int64_t
-    int overflow;
-#if SIZEOF_LONG == 8
-    long value = PyLong_AsLongAndOverflow(obj, &overflow);
-#else
-    // Windows has 32-bit long, so use 64-bit long long instead
-    long long value = PyLong_AsLongLongAndOverflow(obj, &overflow);
-#endif
-    Py_BUILD_ASSERT(sizeof(value) == sizeof(int64_t));
-    // the function cannot fail since obj is a PyLongObject
-    assert(!(value == -1 && PyErr_Occurred()));
-
-    if (!overflow) {
-        export_long->value = value;
-        export_long->negative = 0;
-        export_long->ndigits = 0;
-        export_long->digits = 0;
-        export_long->_reserved = 0;
+    PyLongObject *self = (PyLongObject*)obj;
+    export_long->digit_array.negative = _PyLong_IsNegative(self);
+    export_long->digit_array.ndigits = _PyLong_DigitCount(self);
+    if (export_long->digit_array.ndigits == 0) {
+        export_long->digit_array.ndigits = 1;
     }
-    else {
-        PyLongObject *self = (PyLongObject*)obj;
-        export_long->value = 0;
-        export_long->negative = _PyLong_IsNegative(self);
-        export_long->ndigits = _PyLong_DigitCount(self);
-        if (export_long->ndigits == 0) {
-            export_long->ndigits = 1;
-        }
-        export_long->digits = self->long_value.ob_digit;
-        export_long->_reserved = (Py_uintptr_t)Py_NewRef(obj);
-    }
-    return 0;
+    export_long->digit_array.digits = self->long_value.ob_digit;
+    export_long->_reserved = (Py_uintptr_t)Py_NewRef(obj);
+    return PyLongExport_DigitArray;
 }