[Python-3000-checkins] r59284 - in python/branches/py3k/Doc: c-api/concrete.rst extending/extending.rst
georg.brandl
python-3000-checkins at python.org
Mon Dec 3 00:08:39 CET 2007
Author: georg.brandl
Date: Mon Dec 3 00:08:39 2007
New Revision: 59284
Modified:
python/branches/py3k/Doc/c-api/concrete.rst
python/branches/py3k/Doc/extending/extending.rst
Log:
Remove PyInt API from the docs. Extend PyLong docs to cover all public functions in longobject.c.
Modified: python/branches/py3k/Doc/c-api/concrete.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/concrete.rst (original)
+++ python/branches/py3k/Doc/c-api/concrete.rst Mon Dec 3 00:08:39 2007
@@ -132,115 +132,6 @@
.. 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 @@
.. _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 @@
: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 @@
*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 @@
.. 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 @@
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 @@
.. 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 @@
.. 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 @@
.. 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.
Modified: python/branches/py3k/Doc/extending/extending.rst
==============================================================================
--- python/branches/py3k/Doc/extending/extending.rst (original)
+++ python/branches/py3k/Doc/extending/extending.rst Mon Dec 3 00:08:39 2007
@@ -165,7 +165,7 @@
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 @@
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 @@
{
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 @@
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);
}
More information about the Python-3000-checkins
mailing list