diff options
Diffstat (limited to 'Doc/c-api')
| -rw-r--r-- | Doc/c-api/list.rst | 71 |
1 files changed, 37 insertions, 34 deletions
diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst index 7006bab..81e57ea 100644 --- a/Doc/c-api/list.rst +++ b/Doc/c-api/list.rst @@ -17,8 +17,9 @@ List Objects .. index:: single: ListType (in module types) - This instance of :ctype:`PyTypeObject` represents the Python list type. This is - the same object as ``list`` and ``types.ListType`` in the Python layer. + This instance of :ctype:`PyTypeObject` represents the Python list type. + This is the same object as ``list`` and ``types.ListType`` in the Python + layer. .. cfunction:: int PyList_Check(PyObject *p) @@ -32,8 +33,8 @@ List Objects .. cfunction:: int PyList_CheckExact(PyObject *p) - Return true if *p* is a list object, but not an instance of a subtype of the - list type. + Return true if *p* is a list object, but not an instance of a subtype of + the list type. .. versionadded:: 2.2 @@ -44,10 +45,10 @@ List Objects .. note:: - If *length* is greater than zero, the returned list object's items are set to - ``NULL``. Thus you cannot use abstract API functions such as - :cfunc:`PySequence_SetItem` or expose the object to Python code before setting - all items to a real object with :cfunc:`PyList_SetItem`. + If *length* is greater than zero, the returned list object's items are + set to ``NULL``. Thus you cannot use abstract API functions such as + :cfunc:`PySequence_SetItem` or expose the object to Python code before + setting all items to a real object with :cfunc:`PyList_SetItem`. .. versionchanged:: 2.5 This function used an :ctype:`int` for *size*. This might require @@ -73,9 +74,10 @@ List Objects .. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index) - Return the object at position *pos* in the list pointed to by *p*. The position - must be positive, indexing from the end of the list is not supported. If *pos* - is out of bounds, return *NULL* and set an :exc:`IndexError` exception. + Return the object at position *pos* in the list pointed to by *p*. The + position must be positive, indexing from the end of the list is not + supported. If *pos* is out of bounds, return *NULL* and set an + :exc:`IndexError` exception. .. versionchanged:: 2.5 This function used an :ctype:`int` for *index*. This might require @@ -89,13 +91,13 @@ List Objects .. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item) - Set the item at index *index* in list to *item*. Return ``0`` on success or - ``-1`` on failure. + Set the item at index *index* in list to *item*. Return ``0`` on success + or ``-1`` on failure. .. note:: - This function "steals" a reference to *item* and discards a reference to an item - already in the list at the affected position. + This function "steals" a reference to *item* and discards a reference to + an item already in the list at the affected position. .. versionchanged:: 2.5 This function used an :ctype:`int` for *index*. This might require @@ -104,21 +106,22 @@ List Objects .. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o) - Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally - only used to fill in new lists where there is no previous content. + Macro form of :cfunc:`PyList_SetItem` without error checking. This is + normally only used to fill in new lists where there is no previous content. .. note:: This function "steals" a reference to *item*, and, unlike - :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it - being replaced; any reference in *list* at position *i* will be leaked. + :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that + it being replaced; any reference in *list* at position *i* will be + leaked. .. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item) - Insert the item *item* into list *list* in front of index *index*. Return ``0`` - if successful; return ``-1`` and set an exception if unsuccessful. Analogous to - ``list.insert(index, item)``. + Insert the item *item* into list *list* in front of index *index*. Return + ``0`` if successful; return ``-1`` and set an exception if unsuccessful. + Analogous to ``list.insert(index, item)``. .. versionchanged:: 2.5 This function used an :ctype:`int` for *index*. This might require @@ -127,16 +130,16 @@ List Objects .. cfunction:: int PyList_Append(PyObject *list, PyObject *item) - Append the object *item* at the end of list *list*. Return ``0`` if successful; - return ``-1`` and set an exception if unsuccessful. Analogous to - ``list.append(item)``. + Append the object *item* at the end of list *list*. Return ``0`` if + successful; return ``-1`` and set an exception if unsuccessful. Analogous + to ``list.append(item)``. .. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high) - Return a list of the objects in *list* containing the objects *between* *low* - and *high*. Return *NULL* and set an exception if unsuccessful. Analogous to - ``list[low:high]``. + Return a list of the objects in *list* containing the objects *between* + *low* and *high*. Return *NULL* and set an exception if unsuccessful. + Analogous to ``list[low:high]``. .. versionchanged:: 2.5 This function used an :ctype:`int` for *low* and *high*. This might @@ -145,10 +148,10 @@ List Objects .. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist) - Set the slice of *list* between *low* and *high* to the contents of *itemlist*. - Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*, - indicating the assignment of an empty list (slice deletion). Return ``0`` on - success, ``-1`` on failure. + Set the slice of *list* between *low* and *high* to the contents of + *itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may + be *NULL*, indicating the assignment of an empty list (slice deletion). + Return ``0`` on success, ``-1`` on failure. .. versionchanged:: 2.5 This function used an :ctype:`int` for *low* and *high*. This might @@ -157,8 +160,8 @@ List Objects .. cfunction:: int PyList_Sort(PyObject *list) - Sort the items of *list* in place. Return ``0`` on success, ``-1`` on failure. - This is equivalent to ``list.sort()``. + Sort the items of *list* in place. Return ``0`` on success, ``-1`` on + failure. This is equivalent to ``list.sort()``. .. cfunction:: int PyList_Reverse(PyObject *list) |