リストオブジェクト
******************

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