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)"。
