Remove PyInt API from the docs. Extend PyLong docs to cover all public functions in longobject.c.

birkenfeld · birkenfeld · commit 9914dd33c008 · 2007-12-02T23:08:39.000Z
diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst
@@ -132,115 +132,6 @@ Numeric Objects
 .. index:: object: numeric
 
 
-.. _intobjects:
-
-Plain Integer Objects
----------------------
-
-.. index:: object: integer
-
-
-.. ctype:: PyIntObject
-
-   This subtype of :ctype:`PyObject` represents a Python integer object.
-
-
-.. cvar:: PyTypeObject PyInt_Type
-
-   .. index:: single: IntType (in modules types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
-   This is the same object as ``int`` and ``types.IntType``.
-
-
-.. cfunction:: int PyInt_Check(PyObject *o)
-
-   Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
-   :cdata:`PyInt_Type`.
-
-
-.. cfunction:: int PyInt_CheckExact(PyObject *o)
-
-   Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
-   :cdata:`PyInt_Type`.
-
-
-.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)
-
-   Return a new :ctype:`PyIntObject` or :ctype:`PyLongObject` based on the string
-   value in *str*, which is interpreted according to the radix in *base*.  If
-   *pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
-   follows the representation of the number.  If *base* is ``0``, the radix will be
-   determined based on the leading characters of *str*: if *str* starts with
-   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
-   8 will be used; otherwise radix 10 will be used.  If *base* is not ``0``, it
-   must be between ``2`` and ``36``, inclusive.  Leading spaces are ignored.  If
-   there are no digits, :exc:`ValueError` will be raised.  If the string represents
-   a number too large to be contained within the machine's :ctype:`long int` type
-   and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
-   returned.  If overflow warnings are not being suppressed, *NULL* will be
-   returned in this case.
-
-
-.. cfunction:: PyObject* PyInt_FromLong(long ival)
-
-   Create a new integer object with a value of *ival*.
-
-   The current implementation keeps an array of integer objects for all integers
-   between ``-5`` and ``256``, when you create an int in that range you actually
-   just get back a reference to the existing object. So it should be possible to
-   change the value of ``1``.  I suspect the behaviour of Python in this case is
-   undefined. :-)
-
-
-.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)
-
-   Create a new integer object with a value of *ival*. If the value exceeds
-   ``LONG_MAX``, a long integer object is returned.
-
-
-.. cfunction:: long PyInt_AsLong(PyObject *io)
-
-   Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
-   already one, and then return its value. If there is an error, ``-1`` is
-   returned, and the caller should check ``PyErr_Occurred()`` to find out whether
-   there was an error, or whether the value just happened to be -1.
-
-
-.. cfunction:: long PyInt_AS_LONG(PyObject *io)
-
-   Return the value of the object *io*.  No error checking is performed.
-
-
-.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
-
-   Will first attempt to cast the object to a :ctype:`PyIntObject` or
-   :ctype:`PyLongObject`, if it is not already one, and then return its value as
-   unsigned long.  This function does not check for overflow.
-
-
-.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
-
-   Will first attempt to cast the object to a :ctype:`PyIntObject` or
-   :ctype:`PyLongObject`, if it is not already one, and then return its value as
-   unsigned long long, without checking for overflow.
-
-
-.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
-
-   Will first attempt to cast the object to a :ctype:`PyIntObject` or
-   :ctype:`PyLongObject`, if it is not already one, and then return its value as
-   :ctype:`Py_ssize_t`.
-
-
-.. cfunction:: long PyInt_GetMax()
-
-   .. index:: single: LONG_MAX
-
-   Return the system's idea of the largest integer it can handle
-   (:const:`LONG_MAX`, as defined in the system header files).
-
-
 .. _boolobjects:
 
 Boolean Objects
@@ -289,23 +180,23 @@ are available, however.
 
 .. _longobjects:
 
-Long Integer Objects
---------------------
+Integer Objects
+---------------
 
 .. index:: object: long integer
+           object: integer
 
+All integers are implemented as "long" integer objects of arbitrary size.
 
 .. ctype:: PyLongObject
 
-   This subtype of :ctype:`PyObject` represents a Python long integer object.
+   This subtype of :ctype:`PyObject` represents a Python integer object.
 
 
 .. cvar:: PyTypeObject PyLong_Type
 
-   .. index:: single: LongType (in modules types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python long integer type.
-   This is the same object as ``long`` and ``types.LongType``.
+   This instance of :ctype:`PyTypeObject` represents the Python integer type.
+   This is the same object as ``int``.
 
 
 .. cfunction:: int PyLong_Check(PyObject *p)
@@ -320,17 +211,39 @@ Long Integer Objects
    :ctype:`PyLongObject`.
 
 
+.. XXX cfunction PyInt_CheckExact(PyObject *p) checks if argument is a long
+   object and fits into a C long
+
+
 .. cfunction:: PyObject* PyLong_FromLong(long v)
 
    Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
 
+   The current implementation keeps an array of integer objects for all integers
+   between ``-5`` and ``256``, when you create an int in that range you actually
+   just get back a reference to the existing object. So it should be possible to
+   change the value of ``1``.  I suspect the behaviour of Python in this case is
+   undefined. :-)
+
 
 .. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
 
    Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
    *NULL* on failure.
 
 
+.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
+
+   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
+   on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
+
+   Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL*
+   on failure.
+
+
 .. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
 
    Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
@@ -351,33 +264,32 @@ Long Integer Objects
 
 .. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
 
-   Return a new :ctype:`PyLongObject` based on the string value in *str*, which is
-   interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
+   Return a new :ctype:`PyLongObject` based on the string value in *str*, which
+   is interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
    ``*pend`` will point to the first character in *str* which follows the
-   representation of the number.  If *base* is ``0``, the radix will be determined
-   based on the leading characters of *str*: if *str* starts with ``'0x'`` or
-   ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be
-   used; otherwise radix 10 will be used.  If *base* is not ``0``, it must be
-   between ``2`` and ``36``, inclusive.  Leading spaces are ignored.  If there are
-   no digits, :exc:`ValueError` will be raised.
+   representation of the number.  If *base* is ``0``, the radix will be
+   determined based on the leading characters of *str*: if *str* starts with
+   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or
+   ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
+   radix 2 will be used; otherwise radix 10 will be used.  If *base* is not
+   ``0``, it must be between ``2`` and ``36``, inclusive.  Leading spaces are
+   ignored.  If there are no digits, :exc:`ValueError` will be raised.
 
 
 .. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
 
-   Convert a sequence of Unicode digits to a Python long integer value.  The first
-   parameter, *u*, points to the first character of the Unicode string, *length*
-   gives the number of characters, and *base* is the radix for the conversion.  The
-   radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
-   will be raised.
+   Convert a sequence of Unicode digits to a Python integer value.  The Unicode
+   string is first encoded to a byte string using :cfunc:`PyUnicode_EncodeDecimal`
+   and then converted using :cfunc:`PyLong_FromString`.
 
 
 .. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
 
-   Create a Python integer or long integer from the pointer *p*. The pointer value
-   can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
-   If the integer is larger than LONG_MAX, a positive long integer is returned.
+   Create a Python integer from the pointer *p*. The pointer value can be
+   retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
 
 
+.. XXX alias PyLong_AS_LONG (for now) 
 .. cfunction:: long PyLong_AsLong(PyObject *pylong)
 
    .. index::
@@ -399,29 +311,46 @@ Long Integer Objects
    raised.
 
 
+.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
+
+   .. index::
+      single: PY_SSIZE_T_MAX
+
+   Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*.  If
+   *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is
+   raised.
+
+
+.. cfunction:: size_t PyLong_AsSize_t(PyObject *pylong)
+
+   Return a :ctype:`size_t` representation of the contents of *pylong*.  If
+   *pylong* is greater than the maximum value for a :ctype:`size_t`, an
+   :exc:`OverflowError` is raised.
+
+
 .. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
 
-   Return a C :ctype:`long long` from a Python long integer.  If *pylong* cannot be
+   Return a C :ctype:`long long` from a Python integer.  If *pylong* cannot be
    represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
 
 
 .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
 
-   Return a C :ctype:`unsigned long long` from a Python long integer. If *pylong*
+   Return a C :ctype:`unsigned long long` from a Python integer. If *pylong*
    cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
    will be raised if the value is positive, or a :exc:`TypeError` will be raised if
    the value is negative.
 
 
 .. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
 
-   Return a C :ctype:`unsigned long` from a Python long integer, without checking
-   for overflow.
+   Return a C :ctype:`unsigned long` from a Python integer, without checking for
+   overflow.
 
 
 .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
 
-   Return a C :ctype:`unsigned long long` from a Python long integer, without
+   Return a C :ctype:`unsigned long long` from a Python integer, without
    checking for overflow.
 
 
@@ -434,12 +363,19 @@ Long Integer Objects
 
 .. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
 
-   Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.
-   If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This
-   is only assured to produce a usable :ctype:`void` pointer for values created
-   with :cfunc:`PyLong_FromVoidPtr`.
+   Convert a Python integer *pylong* to a C :ctype:`void` pointer.  If *pylong*
+   cannot be converted, an :exc:`OverflowError` will be raised.  This is only
+   assured to produce a usable :ctype:`void` pointer for values created with
+   :cfunc:`PyLong_FromVoidPtr`.
+
 
-   For values outside 0..LONG_MAX, both signed and unsigned integers are acccepted.
+.. XXX name?
+.. cfunction:: long PyInt_GetMax()
+
+   .. index:: single: LONG_MAX
+
+   Return the system's idea of the largest integer it can handle
+   (:const:`LONG_MAX`, as defined in the system header files).
 
 
 .. _floatobjects:
@@ -2435,7 +2371,7 @@ change in future releases of Python.
 .. cfunction:: int PyObject_AsFileDescriptor(PyObject *p)
 
    Return the file descriptor associated with *p* as an :ctype:`int`.  If the
-   object is an integer or long integer, its value is returned.  If not, the
+   object is an integer, its value is returned.  If not, the
    object's :meth:`fileno` method is called if it exists; the method must return
    an integer, which is returned as the file descriptor value.  Sets an
    exception and returns ``-1`` on failure.
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
@@ -165,7 +165,7 @@ error on to the interpreter but wants to handle it completely by itself
 Every failing :cfunc:`malloc` call must be turned into an exception --- the
 direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call
 :cfunc:`PyErr_NoMemory` and return a failure indicator itself.  All the
-object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do
+object-creating functions (for example, :cfunc:`PyLong_FromLong`) already do
 this, so this note is only relevant to those who call :cfunc:`malloc` directly.
 
 Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and
@@ -889,10 +889,10 @@ reference or not.
 
 Most functions that return a reference to an object pass on ownership with the
 reference.  In particular, all functions whose function it is to create a new
-object, such as :cfunc:`PyInt_FromLong` and :cfunc:`Py_BuildValue`, pass
+object, such as :cfunc:`PyLong_FromLong` and :cfunc:`Py_BuildValue`, pass
 ownership to the receiver.  Even if the object is not actually new, you still
 receive ownership of a new reference to that object.  For instance,
-:cfunc:`PyInt_FromLong` maintains a cache of popular values and can return a
+:cfunc:`PyLong_FromLong` maintains a cache of popular values and can return a
 reference to a cached item.
 
 Many functions that extract objects from other objects also transfer ownership
@@ -942,7 +942,7 @@ an unrelated object while borrowing a reference to a list item.  For instance::
    {
        PyObject *item = PyList_GetItem(list, 0);
 
-       PyList_SetItem(list, 1, PyInt_FromLong(0L));
+       PyList_SetItem(list, 1, PyLong_FromLong(0L));
        PyObject_Print(item, stdout, 0); /* BUG! */
    }
 
@@ -974,7 +974,7 @@ increment the reference count.  The correct version of the function reads::
        PyObject *item = PyList_GetItem(list, 0);
 
        Py_INCREF(item);
-       PyList_SetItem(list, 1, PyInt_FromLong(0L));
+       PyList_SetItem(list, 1, PyLong_FromLong(0L));
        PyObject_Print(item, stdout, 0);
        Py_DECREF(item);
    }
