[Python-checkins] cpython (merge 3.2 -> default): Issue #12965: Merge from 3.2.

[mark.dickinson]

http://hg.python.org/cpython/rev/349bc58e8c66
changeset:   77624:349bc58e8c66
parent:      77622:5a7080995fd9
parent:      77623:e1416a4d728a
user:        Mark Dickinson <mdickinson at enthought.com>
date:        Sat Jun 23 12:13:15 2012 +0100
summary:
  Issue #12965: Merge from 3.2.

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
@@ -181,9 +181,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)
@@ -192,16 +194,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)
@@ -209,32 +215,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