集合对象
********

这一节详细介绍了针对 "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()")。

type PySetObject

   这个 "PyObject" 的子类型被用来保存 "set" 和 "frozenset" 对象的内部
   数据。它类似于 "PyDictObject" 的地方在于对小尺寸集合来说它是固定大
   小的（很像元组的存储方式），而对于中等和大尺寸集合来说它将指向单独
   的可变大小的内存块（很像列表的存储方式）。此结构体的字段不应被视为
   公有并且可能发生改变。所有访问都应当通过已写入文档的 API 来进行而不
   可通过直接操纵结构体中的值。

PyTypeObject PySet_Type
    * 属于 稳定 ABI.*

   这是一个 "PyTypeObject" 实例，表示 Python "set" 类型。

PyTypeObject PyFrozenSet_Type
    * 属于 稳定 ABI.*

   这是一个 "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 PySet_CheckExact(PyObject *p)

   如果 *p* 是一个 "set" 对象但不是其子类型的实例则返回真值。此函数总
   是会成功执行。

   Added in version 3.10.

int PyAnySet_CheckExact(PyObject *p)

   如果 *p* 是一个 "set" 或 "frozenset" 对象但不是其子类型的实例则返回
   真值。此函数总是会成功执行。

int PyFrozenSet_CheckExact(PyObject *p)

   如果 *p* 是一个 "frozenset" 对象但不是其子类型的实例则返回真值。此
   函数总是会成功执行。

PyObject *PySet_New(PyObject *iterable)
    *返回值：新的引用。** 属于 稳定 ABI.** Thread safety: Safe for
   concurrent use on the same object.*

   返回一个新的 "set"，其中包含 *iterable* 所返回的对象。*iterable* 可
   以为 "NULL" 表示创建一个新的空集合。成功时返回新的集合，失败时返回
   "NULL"。如果 *iterable* 实际上不是可迭代对象则引发 "TypeError"。该
   构造器也适用于拷贝集合 ("c=set(s)")。

   备注:

     The operation is atomic on *free threading* when *iterable* is a
     "set", "frozenset" or "dict".

PyObject *PyFrozenSet_New(PyObject *iterable)
    *返回值：新的引用。** 属于 稳定 ABI.** Thread safety: Safe for
   concurrent use on the same object.*

   返回一个新的 "frozenset"，其中包含 *iterable* 所返回的对象。
   *iterable* 可以为 "NULL" 表示创建一个新的空冻结集合。成功时返回新的
   冻结集合，失败时返回 "NULL"。如果 *iterable* 实际上不是可迭代对象则
   引发 "TypeError".

   备注:

     The operation is atomic on *free threading* when *iterable* is a
     "set", "frozenset" or "dict".

下列函数和宏适用于 "set" 或 "frozenset" 的实例或是其子类型的实例。

Py_ssize_t PySet_Size(PyObject *anyset)
    * 属于 稳定 ABI.** Thread safety: Atomic.*

   返回 "set" 或 "frozenset" 对象的长度。等同于 "len(anyset)"。如果
   *anyset* 不是 "set", "frozenset" 或其子类型的实例，则会引发
   "SystemError"。

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
    * Thread safety: Atomic.*

   宏版本的 "PySet_Size()"，不带错误检测。

int PySet_Contains(PyObject *anyset, PyObject *key)
    * 属于 稳定 ABI.** Thread safety: Safe for concurrent use on the
   same object.*

   如果找到则返回 "1"，如果未找到则返回 "0"，如果遇到错误则返回 "-1"。
   与 Python "__contains__()" 方法不同，该函数不会自动将不可哈希的集合
   转换为临时冻结集合。如果 *key* 是不可哈希对象则会引发 "TypeError"。
   如果 *anyset* 不是 "set", "frozenset" 或其子类型的实例则会引发
   "SystemError"。

   备注:

     The operation is atomic on *free threading* when *key* is "str",
     "int", "float", "bool" or "bytes".

int PySet_Add(PyObject *set, PyObject *key)
    * 属于 稳定 ABI.** Thread safety: Safe for concurrent use on the
   same object.*

   添加 *key* 到一个 "set" 实例。也可用于 "frozenset" 实例（与
   "PyTuple_SetItem()" 的类似之处是它也可被用来为全新的冻结集合在公开
   给其他代码之前填充全新的值）。成功时返回 "0" 而失败时返回 "-1"。如
   果 *key* 为不可哈希对象则会引发 "TypeError"。如果没有增长空间则会引
   发 "MemoryError"。如果 *set* 不是 "set" 或其子类型的实例则会引发
   "SystemError".

   备注:

     The operation is atomic on *free threading* when *key* is "str",
     "int", "float", "bool" or "bytes".

下列函数适用于 "set" 或其子类型的实例，但不可用于 "frozenset" 或其子类
型的实例。

int PySet_Discard(PyObject *set, PyObject *key)
    * 属于 稳定 ABI.** Thread safety: Safe for concurrent use on the
   same object.*

   如果已找到并移除则返回 "1"，如果未找到则返回 "0" (不执行任何操作)，
   如果遇到错误则返回 "-1"。不会针对不存在的键引发 "KeyError"。如果
   *key* 不可哈希则会引发 "TypeError"。不同于 Python "discard()" 方法
   ，此函数不会自动将不可哈希的集合转换为临时的冻结集合。如果 *set* 不
   是 "set" 或其子类型的实例则会引发 "SystemError"。

   备注:

     The operation is atomic on *free threading* when *key* is "str",
     "int", "float", "bool" or "bytes".

PyObject *PySet_Pop(PyObject *set)
    *返回值：新的引用。** 属于 稳定 ABI.** Thread safety: Atomic.*

   返回 *set* 中任意对象的新引用，并从 *set* 中移除该对象。失败时返回
   "NULL"。如果集合为空则会引发 "KeyError"。如果 *set* 不是 "set" 或其
   子类型的实例则会引发 "SystemError" 异常。

int PySet_Clear(PyObject *set)
    * 属于 稳定 ABI.** Thread safety: Atomic.*

   清空一个现有集合的所有元素。成功时返回 "0"。如果 *set* 不是 "set"
   或其子类型的实例则返回 "-1" 并引发 "SystemError".

   备注:

     In the *free-threaded build*, the set is emptied before its
     entries are cleared, so other threads will observe an empty set
     rather than intermediate states.


已弃用的 API
============

PySet_MINSIZE

   A *soft deprecated* constant representing the size of an internal
   preallocated table inside "PySetObject" instances.

   该常量只是出于完整性考虑才被写入文档的，因为给定的 CPython 版本并不
   保证使用具有固定大小的预分配表。在不涉及不稳定的集合内部结构的代码
   中，可以将 "PySet_MINSIZE" 替换为较小的常量如 "8"。

   要查找集合的大小，请改用 "PySet_Size()"。
