Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _listobjects: |
| 4 | |
| 5 | List Objects |
| 6 | ------------ |
| 7 | |
| 8 | .. index:: object: list |
| 9 | |
| 10 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 11 | .. c:type:: PyListObject |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 12 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 13 | This subtype of :c:type:`PyObject` represents a Python list object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 14 | |
| 15 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 16 | .. c:var:: PyTypeObject PyList_Type |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 17 | |
Georg Brandl | 2aff335 | 2010-10-17 10:59:41 +0000 | [diff] [blame] | 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. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 20 | |
| 21 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 22 | .. c:function:: int PyList_Check(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 23 | |
| 24 | Return true if *p* is a list object or an instance of a subtype of the list |
| 25 | type. |
| 26 | |
| 27 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 28 | .. c:function:: int PyList_CheckExact(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 29 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 30 | Return true if *p* is a list object, but not an instance of a subtype of |
| 31 | the list type. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 32 | |
| 33 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 34 | .. c:function:: PyObject* PyList_New(Py_ssize_t len) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 35 | |
| 36 | Return a new list of length *len* on success, or *NULL* on failure. |
| 37 | |
| 38 | .. note:: |
| 39 | |
Georg Brandl | f7f5a82 | 2010-12-01 15:36:33 +0000 | [diff] [blame] | 40 | If *len* is greater than zero, the returned list object's items are |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 41 | set to ``NULL``. Thus you cannot use abstract API functions such as |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 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`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 44 | |
| 45 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 46 | .. c:function:: Py_ssize_t PyList_Size(PyObject *list) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 54 | .. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 55 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 56 | Macro form of :c:func:`PyList_Size` without error checking. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 57 | |
| 58 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 59 | .. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 60 | |
Georg Brandl | f7f5a82 | 2010-12-01 15:36:33 +0000 | [diff] [blame] | 61 | Return the object at position *index* in the list pointed to by *list*. The |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 62 | position must be positive, indexing from the end of the list is not |
Georg Brandl | f7f5a82 | 2010-12-01 15:36:33 +0000 | [diff] [blame] | 63 | supported. If *index* is out of bounds, return *NULL* and set an |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 64 | :exc:`IndexError` exception. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 65 | |
| 66 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 67 | .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 68 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 69 | Macro form of :c:func:`PyList_GetItem` without error checking. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 70 | |
| 71 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 72 | .. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 73 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 74 | Set the item at index *index* in list to *item*. Return ``0`` on success |
| 75 | or ``-1`` on failure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 76 | |
| 77 | .. note:: |
| 78 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 79 | This function "steals" a reference to *item* and discards a reference to |
| 80 | an item already in the list at the affected position. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 81 | |
| 82 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 83 | .. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 84 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 85 | Macro form of :c:func:`PyList_SetItem` without error checking. This is |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 86 | normally only used to fill in new lists where there is no previous content. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 87 | |
| 88 | .. note:: |
| 89 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 90 | This macro "steals" a reference to *item*, and, unlike |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 91 | :c:func:`PyList_SetItem`, does *not* discard a reference to any item that |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 92 | is being replaced; any reference in *list* at position *i* will be |
| 93 | leaked. |
| 94 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 95 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 96 | .. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 97 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 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)``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 101 | |
| 102 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 103 | .. c:function:: int PyList_Append(PyObject *list, PyObject *item) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 104 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 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)``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 108 | |
| 109 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 110 | .. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 111 | |
Georg Brandl | c6c3178 | 2009-06-08 13:41:29 +0000 | [diff] [blame] | 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. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 116 | |
| 117 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 118 | .. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 119 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 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). |
Georg Brandl | c6c3178 | 2009-06-08 13:41:29 +0000 | [diff] [blame] | 123 | Return ``0`` on success, ``-1`` on failure. Negative indices, as when |
| 124 | slicing from Python, are not supported. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 125 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 126 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 127 | .. c:function:: int PyList_Sort(PyObject *list) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 128 | |
Jeroen Ruigrok van der Werven | 47a7d70 | 2009-04-27 05:43:17 +0000 | [diff] [blame] | 129 | Sort the items of *list* in place. Return ``0`` on success, ``-1`` on |
| 130 | failure. This is equivalent to ``list.sort()``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 131 | |
| 132 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 133 | .. c:function:: int PyList_Reverse(PyObject *list) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 139 | .. c:function:: PyObject* PyList_AsTuple(PyObject *list) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 140 | |
| 141 | .. index:: builtin: tuple |
| 142 | |
| 143 | Return a new tuple object containing the contents of *list*; equivalent to |
| 144 | ``tuple(list)``. |
Antoine Pitrou | 9a812cb | 2011-11-15 00:00:12 +0100 | [diff] [blame] | 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 |