List（串列）物件¶
-
PyTypeObject PyList_Type¶
- 為 穩定 ABI 的一部分.
此
PyTypeObject實例表示 Python 的 list 型別。這與 Python 層中的list是同一個物件。
-
int PyList_Check(PyObject *p)¶
- Thread safety: Atomic.
如果 p 是一個 list 物件或者是 list 型別之子型別的實例，就回傳 true。這個函式永遠會成功執行。
-
int PyList_CheckExact(PyObject *p)¶
- Thread safety: Atomic.
如果 p 是一個 list 物件但不是 list 型別的子型別的實例，就回傳 true。這個函式永遠會成功執行。
-
PyObject *PyList_New(Py_ssize_t len)¶
- 回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.
成功時回傳長度為 len 的新串列，失敗時回傳
NULL。備註
如果 len 大於零，則回傳的串列物件之項目將被設定為
NULL。因此，在使用PyList_SetItem()或PyList_SET_ITEM()來將所有項目設定為一個真實物件前，你無法使用像是PySequence_SetItem()的抽象 API 函式，也不能將物件暴露 (expose) 給 Python 程式碼。以下 API 在串列完全初始化之前是安全的：PyList_SetItem()和PyList_SET_ITEM()。
-
Py_ssize_t PyList_Size(PyObject *list)¶
- 為 穩定 ABI 的一部分. Thread safety: Atomic.
回傳 list 串列物件的長度；這相當於串列物件的
len(list)。
-
Py_ssize_t PyList_GET_SIZE(PyObject *list)¶
- Thread safety: Atomic.
與
PyList_Size()類似，但沒有錯誤檢查。
-
PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)¶
- 回傳值：新的參照。 為 穩定 ABI 的一部分 自 3.13 版本開始. Thread safety: Atomic.
回傳 list 指向的串列中位於 index 位置的物件。該位置不可為負數；並不支援從串列尾末開始索引。如果 index 超出邊界範圍 (
<0 or >=len(list)) 則回傳NULL並設定IndexError例外。在 3.13 版被加入.
-
PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)¶
- 回傳值：借用參照。 為 穩定 ABI 的一部分. Thread safety: Safe to call from multiple threads with external synchronization only.
與
PyList_GetItemRef()類似，但回傳一個 borrowed reference 而非一個 strong reference。備註
In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the list concurrently. Prefer
PyList_GetItemRef(), which returns a strong reference.
-
PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)¶
- 回傳值：借用參照。 Thread safety: Safe to call from multiple threads with external synchronization only.
與
PyList_GetItem()類似，但沒有錯誤檢查。備註
In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the list concurrently. Prefer
PyList_GetItemRef(), which returns a strong reference.
-
int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)¶
- 為 穩定 ABI 的一部分. Thread safety: Atomic.
將串列中索引 index 處的項目設定為 item。成功時回傳
0。如果 index 超出邊界範圍則回傳-1並設定一個IndexError例外。備註
此函式「竊取」對 item 的參照，並丟棄對串列中受影響位置上已存在項目的參照。
-
void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)¶
- Thread safety: Safe to call from multiple threads with external synchronization only.
PyList_SetItem()的巨集形式，沒有錯誤檢查。這通常僅用於填充沒有已存在內容的新串列。如果 Python 是以偵錯模式或
with assertions建置，則會進行作為斷言（asserting）的邊界檢查。備註
該巨集「竊取」對 item 的參照，並且與
PyList_SetItem()不同的是，它不會丟棄對任意被替換項目的參照；list 中位置 i 的任何參照都將被洩漏 (leak)。備註
In the free-threaded build, this macro has no internal synchronization. It is normally only used to fill in new lists where no other thread has a reference to the list. If the list may be shared, use
PyList_SetItem()instead, which uses a per-object lock.
-
int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)¶
- 為 穩定 ABI 的一部分. Thread safety: Safe for concurrent use on the same object.
將項目 item 插入串列 list 中索引 index 的位置之前。如果成功則回傳
0；如果失敗則回傳-1並設定例外。類似於list.insert(index, item)。
-
int PyList_Append(PyObject *list, PyObject *item)¶
- 為 穩定 ABI 的一部分. Thread safety: Atomic.
將物件 item 附加到串列 list 的最後面。如果成功則回傳
0；如果不成功，則回傳-1並設定例外。類似於list.append(item)。
-
PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)¶
- 回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.
回傳 list 中的物件串列，其中包含 low 和 high 之間的物件。如果沒有成功則回傳
NULL並設定例外。類似於list[low:high]。不支援從串列尾末開始索引。
-
int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)¶
- 為 穩定 ABI 的一部分. Thread safety: Safe for concurrent use on the same object.
將 low 和