1.. highlightlang:: c 2 3.. _listobjects: 4 5List 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. 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. 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. 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`. 44 45 46.. c:function:: Py_ssize_t PyList_Size(PyObject *list) 47 48 .. index:: builtin: len 49 50 Return the length of the list object in *list*; this is equivalent to 51 ``len(list)`` on a list object. 52 53 54.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list) 55 56 Macro form of :c:func:`PyList_Size` without error checking. 57 58 59.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index) 60 61 Return the object at position *index* in the list pointed to by *list*. The 62 position must be positive, indexing from the end of the list is not 63 supported. If *index* is out of bounds, return *NULL* and set an 64 :exc:`IndexError` exception. 65 66 67.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i) 68 69 Macro form of :c:func:`PyList_GetItem` without error checking. 70 71 72.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item) 73 74 Set the item at index *index* in list to *item*. Return ``0`` on success 75 or ``-1`` on failure. 76 77 .. note:: 78 79 This function "steals" a reference to *item* and discards a reference to 80 an item already in the list at the affected position. 81 82 83.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o) 84 85 Macro form of :c:func:`PyList_SetItem` without error checking. This is 86 normally only used to fill in new lists where there is no previous content. 87 88 .. note:: 89 90 This macro "steals" a reference to *item*, and, unlike 91 :c:func:`PyList_SetItem`, does *not* discard a reference to any item that 92 is being replaced; any reference in *list* at position *i* will be 93 leaked. 94 95 96.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item) 97 98 Insert the item *item* into list *list* in front of index *index*. Return 99 ``0`` if successful; return ``-1`` and set an exception if unsuccessful. 100 Analogous to ``list.insert(index, item)``. 101 102 103.. c:function:: int PyList_Append(PyObject *list, PyObject *item) 104 105 Append the object *item* at the end of list *list*. Return ``0`` if 106 successful; return ``-1`` and set an exception if unsuccessful. Analogous 107 to ``list.append(item)``. 108 109 110.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high) 111 112 Return a list of the objects in *list* containing the objects *between* *low* 113 and *high*. Return *NULL* and set an exception if unsuccessful. Analogous 114 to ``list[low:high]``. Negative indices, as when slicing from Python, are not 115 supported. 116 117 118.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist) 119 120 Set the slice of *list* between *low* and *high* to the contents of 121 *itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may 122 be *NULL*, indicating the assignment of an empty list (slice deletion). 123 Return ``0`` on success, ``-1`` on failure. Negative indices, as when 124 slicing from Python, are not supported. 125 126 127.. c:function:: int PyList_Sort(PyObject *list) 128 129 Sort the items of *list* in place. Return ``0`` on success, ``-1`` on 130 failure. This is equivalent to ``list.sort()``. 131 132 133.. c:function:: int PyList_Reverse(PyObject *list) 134 135 Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on 136 failure. This is the equivalent of ``list.reverse()``. 137 138 139.. c:function:: PyObject* PyList_AsTuple(PyObject *list) 140 141 .. index:: builtin: tuple 142 143 Return a new tuple object containing the contents of *list*; equivalent to 144 ``tuple(list)``. 145 146 147.. c:function:: int PyList_ClearFreeList() 148 149 Clear the free list. Return the total number of freed items. 150 151 .. versionadded:: 3.3 152