Spaces:
Running on Zero
Running on Zero
File size: 5,089 Bytes
9273228 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | # List Objects {#listobjects}
::: index
pair: object; list
:::
> This subtype of `PyObject`{.interpreted-text role="c:type"} represents a Python list object.
> This instance of `PyTypeObject`{.interpreted-text role="c:type"} represents the Python list type. This is the same object as `list`{.interpreted-text role="class"} in the Python layer.
> Return true if *p* is a list object or an instance of a subtype of the list type. This function always succeeds.
> Return true if *p* is a list object, but not an instance of a subtype of the list type. This function always succeeds.
> Return a new list of length *len* on success, or `NULL` on failure.
>
> :::: note
> ::: title
> Note
> :::
>
> If *len* is greater than zero, the returned list object\'s items are set to `NULL`. Thus you cannot use abstract API functions such as `PySequence_SetItem`{.interpreted-text role="c:func"} or expose the object to Python code before setting all items to a real object with `PyList_SetItem`{.interpreted-text role="c:func"} or `PyList_SET_ITEM()`{.interpreted-text role="c:func"}. The following APIs are safe APIs before the list is fully initialized: `PyList_SetItem()`{.interpreted-text role="c:func"} and `PyList_SET_ITEM()`{.interpreted-text role="c:func"}.
> ::::
> ::: index
> pair: built-in function; len
> :::
>
> Return the length of the list object in *list*; this is equivalent to `len(list)` on a list object.
> Similar to `PyList_Size`{.interpreted-text role="c:func"}, but without error checking.
> Return the object at position *index* in the list pointed to by *list*. The position must be non-negative; indexing from the end of the list is not supported. If *index* is out of bounds (`<0 or >=len(list)`), return `NULL` and set an `IndexError`{.interpreted-text role="exc"} exception.
>
> ::: versionadded
> 3.13
> :::
> Like `PyList_GetItemRef`{.interpreted-text role="c:func"}, but returns a `borrowed reference`{.interpreted-text role="term"} instead of a `strong reference`{.interpreted-text role="term"}.
> Similar to `PyList_GetItem`{.interpreted-text role="c:func"}, but without error checking.
> Set the item at index *index* in list to *item*. Return `0` on success. If *index* is out of bounds, return `-1` and set an `IndexError`{.interpreted-text role="exc"} exception.
>
> :::: note
> ::: title
> Note
> :::
>
> This function \"steals\" a reference to *item* and discards a reference to an item already in the list at the affected position.
> ::::
> Macro form of `PyList_SetItem`{.interpreted-text role="c:func"} without error checking. This is normally only used to fill in new lists where there is no previous content.
>
> Bounds checking is performed as an assertion if Python is built in `debug mode <debug-build>`{.interpreted-text role="ref"} or `with assertions
> <--with-assertions>`{.interpreted-text role="option"}.
>
> :::: note
> ::: title
> Note
> :::
>
> This macro \"steals\" a reference to *item*, and, unlike `PyList_SetItem`{.interpreted-text role="c:func"}, does *not* discard a reference to any item that is being replaced; any reference in *list* at position *i* will be leaked.
> ::::
> 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)`.
> 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)`.
> 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]`. Indexing from the end of the list is not supported.
> 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. Indexing from the end of the list is not supported.
> Extend *list* with the contents of *iterable*. This is the same as `PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)` and analogous to `list.extend(iterable)` or `list += iterable`.
>
> Raise an exception and return `-1` if *list* is not a `list`{.interpreted-text role="class"} object. Return 0 on success.
>
> ::: versionadded
> 3.13
> :::
> Remove all items from *list*. This is the same as `PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)` and analogous to `list.clear()` or `del list[:]`.
>
> Raise an exception and return `-1` if *list* is not a `list`{.interpreted-text role="class"} object. Return 0 on success.
>
> ::: versionadded
> 3.13
> :::
> Sort the items of *list* in place. Return `0` on success, `-1` on failure. This is equivalent to `list.sort()`.
> Reverse the items of *list* in place. Return `0` on success, `-1` on failure. This is the equivalent of `list.reverse()`.
> ::: index
> pair: built-in function; tuple
> :::
>
> Return a new tuple object containing the contents of *list*; equivalent to `tuple(list)`.
|