# 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 的一部分.

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

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

  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 的一部分.

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

Py_ssize_t PyTuple_Size(PyObject *p)
  為 穩定 ABI 的一部分.

  拿取一個元組物件的指標，然後回傳此元組的大小。錯誤發生時，回傳 `-1` 並設定例外。

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

  就像 `PyTuple_Size()` 但沒有錯誤檢查。

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
  回傳值：借用參照。 為 穩定 ABI 的一部分.

  回傳 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)
  回傳值：借用參照。

  與 `PyTuple_GetItem()` 相似，但不檢查其引數。

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
  回傳值：新的參照。 為 穩定 ABI 的一部分.

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

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

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
  為 穩定 ABI 的一部分.

  於 p 指向的元組 pos 位置處插入對物件 o 的參照。成功時回傳 `0`，如果 pos 超出邊界則回傳 `-1`，並設定 `IndexError` 例外。

  備註

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

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

  與 `PyTuple_SetItem()` 相似，但不進行錯誤檢查，且應 只 用於填充全新的元組。

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

  備註

  此函式 "竊取" 對 o 的參照，且與 `PyTuple_SetItem()` 不同的是，此函式並 不 丟棄任何被替代項目的參照；元組中 pos 位置的所有參照皆會被洩漏。

  警告

  此巨集應 僅 用於新建立的元組。在正被使用中的元組（或換句話說，參照計數大於 1 的元組）上使用此巨集可能會導致未定義行為。

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

  可用於調整元組的大小。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 的一部分.

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

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

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

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

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

  與 `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 的一部分.

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

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

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
  回傳值：借用參照。 為 穩定 ABI 的一部分.

  回傳結構序列中由 p 指向 pos 處的物件。

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

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
  回傳值：借用參照。

  `PyStructSequence_GetItem()` 的別名。

  在 3.13 版的變更: 現在是被實作為 `PyStructSequence_GetItem()` 的一個別名。

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
  為 穩定 ABI 的一部分.

  將結構序列 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)

  `PyStructSequence_SetItem()` 的別名。

  在 3.13 版的變更: 現在是被實作為 `PyStructSequence_SetItem()` 的一個別名。