diff options
Diffstat (limited to 'Doc/c-api/concrete.rst')
| -rw-r--r-- | Doc/c-api/concrete.rst | 222 |
1 files changed, 79 insertions, 143 deletions
diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 2f4863a..eefd927 100644 --- 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,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. |