集合對象

這一章節詳細介紹了 set 和 frozenset 對象的公共 API。 任何未在下面列出的功能最好是使用抽象對象協議 (包括 PyObject_CallMethod(), PyObject_RichCompareBool(), PyObject_Hash(), PyObject_Repr(), PyObject_IsTrue(), PyObject_Print() 以及 PyObject_GetIter()) 或者抽象數字協議 (包括 PyNumber_And(), PyNumber_Subtract(), PyNumber_Or(), PyNumber_Xor(), PyNumber_InPlaceAnd(), PyNumber_InPlaceSubtract(), PyNumber_InPlaceOr() 以及 PyNumber_InPlaceXor()) 來訪問。

PySetObject

這個 PyObject 的子類型被用來保存 set 和 frozenset 對象的內部數據。 它類似于 PyDictObject，因為對于小尺寸集合來說它是固定大小的（很像元組的存儲方式），并且對于中等和大尺寸集合來說它將指向單獨的可變大小的內存塊（很像列表的存儲方式）。 此結構體的字段不應被視為公有并且可能發生改變。 所有訪問應當通過已寫入文檔的 API 來進行，而不可通過操縱結構體中的值。

PyTypeObject PySet_Type

這是一個 PyTypeObject 實例，表示 Python set 類型。

PyTypeObject PyFrozenSet_Type

這是一個 PyTypeObject 實例，表示 Python frozenset 類型。

下列類型檢查宏適用于指向任意 Python 對象的指針。 類似地，這些構造函數也適用于任意可迭代的 Python 對象。

int PySet_Check(PyObject?*p)

如果 p 是一個 set 對象或者是其子類型的實例則返回真值。

int PyFrozenSet_Check(PyObject?*p)

如果 p 是一個 frozenset 對象或者是其子類型的實例則返回真值。

int PyAnySet_Check(PyObject?*p)

如果 p 是一個 set 對象、frozenset 對象或者是其子類型的實例則返回真值。

int PyAnySet_CheckExact(PyObject?*p)

如果 p 是一個 set 對象或 frozenset 對象但不是其子類型的實例則返回真值。

int PyFrozenSet_CheckExact(PyObject?*p)

如果 p 是一個 frozenset 對象但不是其子類型的實例則返回真值。

PyObject* PySet_New(PyObject?*iterable)

Return value: New reference.

返回一個新的 set，其中包含 iterable 所返回的對象。 iterable 可以為 NULL 表示創建一個新的空集合。 成功時返回新的集合，失敗時返回 NULL。 如果 iterable 實際上不是可迭代對象則引發 TypeError。 該構造器也適用于拷貝集合 (c=set(s))。

PyObject* PyFrozenSet_New(PyObject?*iterable)

Return value: New reference.

返回一個新的 frozenset，其中包含 iterable 所返回的對象。 iterable 可以為 NULL 表示創建一個新的空凍結集合。 成功時返回新的凍結集合，失敗時返回 NULL。 如果 iterable 實際上不是可迭代對象則引發 TypeError。

下列函數和宏適用于 set 或 frozenset 的實例或是其子類型的實例。

Py_ssize_t PySet_Size(PyObject?*anyset)

返回 set 或 frozenset 對象的長度。 等價于 len(anyset)。 如果 anyset 不是 set, frozenset 或其子類型的實例則會引發 PyExc_SystemError。

Py_ssize_t PySet_GET_SIZE(PyObject?*anyset)

宏版本的 PySet_Size()，不帶錯誤檢測。

int PySet_Contains(PyObject?*anyset, PyObject?*key)

如果找到返回 1，如果未找到返回 0，如果遇到錯誤則返回 -1。 不同于 Python __contains__() 方法，此函數不會自動將不可哈希的集合轉換為臨時的凍結集合。 如果 key 為不可哈希對象則會引發 TypeError。 如果 anyset 不是 set, frozenset 或其子類型的實例則會引發 PyExc_SystemError。

int PySet_Add(PyObject?*set, PyObject?*key)

添加 key 到一個 set 實例。 也可用于 frozenset 實例（類似于 PyTuple_SetItem()，它可被用來為全新凍結集合在公開給其他代碼之前填充全新的值）。 成功時返回 0，失敗時返回 -1。 如果 key 為不可哈希對象則會引發 TypeError。 如果沒有增長空間則會引發 MemoryError。 如果 set 不是 set 或其子類型的實例則會引發 SystemError。

下列函數適用于 set 或其子類型的實例，但不可用于 frozenset 或其子類型的實例。

int PySet_Discard(PyObject?*set, PyObject?*key)

如果找到并移除返回 1，如果未找到（無操作）返回 0，如果遇到錯誤則返回 -1。 對于不存在的鍵不會引發 KeyError。 如果 key 為不可哈希對象則會引發 TypeError。 不同于 Python discard() 方法，此函數不會自動將不可哈希的集合轉換為臨時的凍結集合。 如果 set 不是 set 或其子類型的實例則會引發 PyExc_SystemError。

PyObject* PySet_Pop(PyObject?*set)

Return value: New reference.

返回 set 中任意對象的新引用，并從 set 中移除該對象。 失敗時返回 NULL。 如果集合為空則會引發 KeyError。 如果 set 不是 set 或其子類型的實例則會引發 SystemError。

int PySet_Clear(PyObject?*set)

清空現有字典的所有鍵值對。

int PySet_ClearFreeList()

清空釋放列表。 返回所釋放的條目數。

3.3 新版功能.