# 集合对象

This section details the public API for `set` and `frozenset` objects. Any functionality not listed below is best accessed using either the abstract object protocol (including `PyObject_CallMethod()`, `PyObject_RichCompareBool()`, `PyObject_Hash()`, `PyObject_Repr()`, `PyObject_IsTrue()`, `PyObject_Print()`, and `PyObject_GetIter()`) or the abstract number protocol (including `PyNumber_And()`, `PyNumber_Subtract()`, `PyNumber_Or()`, `PyNumber_Xor()`, `PyNumber_InPlaceAnd()`, `PyNumber_InPlaceSubtract()`, `PyNumber_InPlaceOr()`, and `PyNumber_InPlaceXor()`).

`PySetObject`

  This subtype of `PyObject` is used to hold the internal data for both `set` and `frozenset` objects. It is like a `PyDictObject` in that it is a fixed size for small sets (much like tuple storage) and will point to a separate, variable sized block of memory for medium and large sized sets (much like list storage). None of the fields of this structure should be considered public and all are subject to change. All access should be done through the documented API rather than by manipulating the values in the structure.

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)

  Add key to a `set` instance. Also works with `frozenset` instances (like `PyTuple_SetItem()` it can be used to fill in the values of brand new frozensets before they are exposed to other code). Return `0` on success or `-1` on failure. Raise a `TypeError` if the key is unhashable. Raise a `MemoryError` if there is no room to grow. Raise a `SystemError` if set is not an instance of `set` or its subtype.

下列函数适用于 `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)

  清空现有字典的所有键值对。