Tuple（元組）物件

type PyTupleObject

此 PyObject 子型別代表 Python 元組物件

PyTypeObject PyTuple_Type

為 穩定 ABI 的一部分.

此 PyTypeObject 實例代表 Python 元組型別，與 Python 層中的 tuple 是同一物件

int PyTuple_Check(PyObject *p)

如果 p 為一元組物件或是元組型別的子型別實例時回傳 true。此函式總會執行成功

int PyTuple_CheckExact(PyObject *p)

如果 p 為一元組物件但不是元組型別的子型別實例時回傳 true。此函式總會執行成功

PyObject *PyTuple_New(Py_ssize_t len)

回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.

回傳一個長度為 len 的新元組物件，失敗會時回傳 NULL 並設定例外。

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

Thread safety: Atomic.

Create a tuple of size items and copy references from array to the new tuple.

array can be NULL if size is 0.

On success, return a new reference. On error, set an exception and return NULL.

在 3.15 版被加入.

PyObject *PyTuple_Pack(Py_ssize_t n, ...)

回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.

回傳一個長度為 n 的新元組物件，失敗時會回傳 NULL 並設定例外。元組值被初始化為指向 Python 物件的接續 n 個 C 引數。PyTuple_Pack(2, a, b) 等價於 Py_BuildValue("(OO)", a, b)。

Py_ssize_t PyTuple_Size(PyObject *p)

為 穩定 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)

回傳值：借用參照。 為 穩定 ABI 的一部分. Thread safety: Safe to call from multiple threads with external synchronization only.

回傳 p 指向的元組中位置 pos 處的物件。如果 pos 為負數或超出範圍，回傳 NULL 並設定 IndexError 例外。

回傳的參照借自元組 p（也就是說：它僅在你持有 p 的參照時有效）。若要取得一個 strong reference，請使用 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)

回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.

回傳由 p 指向的元組中介於 low 和 high 之間的切片或在錯誤時回傳 NULL 並設定例外。

這與 Python p[low:high] 運算式等價。但不支援從元組末端開始索引。

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

為 穩定 ABI 的一部分. Thread safety: Safe to call from multiple threads with external synchronization only.

Insert a reference to object o at position pos of the tuple pointed to by p. Return 0 on success. If pos is out of bounds, return -1 and set an IndexError exception. This function should only be used to fill in brand new tuples; using it on an existing tuple is thread-unsafe.

備註

此函式 "竊取" 對 o 的參照，並丟棄對元組中受影響位置的項目的參照。

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

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

Like PyTuple_SetItem(), but does no error checking, and should only be used to fill in brand new tuples, using it on an existing tuple is thread-unsafe.

若 Python 以 debug mode 或 with assertions 建置，則會進行作為斷言（asserting）的邊界檢查。

備註

此函式 "竊取" 對 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.

可用於調整元組的大小。newsize 將是元組的新長度。由於元組 應該 是不可變的，因此僅當物件只有一個參照時才應使用此方法。如果程式碼的其他部分已經知道該元組，則 不要 使用此方法。最終元組總會變大或縮小。可以將其理解為銷毀舊元組並建立一個新元組，只是有著更高的效率。成功時回傳 0。用戶端程式碼絕不應假設 *p 的結果值與呼叫此函式之前的值相同。如果 *p 參照的物件被替換，則原始的 *p 將被銷毀。失敗時，回傳 -1，並將 *p 設定為 NULL，並引發 MemoryError 或 SystemError 例外。

結構序列物件

A struct sequence object is a named tuple, that is, a sequence whose items can also be accessed through attributes. It is similar to collections.namedtuple(), but provides a slightly different interface.

To create a struct sequence, you first have to create a specific struct sequence type.

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)

回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.

從 desc 中的資料建立一個新的結構序列型別，如下所述。可以使用 PyStructSequence_New() 以建立產生結構序列型別的實例。

失敗時回傳 NULL 並設定例外。

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

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

從 desc 原地（in place）初始化結構序列型別 type。

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

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

與 PyStructSequence_InitType() 相似，但運行成功時回傳 0，運行失敗時回傳 -1 並設定例外。

在 3.4 版被加入.

type PyStructSequence_Desc

為 穩定 ABI 的一部分 （包含所有成員）.

包含要建立的結構序列化型別的中介資訊（meta information）。

const char *name

型別的完整限定名稱（Fully qualified name）；以 UTF-8 編碼並以空字元結尾。名稱必須包含完整的模組名稱。

const char *doc

指向型別說明文件（docstring）的指標或使用 NULL 表示忽略。

PyStructSequence_Field *fields

指向一個以 NULL 結尾的陣列指標，其包含新型別的欄位名稱。

int n_in_sequence

Python 端可以看到欄位的數目（如果作為元組使用）。

type PyStructSequence_Field

為 穩定 ABI 的一部分 （包含所有成員）.

描述結構序列的一個欄位。由於結構序列以元組作為原型，所有欄位的型別均為 PyObject*。PyStructSequence_Desc 在 fields 陣列中的索引決定了描述的是結構序列的哪個欄位。

const char *name

欄位名稱，或 NULL 表示命名欄位串列結束，設定為 PyStructSequence_UnnamedField 表示該欄位不命名。

const char *doc

欄位說明字串或為 NULL 表示忽略。

const char *const PyStructSequence_UnnamedField

為 穩定 ABI 的一部分 自 3.11 版本開始.

給定欄位名稱一個特別值，表示該欄位不命名。

在 3.9 版的變更: 型別原本是 char *，現已被修改。

PyObject *PyStructSequence_New(PyTypeObject *type)

回傳值：新的參照。 為 穩定 ABI 的一部分. Thread safety: Atomic.

建立 type 的實例，必須以 PyStructSequence_NewType() 建立。

失敗時回傳 NULL 並設定例外。

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)

回傳值：借用參照。 為 穩定 ABI 的一部分. Thread safety: Safe to call from multiple threads with external synchronization only.

Return the object at position pos in the struct sequence pointed to by p. The returned reference is borrowed from the struct sequence p (that is: it is only valid as long as you hold a reference to p).

若 Python 以 debug mode 或 with assertions 建置，則會進行作為斷言（asserting）的邊界檢查。

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)

為 穩定 ABI 的一部分. Thread safety: Safe to call from multiple threads with external synchronization only.

將結構序列 p 中索引 pos 處的欄位值設為 o。與 PyTuple_SET_ITEM() 類似，此函式僅套用於填充全新實例。

若 Python 以 debug mode 或 with assertions 建置，則會進行作為斷言（asserting）的邊界檢查。

備註

此函式 "竊取" 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() 的一個別名。