Doc/c-api/list.rst

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