Skip to content

C
cpython
Commit ff2cea22 authored by Georg Brandl's avatar Georg Brandl
Browse files
Options

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

parent 2c7c6339
Hide whitespace changes
Inline Side-by-side
Showing with 84 additions and 148 deletions
Doc/c-api/concrete.rst
View file @ ff2cea22
......@@ -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.
......
Doc/extending/extending.rst
View file @ ff2cea22
......@@ -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);
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7