Debian Codegraph @

Doc/c-api/tuple.rst

raw
1 .. highlight:: c
2
3 .. _tupleobjects:
4
5 Tuple Objects
6 -------------
7
8 .. index:: pair: object; tuple
9
10
11 .. c:type:: PyTupleObject
12
13 This subtype of :c:type:`PyObject` represents a Python tuple object.
14
15
16 .. c:var:: PyTypeObject PyTuple_Type
17
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.
20
21
22 .. c:function:: int PyTuple_Check(PyObject *p)
23
24 Return true if *p* is a tuple object or an instance of a subtype of the
25 tuple type. This function always succeeds.
26
27
28 .. c:function:: int PyTuple_CheckExact(PyObject *p)
29
30 Return true if *p* is a tuple object, but not an instance of a subtype of the
31 tuple type. This function always succeeds.
32
33
34 .. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
35
36 Return a new tuple object of size *len*,
37 or ``NULL`` with an exception set on failure.
38
39
40 .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
41
42 Return a new tuple object of size *n*,
43 or ``NULL`` with an exception set on failure. The tuple values
44 are initialized to the subsequent *n* C arguments pointing to Python objects.
45 ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
46
47
48 .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
49
50 Take a pointer to a tuple object, and return the size of that tuple.
51 On error, return ``-1`` with an exception set.
52
53
54 .. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
55
56 Like :c:func:`PyTuple_Size`, but without error checking.
57
58
59 .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
60
61 Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
62 negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
63
64 The returned reference is borrowed from the tuple *p*
65 (that is: it is only valid as long as you hold a reference to *p*).
66 To get a :term:`strong reference`, use
67 :c:func:`Py_NewRef(PyTuple_GetItem(...)) <Py_NewRef>`
68 or :c:func:`PySequence_GetItem`.
69
70
71 .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
72
73 Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
74
75
76 .. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
77
78 Return the slice of the tuple pointed to by *p* between *low* and *high*,
79 or ``NULL`` with an exception set on failure.
80
81 This is the equivalent of the Python expression ``p[low:high]``.
82 Indexing from the end of the tuple is not supported.
83
84
85 .. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
86
87 Insert a reference to object *o* at position *pos* of the tuple pointed to by
88 *p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1``
89 and set an :exc:`IndexError` exception.
90
91 .. note::
92
93 This function "steals" a reference to *o* and discards a reference to
94 an item already in the tuple at the affected position.
95
96
97 .. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
98
99 Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
100 used to fill in brand new tuples.
101
102 Bounds checking is performed as an assertion if Python is built in
103 :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
104
105 .. note::
106
107 This function "steals" a reference to *o*, and, unlike
108 :c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that
109 is being replaced; any reference in the tuple at position *pos* will be
110 leaked.
111
112 .. warning::
113
114 This macro should *only* be used on tuples that are newly created.
115 Using this macro on a tuple that is already in use (or in other words, has
116 a refcount > 1) could lead to undefined behavior.
117
118
119 .. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
120
121 Can be used to resize a tuple. *newsize* will be the new length of the tuple.
122 Because tuples are *supposed* to be immutable, this should only be used if there
123 is only one reference to the object. Do *not* use this if the tuple may already
124 be known to some other part of the code. The tuple will always grow or shrink
125 at the end. Think of this as destroying the old tuple and creating a new one,
126 only more efficiently. Returns ``0`` on success. Client code should never
127 assume that the resulting value of ``*p`` will be the same as before calling
128 this function. If the object referenced by ``*p`` is replaced, the original
129 ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and
130 raises :exc:`MemoryError` or :exc:`SystemError`.
131
132
133 .. _struct-sequence-objects:
134
135 Struct Sequence Objects
136 -----------------------
137
138 Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
139 objects, i.e. a sequence whose items can also be accessed through attributes.
140 To create a struct sequence, you first have to create a specific struct sequence
141 type.
142
143 .. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
144
145 Create a new struct sequence type from the data in *desc*, described below. Instances
146 of the resulting type can be created with :c:func:`PyStructSequence_New`.
147
148 Return ``NULL`` with an exception set on failure.
149
150
151 .. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
152
153 Initializes a struct sequence type *type* from *desc* in place.
154
155
156 .. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
157
158 Like :c:func:`PyStructSequence_InitType`, but returns ``0`` on success
159 and ``-1`` with an exception set on failure.
160
161 .. versionadded:: 3.4
162
163
164 .. c:type:: PyStructSequence_Desc
165
166 Contains the meta information of a struct sequence type to create.
167
168 .. c:member:: const char *name
169
170 Fully qualified name of the type; null-terminated UTF-8 encoded.
171 The name must contain the module name.
172
173 .. c:member:: const char *doc
174
175 Pointer to docstring for the type or ``NULL`` to omit.
176
177 .. c:member:: PyStructSequence_Field *fields
178
179 Pointer to ``NULL``-terminated array with field names of the new type.
180
181 .. c:member:: int n_in_sequence
182
183 Number of fields visible to the Python side (if used as tuple).
184
185
186 .. c:type:: PyStructSequence_Field
187
188 Describes a field of a struct sequence. As a struct sequence is modeled as a
189 tuple, all fields are typed as :c:expr:`PyObject*`. The index in the
190 :c:member:`~PyStructSequence_Desc.fields` array of
191 the :c:type:`PyStructSequence_Desc` determines which
192 field of the struct sequence is described.
193
194 .. c:member:: const char *name
195
196 Name for the field or ``NULL`` to end the list of named fields,
197 set to :c:data:`PyStructSequence_UnnamedField` to leave unnamed.
198
199 .. c:member:: const char *doc
200
201 Field docstring or ``NULL`` to omit.
202
203
204 .. c:var:: const char * const PyStructSequence_UnnamedField
205
206 Special value for a field name to leave it unnamed.
207
208 .. versionchanged:: 3.9
209 The type was changed from ``char *``.
210
211
212 .. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)
213
214 Creates an instance of *type*, which must have been created with
215 :c:func:`PyStructSequence_NewType`.
216
217 Return ``NULL`` with an exception set on failure.
218
219
220 .. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
221
222 Return the object at position *pos* in the struct sequence pointed to by *p*.
223
224 Bounds checking is performed as an assertion if Python is built in
225 :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
226
227
228 .. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
229
230 Alias to :c:func:`PyStructSequence_GetItem`.
231
232 .. versionchanged:: 3.13
233 Now implemented as an alias to :c:func:`PyStructSequence_GetItem`.
234
235
236 .. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
237
238 Sets the field at index *pos* of the struct sequence *p* to value *o*. Like
239 :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
240 instances.
241
242 Bounds checking is performed as an assertion if Python is built in
243 :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
244
245 .. note::
246
247 This function "steals" a reference to *o*.
248
249
250 .. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
251
252 Alias to :c:func:`PyStructSequence_SetItem`.
253
254 .. versionchanged:: 3.13
255 Now implemented as an alias to :c:func:`PyStructSequence_SetItem`.