リストオブジェクト

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 を返します。

注釈

len がゼロより大きい場合、返されたリストの要素は NULL に設定されています。 そのため、PyList_SetItem() や PyList_SET_ITEM() ですべての要素に実際のオブジェクトを設定するまでは、PySequence_SetItem() などの抽象 API 関数を使ったり、このオブジェクトを Python コードに公開したりしてはなりません。 リストを完全に初期化する前でも安全に使える API は PyList_SetItem() と 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.

list が指すリストの位置 index にあるオブジェクトを返します。 位置は非負でなければならず、リストの末尾からのインデックス指定はサポートしません。 index が範囲外 (<0 or >=len(list)) の場合、IndexError を設定して NULL を返します。

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.

PyList_GetItemRef() と似ていますが、強参照 ではなく 借用参照 を返します。

注釈

フリースレッドビルド では、別のスレッドが同時にリストを変更すると、返された 借用参照 が無効になる可能性があります。 強参照 を返す PyList_GetItemRef() を使ってください。

PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)

戻り値: 借用参照。 Thread safety: Safe to call from multiple threads with external synchronization only.

PyList_GetItem() に似ていますが、エラーチェックを行いません。

注釈

フリースレッドビルド では、別のスレッドが同時にリストを変更すると、返された 借用参照 が無効になる可能性があります。 強参照 を返す PyList_GetItemRef() を使ってください。

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)

次に属します: Stable ABI. Thread safety: Atomic.

リストのインデックス index にある要素を item に設定します。 成功すると 0 を返します。 index が範囲外の場合は、IndexError を設定して -1 を返します。

注釈

この関数は、エラーの場合も item への参照を「盗みます」。 成功すると、リストの指定位置にすでにあった要素が 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() をマクロによる実装で、エラーチェックを行いません。このマクロは、新たなリストのまだ要素を入れたことのない位置に要素を入れるときにのみ使います。

Python を デバッグモード または アサーションを有効にして ビルドした場合、アサーションで範囲を確認します。

注釈

このマクロは item への参照を「盗みます」。 PyList_SetItem() とは異なり、置き換える要素への参照は破棄 しません。 list の位置 i にある参照はリークします。

注釈

フリースレッドビルド では、このマクロは内部で同期しません。 通常は、他のスレッドが参照を持っていない新しいリストに要素を設定するためにだけ使います。 リストが共有される可能性がある場合は、代わりに オブジェクトごとのロック を使う PyList_SetItem() を使ってください。

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 を返します。 ただし、リストの末尾からのインデックスはサポートされていません。

注釈

フリースレッドビルド では、itemlist が list の場合、操作中は list と itemlist の両方をロックします。 他のイテラブル (または NULL) の場合は、list だけをロックします。

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 に相当します。

list が list オブジェクトでなければ、例外を送出して -1 を返します。 成功すると 0 を返します。

Added in version 3.13.

注釈

フリースレッドビルド では、iterable が list、set、dict、または辞書ビューの場合、操作中は list と iterable (辞書ビューの場合はその元の辞書) の両方をロックします。 他のイテラブルの場合は list だけをロックするため、別のスレッドが同時に iterable を変更する可能性があります。

int PyList_Clear(PyObject *list)

Thread safety: Atomic.

list のすべての要素を削除します。 PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL) と同じで、list.clear() や del list[:] に相当します。

list が list オブジェクトでなければ、例外を送出して -1 を返します。 成功すると 0 を返します。

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() と同じです。

注釈

フリースレッドビルド では、__lt__() による要素の比較で任意の Python コードが実行されることがあり、その間は オブジェクトごとのロック が一時的に解放される場合があります。 組み込み型 (str、int、float) の比較中は、ロックを解放しません。

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) と同じです。