集合物件
********

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()").

type 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
    * 為 穩定 ABI 的一部分.*

   This is an instance of "PyTypeObject" representing the Python "set"
   type.

PyTypeObject PyFrozenSet_Type
    * 為 穩定 ABI 的一部分.*

   This is an instance of "PyTypeObject" representing the Python
   "frozenset" type.

The following type check macros work on pointers to any Python object.
Likewise, the constructor functions work with any iterable Python
object.

int PySet_Check(PyObject *p)

   如果 *p* 是 "set" 物件或是子類別的實例，則回傳 true。此函式總會成功
   執行。

int PyFrozenSet_Check(PyObject *p)

   如果 *p* 是 "frozenset" 物件或是子類別的實例，則回傳 true。此函式總
   會成功執行。

int PyAnySet_Check(PyObject *p)

   如果 *p* 是 "set" 物件、"frozenset" 物件，或是子類別的實例，則回傳
   true。此函式總會成功執行。

int PySet_CheckExact(PyObject *p)

   如果 *p* 是 "set" 物件但不是子類別的實例，則回傳 true。此函式總會成
   功執行。

   在 3.10 版被加入.

int PyAnySet_CheckExact(PyObject *p)

   如果 *p* 是 "set" 物件或 "frozenset" 物件但不是子類別的實例，則回傳
   true。此函式總會成功執行。

int PyFrozenSet_CheckExact(PyObject *p)

   如果 *p* 是 "frozenset" 物件但不是子類別的實例，則回傳 true。此函式
   總會成功執行。

PyObject *PySet_New(PyObject *iterable)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.** Thread safety: Safe
   for concurrent use on the same object.*

   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)").

   備註:

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

PyObject *PyFrozenSet_New(PyObject *iterable)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.** Thread safety: Safe
   for concurrent use on the same object.*

   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.

   備註:

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

The following functions and macros are available for instances of
"set" or "frozenset" or instances of their subtypes.

Py_ssize_t PySet_Size(PyObject *anyset)
    * 為 穩定 ABI 的一部分.** Thread safety: Atomic.*

   Return the length of a "set" or "frozenset" object. Equivalent to
   "len(anyset)".  Raises a "SystemError" if *anyset* is not a "set",
   "frozenset", or an instance of a subtype.

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

   Macro form of "PySet_Size()" without error checking.

int PySet_Contains(PyObject *anyset, PyObject *key)
    * 為 穩定 ABI 的一部分.** Thread safety: Safe for concurrent use
   on the same object.*

   Return "1" if found, "0" if not found, and "-1" if an error is
   encountered.  Unlike the Python "__contains__()" method, this
   function does not automatically convert unhashable sets into
   temporary frozensets.  Raise a "TypeError" if the *key* is
   unhashable. Raise "SystemError" if *anyset* is not a "set",
   "frozenset", or an instance of a subtype.

   備註:

     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.*

   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.

   備註:

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

The following functions are available for instances of "set" or its
subtypes but not for instances of "frozenset" or its subtypes.

int PySet_Discard(PyObject *set, PyObject *key)
    * 為 穩定 ABI 的一部分.** Thread safety: Safe for concurrent use
   on the same object.*

   Return "1" if found and removed, "0" if not found (no action
   taken), and "-1" if an error is encountered.  Does not raise
   "KeyError" for missing keys.  Raise a "TypeError" if the *key* is
   unhashable.  Unlike the Python "discard()" method, this function
   does not automatically convert unhashable sets into temporary
   frozensets. Raise "SystemError" if *set* is not an instance of
   "set" or its subtype.

   備註:

     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.*

   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)
    * 為 穩定 ABI 的一部分.** Thread safety: Atomic.*

   Empty an existing set of all elements. Return "0" on success.
   Return "-1" and raise "SystemError" if *set* is not an instance of
   "set" or its subtype.

   備註:

     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 constant representing the size of an internal preallocated table
   inside "PySetObject" instances.

   這僅為完整性而記錄於文件，且因為無法保證特定版本的 CPython 會使用具
   有固定大小的預分配表格。在不處理不穩定集合內部結構的程式碼中，
   "PySet_MINSIZE" 可以替換為像 "8" 這樣的小常數。

   如果要查詢集合的大小，請使用 "PySet_Size()"。

   Soft deprecated since version 3.14.
