# 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)`。