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