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