タプルオブジェクト (tuple object)

type PyTupleObject

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

PyTypeObject PyTuple_Type

次に属します: Stable ABI.

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

int PyTuple_Check(PyObject *p)

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

int PyTuple_CheckExact(PyObject *p)

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

PyObject *PyTuple_New(Py_ssize_t len)

戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

サイズ len の新しいタプルオブジェクトを返します。 失敗した場合は例外を設定して NULL を返します。

PyObject *PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)

Thread safety: Atomic.

要素数 size のタプルを作成し、array から新しいタプルに参照をコピーします。

size が 0 の場合、array は NULL でも構いません。

成功した場合は新しい参照を返します。 エラーの場合は例外を設定して NULL を返します。

Added in version 3.15.

PyObject *PyTuple_Pack(Py_ssize_t n, ...)

戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

サイズ n の新しいタプルオブジェクトを返します。 失敗した場合は例外を設定して NULL を返します。 タプルの各値は、続く n 個の C 引数が指す Python オブジェクトで初期化されます。 PyTuple_Pack(2, a, b) は Py_BuildValue("(OO)", a, b) と同等です。

Py_ssize_t PyTuple_Size(PyObject *p)

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

タプルオブジェクトへのポインタを受け取り、そのタプルのサイズを返します。 エラーの場合は例外を設定して -1 を返します。

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

Thread safety: Atomic.

PyTuple_Size() と同様ですが、エラーチェックを行いません。

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

戻り値: 借用参照。 次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

p の指すタプルオブジェクト内の、位置 pos にあるオブジェクトを返します。 pos が負であるか範囲を超えている場合、 NULL を返して IndexError 例外をセットします。

返される参照はタプル p からの借用参照です (つまり、p への参照を保持している間だけ有効です)。 強参照 を取得するには、Py_NewRef(PyTuple_GetItem(...)) または PySequence_GetItem() を使ってください。

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

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

PyTuple_GetItem() に似ていますが、引数に対するエラーチェックを行いません。

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

p が指すタプルの low から high までのスライスを返します。 失敗した場合は例外を設定して NULL を返します。

Python の式 p[low:high] と同等です。 タプルの末尾からのインデックス指定はサポートしていません。

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

p が指すタプルの位置 pos に、オブジェクト o への参照を挿入します。 成功した場合は 0 を返します。 pos が範囲外の場合は、IndexError 例外を設定して -1 を返します。 この関数は、作成したばかりのタプルに値を設定するためだけに使ってください。 既存のタプルに使うとスレッドセーフではありません。

注釈

この関数は o への参照を「盗み」、タプルのその位置にすでにあった要素への参照を破棄します (NULL だった場合を除きます)。

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

Thread safety: Safe to call from multiple threads with external synchronization only.

PyTuple_SetItem() と同様ですが、エラーチェックを行いません。 作成したばかりのタプルに値を設定するため だけ に使ってください。 既存のタプルに使うとスレッドセーフではありません。

Python を デバッグモード または アサーションを有効にして ビルドした場合、アサーションによる境界チェックが行われます。

注釈

この関数は o への参照を「盗みます」。 PyTuple_SetItem() と異なり、置き換えられる要素への参照は破棄 しません。 タプルの位置 pos にすでに参照があれば、その参照はリークします。

警告

このマクロは、新しく作成したタプルに だけ 使ってください。 すでに使われているタプル (つまり参照カウントが 1 より大きいタプル) に使うと、未定義の動作を引き起こす可能性があります。

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

Thread safety: Safe to call from multiple threads with external synchronization only.

Resize a tuple. newsize will be the new length of the tuple.

Because tuples are supposed to be immutable, this should only be used if there is only one reference to the object. Do not use this if the tuple may already be known to some other part of the code. The tuple hash value must not be computed yet.

The tuple will always grow or shrink at the end. Think of this as destroying the old tuple and creating a new one, only more efficiently.

Returns 0 on success. Client code should never assume that the resulting value of *p will be the same as before calling this function. If the object referenced by *p is replaced, the original *p is destroyed.

On failure, returns -1 and sets *p to NULL, and raises MemoryError or SystemError.

While tuple objects are usually immutable in Python, this special C API allows mutating a tuple object in-place. The returned tuple object can still be mutated using PyTuple_SetItem(); except if newsize is zero in which case it returns the immutable empty tuple.

バージョン 3.16.0a1 (unreleased) で変更: The function now fails if the tuple hash value was already computed.

Struct Sequence オブジェクト

struct sequence オブジェクトは 名前付きタプル、つまり属性を通じても要素にアクセスできるシーケンスです。 collections.namedtuple() に似ていますが、インターフェースは多少異なります。

struct sequence を作成するには、まず専用の struct sequence 型を作成する必要があります。

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)

戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

後述の desc 中のデータから新しい struct sequence 型を生成します。返される型のインスタンスは PyStructSequence_New() で生成できます。

失敗した場合は例外を設定して NULL を返します。

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

Thread safety: Safe to call without external synchronization on distinct objects.

struct sequence 型である type を desc をもとにその場で初期化します。

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

Thread safety: Safe to call without external synchronization on distinct objects.

PyStructSequence_InitType() と同様ですが、成功した場合は 0 を返し、失敗した場合は例外を設定して -1 を返します。

Added in version 3.4.

type PyStructSequence_Desc

次に属します: Stable ABI (すべてのメンバーを含む).

生成するstruct sequence 型のメタデータを保持します。

const char *name

型の完全修飾名。 ヌル終端された UTF-8 エンコードの文字列です。 モジュール名を含む必要があります。

const char *doc

型の docstring へのポインタ。 省略する場合は NULL。

PyStructSequence_Field *fields

新しい型のフィールド名を持つ、NULL 終端の配列へのポインタ。

int n_in_sequence

タプルとして使う場合に Python 側から見えるフィールドの数。

type PyStructSequence_Field

次に属します: Stable ABI (すべてのメンバーを含む).

struct sequence のフィールドを記述します。 struct sequence はタプルをモデルとしているので、すべてのフィールドは PyObject* 型です。 PyStructSequence_Desc の fields 配列内のインデックスによって、struct sequence のどのフィールドを記述するかが決まります。

const char *name

フィールド名。 名前付きフィールドの一覧を終了するには NULL、名前を付けないフィールドには PyStructSequence_UnnamedField を指定します。

const char *doc

フィールドの docstring。 省略する場合は NULL。

const char *const PyStructSequence_UnnamedField

次に属します: Stable ABI (バージョン 3.11 より).

フィールド名を名前がないままするための特殊な値。

バージョン 3.9 で変更: 型が char * から変更されました。

PyObject *PyStructSequence_New(PyTypeObject *type)

戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

type のインスタンスを生成します。 type は PyStructSequence_NewType() によって事前に生成していなければなりません。

失敗した場合は例外を設定して NULL を返します。

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)

戻り値: 借用参照。 次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

p が指す struct sequence の位置 pos にあるオブジェクトを返します。 返される参照は struct sequence p からの借用参照です (つまり、p への参照を保持している間だけ有効です)。

Python を デバッグモード または アサーションを有効にして ビルドした場合、アサーションによる境界チェックが行われます。

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)

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

PyStructSequence_GetItem() の別名です。

バージョン 3.13 で変更: PyStructSequence_GetItem() の別名として実装されるようになりました。

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

struct sequence p の pos の位置にあるフィールドに値 o を設定します。PyTuple_SET_ITEM() のように、生成したてのインスタンスに対してのみ使用すべきです。

Python を デバッグモード または アサーションを有効にして ビルドした場合、アサーションによる境界チェックが行われます。

注釈

この関数は o への参照を「盗みます」。

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

Thread safety: Safe to call from multiple threads with external synchronization only.

PyStructSequence_SetItem() の別名です。

バージョン 3.13 で変更: PyStructSequence_SetItem() の別名として実装されるようになりました。