1.. highlight:: 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. 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`. 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 non-negative; indexing from the end of the list is not 63 supported. If *index* is out of bounds (<0 or >=len(list)), 64 return ``NULL`` and set an :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 If *index* is out of bounds, return ``-1`` and set an :exc:`IndexError` 76 exception. 77 78 .. note:: 79 80 This function "steals" a reference to *item* and discards a reference to 81 an item already in the list at the affected position. 82 83 84.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o) 85 86 Macro form of :c:func:`PyList_SetItem` without error checking. This is 87 normally only used to fill in new lists where there is no previous content. 88 89 .. note:: 90 91 This macro "steals" a reference to *item*, and, unlike 92 :c:func:`PyList_SetItem`, does *not* discard a reference to any item that 93 is being replaced; any reference in *list* at position *i* will be 94 leaked. 95 96 97.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item) 98 99 Insert the item *item* into list *list* in front of index *index*. Return 100 ``0`` if successful; return ``-1`` and set an exception if unsuccessful. 101 Analogous to ``list.insert(index, item)``. 102 103 104.. c:function:: int PyList_Append(PyObject *list, PyObject *item) 105 106 Append the object *item* at the end of list *list*. Return ``0`` if 107 successful; return ``-1`` and set an exception if unsuccessful. Analogous 108 to ``list.append(item)``. 109 110 111.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high) 112 113 Return a list of the objects in *list* containing the objects *between* *low* 114 and *high*. Return ``NULL`` and set an exception if unsuccessful. Analogous 115 to ``list[low:high]``. Indexing from the end of the list is not 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. Indexing from the end of the 124 list is 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