[Python-checkins] cpython (3.2): Issue #12965: More PyLong_As* clarifications. Thanks Stefan Krah.
mark.dickinson
python-checkins at python.org
Sat Jun 23 13:13:28 CEST 2012
http://hg.python.org/cpython/rev/e1416a4d728a
changeset: 77623:e1416a4d728a
branch: 3.2
parent: 77620:3ace8e17074a
user: Mark Dickinson <mdickinson at enthought.com>
date: Sat Jun 23 12:12:52 2012 +0100
summary:
Issue #12965: More PyLong_As* clarifications. Thanks Stefan Krah.
files:
Doc/c-api/long.rst | 61 +++++++++++++++++++++------------
1 files changed, 39 insertions(+), 22 deletions(-)
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
@@ -167,9 +167,11 @@
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 :c:type:`Py_ssize_t` representation of *pylong*. *pylong* must
+ be an instance of :c:type:`PyLongObject`.
+
+ Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+ :c:type:`Py_ssize_t`.
.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
@@ -178,16 +180,20 @@
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 a C :c:type:`unsigned long` representation of *pylong*. *pylong*
+ must be an instance of :c:type:`PyLongObject`.
+
+ Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+ :c:type:`unsigned long`.
.. 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.
+ Return a C :c:type:`size_t` representation of of *pylong*. *pylong* must be
+ an instance of :c:type:`PyLongObject`.
+
+ Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+ :c:type:`size_t`.
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
@@ -195,32 +201,43 @@
.. 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 a C :c:type:`unsigned PY_LONG_LONG` representation of of *pylong*.
+ *pylong* must be an instance of :c:type:`PyLongObject`.
+
+ Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
+ :c:type:`unsigned PY_LONG_LONG`.
.. versionchanged:: 3.1
A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
-.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
+.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
- Return a C :c:type:`unsigned long` from a Python integer, without checking for
- overflow.
+ Return a C :c:type:`unsigned long` representation of *obj*. If *obj*
+ is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+ method (if present) to convert it to a :c:type:`PyLongObject`.
+ If the value of *obj* is out of range for an :c:type:`unsigned long`,
+ return the reduction of that value modulo :const:`ULONG_MAX + 1`.
-.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
- Return a C :c:type:`unsigned long long` from a Python integer, without
- checking for overflow.
+.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj)
+
+ Return a C :c:type:`unsigned long long` representation of *obj*. If *obj*
+ is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+ method (if present) to convert it to a :c:type:`PyLongObject`.
+
+ If the value of *obj* is out of range for an :c:type:`unsigned long long`,
+ return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`.
.. 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 :c:type:`double` representation of *pylong*. *pylong* must be
+ an instance of :c:type:`PyLongObject`.
+
+ Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
+ :c:type:`double`.
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list