Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _tupleobjects: |
| 4 | |
| 5 | Tuple Objects |
| 6 | ------------- |
| 7 | |
| 8 | .. index:: object: tuple |
| 9 | |
| 10 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 11 | .. c:type:: PyTupleObject |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 12 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 13 | This subtype of :c:type:`PyObject` represents a Python tuple object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 14 | |
| 15 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 16 | .. c:var:: PyTypeObject PyTuple_Type |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 17 | |
Georg Brandl | 2aff335 | 2010-10-17 10:59:41 +0000 | [diff] [blame] | 18 | This instance of :c:type:`PyTypeObject` represents the Python tuple type; it |
| 19 | is the same object as :class:`tuple` in the Python layer. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 20 | |
| 21 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 22 | .. c:function:: int PyTuple_Check(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 23 | |
| 24 | Return true if *p* is a tuple object or an instance of a subtype of the tuple |
| 25 | type. |
| 26 | |
| 27 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 28 | .. c:function:: int PyTuple_CheckExact(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 29 | |
| 30 | Return true if *p* is a tuple object, but not an instance of a subtype of the |
| 31 | tuple type. |
| 32 | |
| 33 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 34 | .. c:function:: PyObject* PyTuple_New(Py_ssize_t len) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 35 | |
| 36 | Return a new tuple object of size *len*, or *NULL* on failure. |
| 37 | |
| 38 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 39 | .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 40 | |
| 41 | Return a new tuple object of size *n*, or *NULL* on failure. The tuple values |
| 42 | are initialized to the subsequent *n* C arguments pointing to Python objects. |
| 43 | ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``. |
| 44 | |
| 45 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 46 | .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 47 | |
| 48 | Take a pointer to a tuple object, and return the size of that tuple. |
| 49 | |
| 50 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 51 | .. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 52 | |
| 53 | Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple; |
| 54 | no error checking is performed. |
| 55 | |
| 56 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 57 | .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 58 | |
| 59 | Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is |
| 60 | out of bounds, return *NULL* and sets an :exc:`IndexError` exception. |
| 61 | |
| 62 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 63 | .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 64 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 65 | Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 66 | |
| 67 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 68 | .. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 69 | |
| 70 | Take a slice of the tuple pointed to by *p* from *low* to *high* and return it |
| 71 | as a new tuple. |
| 72 | |
| 73 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 74 | .. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 75 | |
| 76 | Insert a reference to object *o* at position *pos* of the tuple pointed to by |
| 77 | *p*. Return ``0`` on success. |
| 78 | |
| 79 | .. note:: |
| 80 | |
| 81 | This function "steals" a reference to *o*. |
| 82 | |
| 83 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 84 | .. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 85 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 86 | Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 87 | used to fill in brand new tuples. |
| 88 | |
| 89 | .. note:: |
| 90 | |
| 91 | This function "steals" a reference to *o*. |
| 92 | |
| 93 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 94 | .. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 95 | |
| 96 | Can be used to resize a tuple. *newsize* will be the new length of the tuple. |
| 97 | Because tuples are *supposed* to be immutable, this should only be used if there |
| 98 | is only one reference to the object. Do *not* use this if the tuple may already |
| 99 | be known to some other part of the code. The tuple will always grow or shrink |
| 100 | at the end. Think of this as destroying the old tuple and creating a new one, |
| 101 | only more efficiently. Returns ``0`` on success. Client code should never |
| 102 | assume that the resulting value of ``*p`` will be the same as before calling |
| 103 | this function. If the object referenced by ``*p`` is replaced, the original |
| 104 | ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and |
| 105 | raises :exc:`MemoryError` or :exc:`SystemError`. |
Christian Heimes | a156e09 | 2008-02-16 07:38:31 +0000 | [diff] [blame] | 106 | |
Jeroen Ruigrok van der Werven | bd87552 | 2009-04-26 21:06:15 +0000 | [diff] [blame] | 107 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 108 | .. c:function:: int PyTuple_ClearFreeList() |
Christian Heimes | a156e09 | 2008-02-16 07:38:31 +0000 | [diff] [blame] | 109 | |
| 110 | Clear the free list. Return the total number of freed items. |
Georg Brandl | ae30a81 | 2013-10-12 19:03:43 +0200 | [diff] [blame^] | 111 | |
| 112 | |
| 113 | Struct Sequence Objects |
| 114 | ----------------------- |
| 115 | |
| 116 | Struct sequence objects are the C equivalent of :func:`~collections.namedtuple` |
| 117 | objects, i.e. a sequence whose items can also be accessed through attributes. |
| 118 | To create a struct sequence, you first have to create a specific struct sequence |
| 119 | type. |
| 120 | |
| 121 | .. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc) |
| 122 | |
| 123 | Create a new struct sequence type from the data in *desc*, described below. Instances |
| 124 | of the resulting type can be created with :c:func:`PyStructSequence_New`. |
| 125 | |
| 126 | |
| 127 | .. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc) |
| 128 | |
| 129 | Initializes a struct sequence type *type* from *desc* in place. |
| 130 | |
| 131 | |
| 132 | .. c:type:: PyStructSequence_Desc |
| 133 | |
| 134 | Contains the meta information of a struct sequence type to create. |
| 135 | |
| 136 | +-------------------+------------------------------+------------------------------------+ |
| 137 | | Field | C Type | Meaning | |
| 138 | +===================+==============================+====================================+ |
| 139 | | ``name`` | ``char *`` | name of the struct sequence type | |
| 140 | +-------------------+------------------------------+------------------------------------+ |
| 141 | | ``doc`` | ``char *`` | pointer to docstring for the type | |
| 142 | | | | or NULL to omit | |
| 143 | +-------------------+------------------------------+------------------------------------+ |
| 144 | | ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array | |
| 145 | | | | with field names of the new type | |
| 146 | +-------------------+------------------------------+------------------------------------+ |
| 147 | | ``n_in_sequence`` | ``int`` | number of fields visible to the | |
| 148 | | | | Python side (if used as tuple) | |
| 149 | +-------------------+------------------------------+------------------------------------+ |
| 150 | |
| 151 | |
| 152 | .. c:type:: PyStructSequence_Field |
| 153 | |
| 154 | Describes a field of a struct sequence. As a struct sequence is modeled as a |
| 155 | tuple, all fields are typed as :c:type:`PyObject\*`. The index in the |
| 156 | :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which |
| 157 | field of the struct sequence is described. |
| 158 | |
| 159 | +-----------+---------------+--------------------------------------+ |
| 160 | | Field | C Type | Meaning | |
| 161 | +===========+===============+======================================+ |
| 162 | | ``name`` | ``char *`` | name for the field or *NULL* to end | |
| 163 | | | | the list of named fields, set to | |
| 164 | | | | PyStructSequence_UnnamedField to | |
| 165 | | | | leave unnamed | |
| 166 | +-----------+---------------+--------------------------------------+ |
| 167 | | ``doc`` | ``char *`` | field docstring or *NULL* to omit | |
| 168 | +-----------+---------------+--------------------------------------+ |
| 169 | |
| 170 | |
| 171 | .. c:var:: char* PyStructSequence_UnnamedField |
| 172 | |
| 173 | Special value for a field name to leave it unnamed. |
| 174 | |
| 175 | |
| 176 | .. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type) |
| 177 | |
| 178 | Creates an instance of *type*, which must have been created with |
| 179 | :c:func:`PyStructSequence_NewType`. |
| 180 | |
| 181 | |
| 182 | .. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos) |
| 183 | |
| 184 | Return the object at position *pos* in the struct sequence pointed to by *p*. |
| 185 | No bounds checking is performed. |
| 186 | |
| 187 | |
| 188 | .. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos) |
| 189 | |
| 190 | Macro equivalent of :c:func:`PyStructSequence_GetItem`. |
| 191 | |
| 192 | |
| 193 | .. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) |
| 194 | |
| 195 | Sets the field at index *pos* of the struct sequence *p* to value *o*. Like |
| 196 | :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new |
| 197 | instances. |
| 198 | |
| 199 | .. note:: |
| 200 | |
| 201 | This function "steals" a reference to *o*. |
| 202 | |
| 203 | |
| 204 | .. c:function:: PyObject* PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o) |
| 205 | |
| 206 | Macro equivalent of :c:func:`PyStructSequence_SetItem`. |
| 207 | |
| 208 | .. note:: |
| 209 | |
| 210 | This function "steals" a reference to *o*. |