List（串列）物件

type PyListObject

PyObject 的這個子型別表示 Python 的 list（串列）物件。

PyTypeObject PyList_Type

為 穩定 ABI 的一部分.

此 PyTypeObject 實例表示 Python 的 list 型別。這與 Python 層中的 list 是同一個物件。

int PyList_Check(PyObject *p)

如果 p 是一個 list 物件或者是 list 型別之子型別的實例，就回傳 true。這個函式永遠會成功執行。

int PyList_CheckExact(PyObject *p)

如果 p 是一個 list 物件但不是 list 型別的子型別的實例，就回傳 true。這個函式永遠會成功執行。

PyObject *PyList_New(Py_ssize_t len)

回傳值：新的參照。 為 穩定 ABI 的一部分.

成功時回傳長度為 len 的新串列，失敗時回傳 NULL。

備註

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() or expose the object to Python code before setting all items to a real object with PyList_SetItem() or PyList_SET_ITEM(). The following APIs are safe APIs before the list is fully initialized: PyList_SetItem() and PyList_SET_ITEM().

Py_ssize_t PyList_Size(PyObject *list)

為 穩定 ABI 的一部分.

回傳 list 串列物件的長度；這相當於串列物件的 len(list)。

Py_ssize_t PyList_GET_SIZE(PyObject *list)

與 PyList_Size() 類似，但沒有錯誤檢查。

PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)

回傳值：新的參照。 為 穩定 ABI 的一部分 自 3.13 版本開始.

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

在 3.13 版被加入.

PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)

回傳值：借用參照。 為 穩定 ABI 的一部分.

Like PyList_GetItemRef(), but returns a borrowed reference instead of a strong reference.

PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)

回傳值：借用參照。

與 PyList_GetItem() 類似，但沒有錯誤檢查。

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)

為 穩定 ABI 的一部分.

將串列中索引 index 處的項目設定為 item。成功時回傳 0。如果 index 超出邊界範圍則回傳 -1 並設定一個 IndexError 例外。

備註

此函式「竊取」對 item 的參照，並丟棄對串列中受影響位置上已存在項目的參照。

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)

PyList_SetItem() 的巨集形式，沒有錯誤檢查。這通常僅用於填充沒有已存在內容的新串列。

Bounds checking is performed as an assertion if Python is built in debug mode or with assertions.

備註

該巨集「竊取」對 item 的參照，並且與 PyList_SetItem() 不同的是，它不會丟棄對任意被替換項目的參照；list 中位置 i 的任何參照都將被洩漏 (leak)。

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)

為 穩定 ABI 的一部分.

將項目 item 插入串列 list 中索引 index 的位置之前。如果成功則回傳 0；如果失敗則回傳 -1 並設定例外。類似於 list.insert(index, item)。

int PyList_Append(PyObject *list, PyObject *item)

為 穩定 ABI 的一部分.

將物件 item 附加到串列 list 的最後面。如果成功則回傳 0；如果不成功，則回傳 -1 並設定例外。類似於 list.append(item)。

PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)

回傳值：新的參照。 為 穩定 ABI 的一部分.

回傳 list 中的物件串列，其中包含 low 和 high 之間的物件。如果沒有成功則回傳 NULL 並設定例外。類似於 list[low:high]。不支援從串列尾末開始索引。

int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

為 穩定 ABI 的一部分.

將 low 和 high 之間的 list 切片設定為 itemlist 的內容。類似於 list[low:high] = itemlist。itemlist 可能為 NULL，表示分配一個空串列（切片刪除）。成功時回傳 0，失敗時則回傳 -1。不支援從串列尾末開始索引。

int PyList_Extend(PyObject *list, PyObject *iterable)

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 object. Return 0 on success.

在 3.13 版被加入.

int PyList_Clear(PyObject *list)

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 object. Return 0 on success.

在 3.13 版被加入.

int PyList_Sort(PyObject *list)

為 穩定 ABI 的一部分.

對 list 的項目進行原地 (in place) 排序。成功時回傳 0，失敗時回傳 -1。這相當於 list.sort()。

int PyList_Reverse(PyObject *list)

為 穩定 ABI 的一部分.

原地反轉 list 的項目。成功時回傳 0，失敗時回傳 -1。這相當於 list.reverse()。

PyObject *PyList_AsTuple(PyObject *list)

回傳值：新的參照。 為 穩定 ABI 的一部分.

回傳一個新的 tuple（元組）物件，其中包含 list 的內容；相當於 tuple(list)。