diff options
Diffstat (limited to 'Doc/c-api/list.rst')
| -rw-r--r-- | Doc/c-api/list.rst | 85 |
1 files changed, 50 insertions, 35 deletions
diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst index e2990e7..e971d36 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) @@ -29,8 +30,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. .. cfunction:: PyObject* PyList_New(Py_ssize_t len) @@ -39,10 +40,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 @@ -65,12 +66,17 @@ List Objects Macro form of :cfunc:`PyList_Size` without error checking. + .. versionchanged:: 2.5 + This macro returned an :ctype:`int`. This might require changes in your + code for properly supporting 64-bit systems. + .. 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 @@ -81,16 +87,20 @@ List Objects Macro form of :cfunc:`PyList_GetItem` without error checking. + .. versionchanged:: 2.5 + This macro used an :ctype:`int` for *i*. This might require changes in + your code for properly supporting 64-bit systems. + .. 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 @@ -99,21 +109,26 @@ 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. + This macro "steals" a reference to *item*, and, unlike + :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that + is being replaced; any reference in *list* at position *i* will be + leaked. + + .. versionchanged:: 2.5 + This macro used an :ctype:`int` for *i*. This might require + changes in your code for properly supporting 64-bit systems. .. 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 @@ -122,16 +137,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 @@ -140,10 +155,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 @@ -152,8 +167,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) |