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

这一章节详细介绍了 "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.*

   Return a new "set" containing objects returned by the *iterable*.
   The *iterable* may be *NULL* to create a new empty set.  Return the
   new set on success or *NULL* on failure.  Raise "TypeError" if
   *iterable* is not actually iterable.  The constructor is also
   useful for copying a set ("c=set(s)").

PyObject* PyFrozenSet_New(PyObject *iterable)
    *Return value: New reference.*

   Return a new "frozenset" containing objects returned by the
   *iterable*. The *iterable* may be *NULL* to create a new empty
   frozenset.  Return the new set on success or *NULL* on failure.
   Raise "TypeError" if *iterable* is not actually iterable.

下列函数和宏适用于 "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.*

   Return a new reference to an arbitrary object in the *set*, and
   removes the object from the *set*.  Return *NULL* on failure.
   Raise "KeyError" if the set is empty. Raise a "SystemError" if
   *set* is not an instance of "set" or its subtype.

int PySet_Clear(PyObject *set)

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

int PySet_ClearFreeList()

   清空释放列表。 返回所释放的条目数。

   3.3 版新加入.
