# List（串列）物件

type PyListObject

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

  備註

  In the free-threaded build, when itemlist is a `list`, both list and itemlist are locked for the duration of the operation. For other iterables (or `NULL`), only list is locked.

int PyList_Extend(PyObject *list, PyObject *iterable)
  Thread safety: Safe for concurrent use on the same object.

  以 iterable 中的內容擴展 list。這與 `PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)` 相同，類似於 `list.extend(iterable)` 或 `list += iterable`。

  引發一個例外並回傳 `-1` 如果 list 不是一個 `list` 物件。如果成功回傳 0。

  在 3.13 版被加入.

  備註

  In the free-threaded build, when iterable is a `list`, `set`, `dict`, or dict view, both list and iterable (or its underlying dict) are locked for the duration of the operation. For other iterables, only list is locked; iterable may be concurrently modified by another thread.

int PyList_Clear(PyObject *list)
  Thread safety: Atomic.

  移除 list 中的所有項目。這與 `PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)` 相同，類似於 `list.clear()` 或 `del list[:]`。

  引發一個例外並回傳 `-1` 如果 list 不是一個 `list` 物件。如果成功回傳 0。

  在 3.13 版被加入.

int PyList_Sort(PyObject *list)
  為 穩定 ABI 的一部分. Thread safety: Safe for concurrent use on the same object.

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

  備註

  In the free-threaded build, element comparison via `__lt__()` can execute arbitrary Python code, during which the per-object lock may be temporarily released. For built-in types (`str`, `int`, `float`), the lock is not released during comparison.

int PyList_Reverse(PyObject *list)
  為 穩定 ABI 的一部分. Thread safety: Safe for concurrent use on the same object.

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

PyObject *PyList_AsTuple(PyObject *list)
  回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.

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