Debian Codegraph @

Doc/c-api/list.rst

raw
1 .. highlight:: c
2
3 .. _listobjects:
4
5 List Objects
6 ------------
7
8 .. index:: pair: object; list
9
10
11 .. c:type:: PyListObject
12
13 This subtype of :c:type:`PyObject` represents a Python list object.
14
15
16 .. c:var:: PyTypeObject PyList_Type
17
18 This instance of :c:type:`PyTypeObject` represents the Python list type.
19 This is the same object as :class:`list` in the Python layer.
20
21
22 .. c:function:: int PyList_Check(PyObject *p)
23
24 Return true if *p* is a list object or an instance of a subtype of the list
25 type. This function always succeeds.
26
27
28 .. c:function:: int PyList_CheckExact(PyObject *p)
29
30 Return true if *p* is a list object, but not an instance of a subtype of
31 the list type. This function always succeeds.
32
33
34 .. c:function:: PyObject* PyList_New(Py_ssize_t len)
35
36 Return a new list of length *len* on success, or ``NULL`` on failure.
37
38 .. note::
39
40 If *len* is greater than zero, the returned list object's items are
41 set to ``NULL``. Thus you cannot use abstract API functions such as
42 :c:func:`PySequence_SetItem` or expose the object to Python code before
43 setting all items to a real object with :c:func:`PyList_SetItem` or
44 :c:func:`PyList_SET_ITEM()`. The following APIs are safe APIs before
45 the list is fully initialized: :c:func:`PyList_SetItem()` and :c:func:`PyList_SET_ITEM()`.
46
47
48
49 .. c:function:: Py_ssize_t PyList_Size(PyObject *list)
50
51 .. index:: pair: built-in function; len
52
53 Return the length of the list object in *list*; this is equivalent to
54 ``len(list)`` on a list object.
55
56
57 .. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
58
59 Similar to :c:func:`PyList_Size`, but without error checking.
60
61
62 .. c:function:: PyObject* PyList_GetItemRef(PyObject *list, Py_ssize_t index)
63
64 Return the object at position *index* in the list pointed to by *list*. The
65 position must be non-negative; indexing from the end of the list is not
66 supported. If *index* is out of bounds (:code:`<0 or >=len(list)`),
67 return ``NULL`` and set an :exc:`IndexError` exception.
68
69 .. versionadded:: 3.13
70
71
72 .. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
73
74 Like :c:func:`PyList_GetItemRef`, but returns a
75 :term:`borrowed reference` instead of a :term:`strong reference`.
76
77 .. note::
78
79 In the :term:`free-threaded build`, the returned
80 :term:`borrowed reference` may become invalid if another thread modifies
81 the list concurrently. Prefer :c:func:`PyList_GetItemRef`, which returns
82 a :term:`strong reference`.
83
84
85 .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
86
87 Similar to :c:func:`PyList_GetItem`, but without error checking.
88
89 .. note::
90
91 In the :term:`free-threaded build`, the returned
92 :term:`borrowed reference` may become invalid if another thread modifies
93 the list concurrently. Prefer :c:func:`PyList_GetItemRef`, which returns
94 a :term:`strong reference`.
95
96
97 .. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
98
99 Set the item at index *index* in list to *item*. Return ``0`` on success.
100 If *index* is out of bounds, return ``-1`` and set an :exc:`IndexError`
101 exception.
102
103 .. note::
104
105 This function "steals" a reference to *item* and discards a reference to
106 an item already in the list at the affected position.
107
108
109 .. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
110
111 Macro form of :c:func:`PyList_SetItem` without error checking. This is
112 normally only used to fill in new lists where there is no previous content.
113
114 Bounds checking is performed as an assertion if Python is built in
115 :ref:`debug mode <debug-build>` or :option:`with assertions
116 <--with-assertions>`.
117
118 .. note::
119
120 This macro "steals" a reference to *item*, and, unlike
121 :c:func:`PyList_SetItem`, does *not* discard a reference to any item that
122 is being replaced; any reference in *list* at position *i* will be
123 leaked.
124
125 .. note::
126
127 In the :term:`free-threaded build`, this macro has no internal
128 synchronization. It is normally only used to fill in new lists where no
129 other thread has a reference to the list. If the list may be shared,
130 use :c:func:`PyList_SetItem` instead, which uses a :term:`per-object
131 lock`.
132
133
134 .. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
135
136 Insert the item *item* into list *list* in front of index *index*. Return
137 ``0`` if successful; return ``-1`` and set an exception if unsuccessful.
138 Analogous to ``list.insert(index, item)``.
139
140
141 .. c:function:: int PyList_Append(PyObject *list, PyObject *item)
142
143 Append the object *item* at the end of list *list*. Return ``0`` if
144 successful; return ``-1`` and set an exception if unsuccessful. Analogous
145 to ``list.append(item)``.
146
147
148 .. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
149
150 Return a list of the objects in *list* containing the objects *between* *low*
151 and *high*. Return ``NULL`` and set an exception if unsuccessful. Analogous
152 to ``list[low:high]``. Indexing from the end of the list is not supported.
153
154
155 .. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
156
157 Set the slice of *list* between *low* and *high* to the contents of
158 *itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
159 be ``NULL``, indicating the assignment of an empty list (slice deletion).
160 Return ``0`` on success, ``-1`` on failure. Indexing from the end of the
161 list is not supported.
162
163 .. note::
164
165 In the :term:`free-threaded build`, when *itemlist* is a :class:`list`,
166 both *list* and *itemlist* are locked for the duration of the operation.
167 For other iterables (or ``NULL``), only *list* is locked.
168
169
170 .. c:function:: int PyList_Extend(PyObject *list, PyObject *iterable)
171
172 Extend *list* with the contents of *iterable*. This is the same as
173 ``PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)``
174 and analogous to ``list.extend(iterable)`` or ``list += iterable``.
175
176 Raise an exception and return ``-1`` if *list* is not a :class:`list`
177 object. Return 0 on success.
178
179 .. versionadded:: 3.13
180
181 .. note::
182
183 In the :term:`free-threaded build`, when *iterable* is a :class:`list`,
184 :class:`set`, :class:`dict`, or dict view, both *list* and *iterable*
185 (or its underlying dict) are locked for the duration of the operation.
186 For other iterables, only *list* is locked; *iterable* may be
187 concurrently modified by another thread.
188
189
190 .. c:function:: int PyList_Clear(PyObject *list)
191
192 Remove all items from *list*. This is the same as
193 ``PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)`` and analogous to
194 ``list.clear()`` or ``del list[:]``.
195
196 Raise an exception and return ``-1`` if *list* is not a :class:`list`
197 object. Return 0 on success.
198
199 .. versionadded:: 3.13
200
201
202 .. c:function:: int PyList_Sort(PyObject *list)
203
204 Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
205 failure. This is equivalent to ``list.sort()``.
206
207 .. note::
208
209 In the :term:`free-threaded build`, element comparison via
210 :meth:`~object.__lt__` can execute arbitrary Python code, during which
211 the :term:`per-object lock` may be temporarily released. For built-in
212 types (:class:`str`, :class:`int`, :class:`float`), the lock is not
213 released during comparison.
214
215
216 .. c:function:: int PyList_Reverse(PyObject *list)
217
218 Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
219 failure. This is the equivalent of ``list.reverse()``.
220
221
222 .. c:function:: PyObject* PyList_AsTuple(PyObject *list)
223
224 .. index:: pair: built-in function; tuple
225
226 Return a new tuple object containing the contents of *list*; equivalent to
227 ``tuple(list)``.