traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

This commit is contained in:
Georg Brandl 2007-12-02 23:08:39 +00:00
parent 8d5c39240e
commit 9914dd33c0
2 changed files with 84 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

222
Doc/c-api/concrete.rst
View File

@ -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,10 +211,20 @@ 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)
@ -331,6 +232,18 @@ Long Integer Objects
*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,15 +311,32 @@ 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.
@ -415,13 +344,13 @@ Long Integer Objects
.. 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.

10
Doc/extending/extending.rst
View File

@ -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);
}