Set オブジェクト
****************

このセクションでは "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" と同じように、小さ
   い集合(set)に対しては(タプルのように)固定サイズであり、そうでない集
   合に対しては(リストと同じように)可変長のメモリブロックを用います。
   この構造体のどのフィールドも、公開されていると考えるべきではなく、
   変更される可能性があります。すべてのアクセスは、構造体の中の値を直
   接操作するのではなく、ドキュメントされた API を用いて行うべきです。

PyTypeObject PySet_Type
    * 次に属します: Stable ABI.*

   この "PyTypeObject" のインスタンスは、Python の "set" 型を表します
   。

PyTypeObject PyFrozenSet_Type
    * 次に属します: Stable ABI.*

   この "PyTypeObject" のインスタンスは、Python の "frozenset" 型を表
   します。

以降の型チェックマクロはすべての Python オブジェクトに対するポインタに
対して動作します。同様に、コンストラクタはすべてのイテレート可能な
Python オブジェクトに対して動作します。

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" オブジェクトだがサブタイプのインスタンスでない場合に真
   を返します。この関数は常に成功します。

   Added in version 3.10.

int PyAnySet_CheckExact(PyObject *p)

   *p* が "set" か "frozenset" のどちらかのオブジェクトであるときに
   true を返します。サブタイプのオブジェクトは含みません。この関数は常
   に成功します。

int PyFrozenSet_CheckExact(PyObject *p)

   *p* が "frozenset" オブジェクトだがサブタイプのインスタンスでない場
   合に真を返します。この関数は常に成功します。

PyObject *PySet_New(PyObject *iterable)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *iterable* が返すオブジェクトを含む新しい "set" を返します。
   *iterable* が "NULL" のときは、空の set を返します。 成功したら新し
   い set を、失敗したら "NULL" を返します。 *iterable* がイテレート可
   能でない場合は、 "TypeError" を送出します。 このコンストラクタは
   set をコピーするときにも使えます ("c=set(s)")。

PyObject *PyFrozenSet_New(PyObject *iterable)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *iterable* が返すオブジェクトを含む新しい "frozenset" を返します。
   *iterable* が "NULL" のときは、空の frozenset を返します。 成功時に
   は新しい set を、失敗時には "NULL" を返します。 *iterable* がイテレ
   ート可能でない場合は、 "TypeError" を送出します。

以降の関数やマクロは、 "set" と "frozenset" とそのサブタイプのインスタ
ンスに対して利用できます。

Py_ssize_t PySet_Size(PyObject *anyset)
    * 次に属します: Stable ABI.*

   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)

   エラーチェックを行わない、 "PySet_Size()" のマクロ形式。

int PySet_Contains(PyObject *anyset, PyObject *key)
    * 次に属します: Stable ABI.*

   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.

int PySet_Add(PyObject *set, PyObject *key)
    * 次に属します: Stable ABI.*

   "set" のインスタンスに *key* を追加します。 "frozenset" に対しても
   動作します ("PyTuple_SetItem()" のように、他のコードに見える前の新
   しい frozenset の値を埋めるために使用できます)。 成功したら "0" を
   、失敗したら "-1" を返します。 *key* がハッシュ可能でない場合は、
   "TypeError" を送出します。 *set* を大きくする余裕がない場合は、
   "MemoryError" を送出します。 *set* が "set" かそのサブタイプのイン
   スタンスでない場合は、 "SystemError" を送出します。

以降の関数は、 "set" とそのサブタイプに対して利用可能です。
"frozenset" とそのサブタイプには利用できません。

int PySet_Discard(PyObject *set, PyObject *key)
    * 次に属します: Stable ABI.*

   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.

PyObject *PySet_Pop(PyObject *set)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *set* の中の要素のどれかに対する新しい参照を返し、そのオブジェクト
   を *set* から削除します。 失敗したら "NULL" を返します。 set が空の
   場合には "KeyError" を送出します。 *set* が "set" とそのサブタイプ
   のインスタンスでない場合は、 "SystemError" を送出します。

int PySet_Clear(PyObject *set)
    * 次に属します: Stable ABI.*

   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.


Deprecated API
==============

PySet_MINSIZE

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

   This is documented solely for completeness, as there are no
   guarantees that a given version of CPython uses preallocated tables
   with a fixed size. In code that does not deal with unstable set
   internals, "PySet_MINSIZE" can be replaced with a small constant
   like "8".

   If looking for the size of a set, use "PySet_Size()" instead.
