/Doc/c-api/list.rst

  1.. highlightlang:: c
  2
  3.. _listobjects:
  4
  5List Objects
  6------------
  7
  8.. index:: object: list
  9
 10
 11.. ctype:: PyListObject
 12
 13   This subtype of :ctype:`PyObject` represents a Python list object.
 14
 15
 16.. cvar:: PyTypeObject PyList_Type
 17
 18   .. index:: single: ListType (in module types)
 19
 20   This instance of :ctype:`PyTypeObject` represents the Python list type.
 21   This is the same object as ``list`` and ``types.ListType`` in the Python
 22   layer.
 23
 24
 25.. cfunction:: int PyList_Check(PyObject *p)
 26
 27   Return true if *p* is a list object or an instance of a subtype of the list
 28   type.
 29
 30   .. versionchanged:: 2.2
 31      Allowed subtypes to be accepted.
 32
 33
 34.. cfunction:: int PyList_CheckExact(PyObject *p)
 35
 36   Return true if *p* is a list object, but not an instance of a subtype of
 37   the list type.
 38
 39   .. versionadded:: 2.2
 40
 41
 42.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
 43
 44   Return a new list of length *len* on success, or *NULL* on failure.
 45
 46   .. note::
 47
 48      If *length* is greater than zero, the returned list object's items are
 49      set to ``NULL``.  Thus you cannot use abstract API functions such as
 50      :cfunc:`PySequence_SetItem`  or expose the object to Python code before
 51      setting all items to a real object with :cfunc:`PyList_SetItem`.
 52
 53   .. versionchanged:: 2.5
 54      This function used an :ctype:`int` for *size*. This might require
 55      changes in your code for properly supporting 64-bit systems.
 56
 57
 58.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
 59
 60   .. index:: builtin: len
 61
 62   Return the length of the list object in *list*; this is equivalent to
 63   ``len(list)`` on a list object.
 64
 65   .. versionchanged:: 2.5
 66      This function returned an :ctype:`int`. This might require changes in
 67      your code for properly supporting 64-bit systems.
 68
 69
 70.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
 71
 72   Macro form of :cfunc:`PyList_Size` without error checking.
 73
 74   .. versionchanged:: 2.5
 75      This macro returned an :ctype:`int`. This might require changes in your
 76      code for properly supporting 64-bit systems.
 77
 78
 79.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
 80
 81   Return the object at position *pos* in the list pointed to by *p*.  The
 82   position must be positive, indexing from the end of the list is not
 83   supported.  If *pos* is out of bounds, return *NULL* and set an
 84   :exc:`IndexError` exception.
 85
 86   .. versionchanged:: 2.5
 87      This function used an :ctype:`int` for *index*. This might require
 88      changes in your code for properly supporting 64-bit systems.
 89
 90
 91.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
 92
 93   Macro form of :cfunc:`PyList_GetItem` without error checking.
 94
 95   .. versionchanged:: 2.5
 96      This macro used an :ctype:`int` for *i*. This might require changes in
 97      your code for properly supporting 64-bit systems.
 98
 99
100.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
101
102   Set the item at index *index* in list to *item*.  Return ``0`` on success
103   or ``-1`` on failure.
104
105   .. note::
106
107      This function "steals" a reference to *item* and discards a reference to
108      an item already in the list at the affected position.
109
110   .. versionchanged:: 2.5
111      This function used an :ctype:`int` for *index*. This might require
112      changes in your code for properly supporting 64-bit systems.
113
114
115.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
116
117   Macro form of :cfunc:`PyList_SetItem` without error checking. This is
118   normally only used to fill in new lists where there is no previous content.
119
120   .. note::
121
122      This macro "steals" a reference to *item*, and, unlike
123      :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that
124      it being replaced; any reference in *list* at position *i* will be
125      leaked.
126
127   .. versionchanged:: 2.5
128      This macro used an :ctype:`int` for *i*. This might require
129      changes in your code for properly supporting 64-bit systems.
130
131
132.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
133
134   Insert the item *item* into list *list* in front of index *index*.  Return
135   ``0`` if successful; return ``-1`` and set an exception if unsuccessful.
136   Analogous to ``list.insert(index, item)``.
137
138   .. versionchanged:: 2.5
139      This function used an :ctype:`int` for *index*. This might require
140      changes in your code for properly supporting 64-bit systems.
141
142
143.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
144
145   Append the object *item* at the end of list *list*. Return ``0`` if
146   successful; return ``-1`` and set an exception if unsuccessful.  Analogous
147   to ``list.append(item)``.
148
149
150.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
151
152   Return a list of the objects in *list* containing the objects *between*
153   *low* and *high*.  Return *NULL* and set an exception if unsuccessful.
154   Analogous to ``list[low:high]``.
155
156   .. versionchanged:: 2.5
157      This function used an :ctype:`int` for *low* and *high*. This might
158      require changes in your code for properly supporting 64-bit systems.
159
160
161.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
162
163   Set the slice of *list* between *low* and *high* to the contents of
164   *itemlist*.  Analogous to ``list[low:high] = itemlist``. The *itemlist* may
165   be *NULL*, indicating the assignment of an empty list (slice deletion).
166   Return ``0`` on success, ``-1`` on failure.
167
168   .. versionchanged:: 2.5
169      This function used an :ctype:`int` for *low* and *high*. This might
170      require changes in your code for properly supporting 64-bit systems.
171
172
173.. cfunction:: int PyList_Sort(PyObject *list)
174
175   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on
176   failure.  This is equivalent to ``list.sort()``.
177
178
179.. cfunction:: int PyList_Reverse(PyObject *list)
180
181   Reverse the items of *list* in place.  Return ``0`` on success, ``-1`` on
182   failure.  This is the equivalent of ``list.reverse()``.
183
184
185.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
186
187   .. index:: builtin: tuple
188
189   Return a new tuple object containing the contents of *list*; equivalent to
190   ``tuple(list)``.