diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -108,37 +108,56 @@ .. XXX alias PyLong_AS_LONG (for now) -.. c:function:: long PyLong_AsLong(PyObject *pylong) +.. c:function:: long PyLong_AsLong(PyObject *obj) .. index:: single: LONG_MAX single: OverflowError (built-in exception) - Return a C :c:type:`long` representation of the contents of *pylong*. If - *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`, - and return -1. Convert non-long objects automatically to long first, - and return -1 if that raises exceptions. + Return a :c:type:`long` representation of *obj* or ``-1`` on error. + *obj* can be a :c:type:`PyLongObject`, a subtype of :c:type:`PyLongObject` + or any object that implements the :meth:`__int__` method. -.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow) + If *obj* cannot be represented as an integer, raise :exc:`TypeError`. + If *obj* is out of bounds, raise :exc:`OverflowError`. - Return a C :c:type:`long` representation of the contents of - *pylong*. If *pylong* is greater than :const:`LONG_MAX` or less - than :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, - respectively, and return ``-1``; otherwise, set *\*overflow* to - ``0``. If any other exception occurs (for example a TypeError or - MemoryError), then ``-1`` will be returned and *\*overflow* will - be ``0``. +.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow) + Return a :c:type:`long` representation of *obj*. *obj* can be a + :c:type:`PyLongObject`, a subtype of :c:type:`PyLongObject` or + any object that implements the :meth:`__int__` method. -.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow) + If *obj* is greater than :const:`LONG_MAX` or less than :const:`LONG_MIN`, set + *\*overflow* to ``1`` or ``-1``, respectively, and return ``-1``; otherwise, + set *\*overflow* to ``0``. If any other exception occurs (for example a + :exc:`TypeError` or :exc:`MemoryError`), then ``-1`` will be returned and + *\*overflow* will be ``0``. - Return a C :c:type:`long long` representation of the contents of - *pylong*. If *pylong* is greater than :const:`PY_LLONG_MAX` or less - than :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, - respectively, and return ``-1``; otherwise, set *\*overflow* to - ``0``. If any other exception occurs (for example a TypeError or - MemoryError), then ``-1`` will be returned and *\*overflow* will - be ``0``. + +.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *obj) + + .. index:: + single: OverflowError (built-in exception) + + Return a :c:type:`long long` representation of *obj* or ``-1`` on error. + *obj* can be a :c:type:`PyLongObject`, a subtype of :c:type:`PyLongObject` + or any object that implements the :meth:`__int__` method. + + If *obj* cannot be represented as an integer, raise :exc:`TypeError`. + If *obj* is out of bounds, raise :exc:`OverflowError`. + + +.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow) + + Return a :c:type:`long long` representation of *obj*. *obj* can be a + :c:type:`PyLongObject`, a subtype of :c:type:`PyLongObject` or any + object that implements the :meth:`__int__` method. + + If *obj* is greater than :const:`PY_LLONG_MAX` or less than :const:`PY_LLONG_MIN`, + set *\*overflow* to ``1`` or ``-1``, respectively, and return ``-1``; otherwise, + set *\*overflow* to ``0``. If any other exception occurs (for example a + :exc:`TypeError` or :exc:`MemoryError`), then ``-1`` will be returned and + *\*overflow* will be ``0``. .. versionadded:: 3.2 @@ -149,9 +168,12 @@ single: PY_SSIZE_T_MAX single: OverflowError (built-in exception) - Return a C :c:type:`Py_ssize_t` representation of the contents of *pylong*. - If *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` - is raised and ``-1`` will be returned. + Return a :c:type:`Py_ssize_t` representation of *pylong* or ``-1`` + on error. *pylong* must be a :c:type:`PyLongObject` or a subtype of + :c:type:`PyLongObject`. + + If *pylong* has an invalid type, raise :exc:`TypeError`. + If *pylong* is out of bounds, raise :exc:`OverflowError`. .. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong) @@ -160,26 +182,12 @@ single: ULONG_MAX single: OverflowError (built-in exception) - Return a C :c:type:`unsigned long` representation of the contents of *pylong*. - If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is - raised. + Return an :c:type:`unsigned long` representation of *pylong* or + ``(unsigned long)-1`` on error. *pylong* must be a :c:type:`PyLongObject` + or a subtype of :c:type:`PyLongObject`. - -.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong) - - Return a :c:type:`size_t` representation of the contents of *pylong*. If - *pylong* is greater than the maximum value for a :c:type:`size_t`, an - :exc:`OverflowError` is raised. - - -.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong) - - .. index:: - single: OverflowError (built-in exception) - - Return a C :c:type:`long long` from a Python integer. If *pylong* - cannot be represented as a :c:type:`long long`, an - :exc:`OverflowError` is raised and ``-1`` is returned. + If *pylong* has an invalid type, raise :exc:`TypeError`. + If *pylong* is out of bounds, raise :exc:`OverflowError`. .. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong) @@ -187,37 +195,64 @@ .. index:: single: OverflowError (built-in exception) - Return a C :c:type:`unsigned long long` from a Python integer. If - *pylong* cannot be represented as an :c:type:`unsigned long long`, - an :exc:`OverflowError` is raised and ``(unsigned long long)-1`` is - returned. + Return an :c:type:`unsigned PY_LONG_LONG` representation of *pylong* or + ``(unsigned PY_LONG_LONG)-1`` on error. *pylong* must be a + :c:type:`PyLongObject` or a subtype of :c:type:`PyLongObject`. + + If *pylong* has an invalid type, raise :exc:`TypeError`. + If *pylong* is out of bounds, raise :exc:`OverflowError`. .. versionchanged:: 3.1 A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`. -.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io) +.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong) - Return a C :c:type:`unsigned long` from a Python integer, without checking for - overflow. + Return a :c:type:`size_t` representation of *pylong* or ``(size_t)-1`` + on error. *pylong* must be a :c:type:`PyLongObject` or a subtype of + :c:type:`PyLongObject`. + If *pylong* has an invalid type, raise :exc:`TypeError`. + If *pylong* is out of bounds, raise :exc:`OverflowError`. -.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io) +.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj) - Return a C :c:type:`unsigned long long` from a Python integer, without - checking for overflow. + Return an :c:type:`unsigned long` representation of *obj*. or ``(unsigned long)-1`` + on error. *obj* can be a :c:type:`PyLongObject`, a subtype of :c:type:`PyLongObject` + or any object that implements the :meth:`__int__` method. + + If *obj* cannot be represented as an integer, raise :exc:`TypeError`. + This function does not check for overflow. + + +.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj) + + Return an :c:type:`unsigned PY_LONG_LONG` representation of *obj* or + ``(unsigned PY_LONG_LONG)-1`` on error. *obj* can be a :c:type:`PyLongObject`, + a subtype of :c:type:`PyLongObject` or any object that implements the + :meth:`__int__` method. + + If *obj* cannot be represented as an integer, raise :exc:`TypeError`. + This function does not check for overflow. .. c:function:: double PyLong_AsDouble(PyObject *pylong) - Return a C :c:type:`double` representation of the contents of *pylong*. If - *pylong* cannot be approximately represented as a :c:type:`double`, an - :exc:`OverflowError` exception is raised and ``-1.0`` will be returned. + Return a :c:type:`double` representation of *pylong* or ``-1.0`` on error. + *pylong* must be a :c:type:`PyLongObject` or a subtype of :c:type:`PyLongObject`. + + If *pylong* has an invalid type, raise :exc:`TypeError`. + If *pylong* cannot be approximately represented as a :c:type:`double`, + raise :exc:`OverflowError`. .. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong) - Convert a Python integer *pylong* to a C :c:type:`void` pointer. - If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This - is only assured to produce a usable :c:type:`void` pointer for values created - with :c:func:`PyLong_FromVoidPtr`. + Convert a Python integer *pylong* to a :c:type:`void` pointer. *pylong* must + be a :c:type:`PyLongObject` or a subtype of :c:type:`PyLongObject`. + + If *pylong* has an invalid type, raise :exc:`TypeError`. + If *pylong* cannot be converted, raise :exc:`OverflowError`. + + This is only assured to produce a usable :c:type:`void` pointer for + values created with :c:func:`PyLong_FromVoidPtr`. diff --git a/Objects/longobject.c b/Objects/longobject.c --- a/Objects/longobject.c +++ b/Objects/longobject.c @@ -322,8 +322,8 @@ #define PY_ABS_LONG_MIN (0-(unsigned long)LONG_MIN) #define PY_ABS_SSIZE_T_MIN (0-(size_t)PY_SSIZE_T_MIN) -/* Get a C long int from a long int object. - Returns -1 and sets an error condition if overflow occurs. */ +/* Get a C long int from a long int object or any object that has an __int__() + method. Returns -1 and sets an error condition if overflow occurs. */ long PyLong_AsLongAndOverflow(PyObject *vv, int *overflow) @@ -946,10 +946,7 @@ void * PyLong_AsVoidPtr(PyObject *vv) { - /* This function will allow int or long objects. If vv is neither, - then the PyLong_AsLong*() functions will raise the exception: - PyExc_SystemError, "bad argument to internal function" - */ + /* This function will allow int or long objects. */ #if SIZEOF_VOID_P <= SIZEOF_LONG long x; @@ -1130,8 +1127,8 @@ return (PyObject *)v; } -/* Get a C PY_LONG_LONG int from a long int object. - Return -1 and set an error if overflow occurs. */ +/* Get a C PY_LONG_LONG int from a long int object or any other object that + has an __int__() method. Return -1 and set an error if overflow occurs. */ PY_LONG_LONG PyLong_AsLongLong(PyObject *vv) @@ -1287,7 +1284,9 @@ } #undef IS_LITTLE_ENDIAN -/* Get a C long long int from a Python long or Python int object. +/* Get a C long long int from a Python long or Python int object or + any object that has an __int__() method. + On overflow, returns -1 and sets *overflow to 1 or -1 depending on the sign of the result. Otherwise *overflow is 0.