7.3.5 List Objects

7.3.5 List Objects

PyListObject: This subtype of PyObject represents a Python list object.

PyTypeObject PyList_Type: This instance of PyTypeObject represents the Python list type. This is the same object as types.ListType.

int PyList_Check( PyObject *p): Return true if p is a list object or an instance of a subtype of the list type. Changed in version 2.2: Allowed subtypes to be accepted.

int PyList_CheckExact( PyObject *p): Return true if p is a list object, but not an instance of a subtype of the list type. New in version 2.2.

PyObject* PyList_New( int len): Return value: New reference.
Return a new list of length len on success, or NULL on failure.

int PyList_Size( PyObject *list): Return the length of the list object in list; this is equivalent to "len(list)" on a list object.

int PyList_GET_SIZE( PyObject *list): Macro form of PyList_Size() without error checking.

PyObject* PyList_GetItem( PyObject *list, int index): Return value: Borrowed reference.
Return the object at position pos in the list pointed to by p. If pos is out of bounds, return NULL and set an IndexError exception.

PyObject* PyList_GET_ITEM( PyObject *list, int i): Return value: Borrowed reference.
Macro form of PyList_GetItem() without error checking.

int PyList_SetItem( PyObject *list, int index, PyObject *item): 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.

void PyList_SET_ITEM( PyObject *list, int i, PyObject *o): Macro form of 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 PyList_SetItem(), does not discard a reference to any item that it being replaced; any reference in list at position i will be leaked.

int PyList_Insert( PyObject *list, int 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).

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).

PyObject* PyList_GetSlice( PyObject *list, int low, int high): Return value: New reference.
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].

int PyList_SetSlice( PyObject *list, int low, int 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.

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()".

int PyList_Reverse( PyObject *list): Reverse the items of list in place. Return 0 on success, -1 on failure. This is the equivalent of "list.reverse()".

PyObject* PyList_AsTuple( PyObject *list): Return value: New reference.
Return a new tuple object containing the contents of list; equivalent to "tuple(list)".

See About this document... for information on suggesting changes.