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()" 的一
   個別名。
