mirror of
https://github.com/python/cpython.git
synced 2025-09-13 12:17:24 +00:00
bd87552a34
svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
140 lines
4.6 KiB
ReStructuredText
140 lines
4.6 KiB
ReStructuredText
.. highlightlang:: c
|
|
|
|
.. _tupleobjects:
|
|
|
|
Tuple Objects
|
|
-------------
|
|
|
|
.. index:: object: tuple
|
|
|
|
|
|
.. ctype:: PyTupleObject
|
|
|
|
This subtype of :ctype:`PyObject` represents a Python tuple object.
|
|
|
|
|
|
.. cvar:: PyTypeObject PyTuple_Type
|
|
|
|
.. index:: single: TupleType (in module types)
|
|
|
|
This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
|
|
the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
|
|
|
|
|
|
.. cfunction:: int PyTuple_Check(PyObject *p)
|
|
|
|
Return true if *p* is a tuple object or an instance of a subtype of the tuple
|
|
type.
|
|
|
|
|
|
.. cfunction:: int PyTuple_CheckExact(PyObject *p)
|
|
|
|
Return true if *p* is a tuple object, but not an instance of a subtype of the
|
|
tuple type.
|
|
|
|
|
|
.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len)
|
|
|
|
Return a new tuple object of size *len*, or *NULL* on failure.
|
|
|
|
.. versionchanged:: 2.5
|
|
This function used an :ctype:`int` type for *len*. This might require
|
|
changes in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
|
|
|
|
Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
|
|
are initialized to the subsequent *n* C arguments pointing to Python objects.
|
|
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
|
|
|
|
.. versionchanged:: 2.5
|
|
This function used an :ctype:`int` type for *n*. This might require
|
|
changes in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)
|
|
|
|
Take a pointer to a tuple object, and return the size of that tuple.
|
|
|
|
.. versionchanged:: 2.5
|
|
This function returned an :ctype:`int` type. This might require changes
|
|
in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
|
|
|
|
Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
|
|
no error checking is performed.
|
|
|
|
|
|
.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
|
|
|
|
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
|
|
out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
|
|
|
|
.. versionchanged:: 2.5
|
|
This function used an :ctype:`int` type for *pos*. This might require
|
|
changes in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
|
|
|
|
Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
|
|
|
|
|
|
.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
|
|
|
|
Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
|
|
as a new tuple.
|
|
|
|
.. versionchanged:: 2.5
|
|
This function used an :ctype:`int` type for *low* and *high*. This might
|
|
require changes in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
|
|
|
|
Insert a reference to object *o* at position *pos* of the tuple pointed to by
|
|
*p*. Return ``0`` on success.
|
|
|
|
.. note::
|
|
|
|
This function "steals" a reference to *o*.
|
|
|
|
.. versionchanged:: 2.5
|
|
This function used an :ctype:`int` type for *pos*. This might require
|
|
changes in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
|
|
|
|
Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be
|
|
used to fill in brand new tuples.
|
|
|
|
.. note::
|
|
|
|
This function "steals" a reference to *o*.
|
|
|
|
|
|
.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
|
|
|
|
Can be used to resize a tuple. *newsize* will be the new length of the tuple.
|
|
Because tuples are *supposed* to be immutable, this should only be used if there
|
|
is only one reference to the object. Do *not* use this if the tuple may already
|
|
be known to some other part of the code. The tuple will always grow or shrink
|
|
at the end. Think of this as destroying the old tuple and creating a new one,
|
|
only more efficiently. Returns ``0`` on success. Client code should never
|
|
assume that the resulting value of ``*p`` will be the same as before calling
|
|
this function. If the object referenced by ``*p`` is replaced, the original
|
|
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
|
|
raises :exc:`MemoryError` or :exc:`SystemError`.
|
|
|
|
.. versionchanged:: 2.5
|
|
This function used an :ctype:`int` type for *newsize*. This might
|
|
require changes in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. cfunction:: int PyTuple_ClearFreeList(void)
|
|
|
|
Clear the free list. Return the total number of freed items.
|