# リストオブジェクト

type PyListObject

  この `PyObject` のサブタイプは Python のリストオブジェクトを表現します。

PyTypeObject PyList_Type
  次に属します: Stable ABI.

  この `PyTypeObject` のインスタンスは Python のリスト型を表現します。これは Python レイヤにおける `list` と同じオブジェクトです。

int PyList_Check(PyObject *p)
  Thread safety: Atomic.

  p がリストオブジェクトかリスト型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyList_CheckExact(PyObject *p)
  Thread safety: Atomic.

  p がリストオブジェクトだがリスト型のサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

PyObject *PyList_New(Py_ssize_t len)
  戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

  サイズが 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)
  次に属します: Stable 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)
  戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.13 より). Thread safety: Atomic.

  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.

  Added in version 3.13.

PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)
  戻り値: 借用参照。 次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  Like `PyList_GetItemRef()`, but returns a borrowed reference instead of a 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)
  次に属します: Stable ABI. Thread safety: Atomic.

  リストオブジェクト内の位置 index に、オブジェクト item を挿入します。 成功した場合には `0` を返します。 index が範囲を越えている場合、 `-1` を返して `IndexError` をセットします。

  注釈

  This function "steals" a reference to item, even on error. On success, it discards a reference to an item already in the list at the affected position (unless it was `NULL`).

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()` をマクロによる実装で、エラーチェックを行いません。このマクロは、新たなリストのまだ要素を入れたことのない位置に要素を入れるときにのみ使います。

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

  注釈

  This macro "steals" a reference to item, and, unlike `PyList_SetItem()`, does not discard a reference to any item that is being replaced; any reference in list at position i will be leaked.

  注釈

  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)
  次に属します: Stable 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)
  次に属します: Stable ABI. Thread safety: Atomic.

  オブジェクト item を list の末尾に追加します。成功すると `0` を返します; 失敗すると `-1` を返し、例外をセットします。`list.append(item)` に類似した機能です。

PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
  戻り値: 新しい参照。 次に属します: Stable 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)
  次に属します: Stable 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.

  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.

  Added in version 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.

  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.

  Added in version 3.13.

int PyList_Sort(PyObject *list)
  次に属します: Stable ABI. Thread safety: Safe for concurrent use on the same object.

  list の内容をインプレースでソートします。成功した場合には `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)
  次に属します: Stable ABI. Thread safety: Safe for concurrent use on the same object.

  list の要素をインプレースで反転します。成功した場合には `0` を、失敗した場合には `-1` を返します。`list.reverse()` と同じです。

PyObject *PyList_AsTuple(PyObject *list)
  戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

  list の内容が入った新たなタプルオブジェクトを返します; `tuple(list)` と同じです。