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.** Thread safety:
   Safe for concurrent use on the same object.*

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

   注釈:

     *iterable* が "set"、"frozenset"、"dict"、"frozendict" の場合、こ
     の操作は *フリースレッドビルド* でアトミックです。

PyObject *PyFrozenSet_New(PyObject *iterable)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Safe for concurrent use on the same object.*

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

   注釈:

     *iterable* が "set"、"frozenset"、"dict"、"frozendict" の場合、こ
     の操作は *フリースレッドビルド* でアトミックです。

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

Py_ssize_t PySet_Size(PyObject *anyset)
    * 次に属します: Stable 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)
    * 次に属します: Stable ABI.** Thread safety: Safe for concurrent
   use on the same object.*

   見付かれば "1"、見付からなければ "0"、エラーが起きれば "-1" を返し
   ます。 Python の "__contains__()" メソッドとは異なり、ハッシュ不可
   能な集合を一時的な frozenset に自動変換しません。 *key* がハッシュ
   不可能な場合、"TypeError" を送出します。 *anyset* が "set"、
   "frozenset"、またはそのサブタイプのインスタンスでない場合、
   "SystemError" を送出します。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" の場合、この操作
     は *フリースレッドビルド* でアトミックです。

int PySet_Add(PyObject *set, PyObject *key)
    * 次に属します: Stable ABI.** Thread safety: Safe for concurrent
   use on the same object.*

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

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" の場合、この操作
     は *フリースレッドビルド* でアトミックです。

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

int PySet_Discard(PyObject *set, PyObject *key)
    * 次に属します: Stable ABI.** Thread safety: Safe for concurrent
   use on the same object.*

   見付かって削除した場合は "1"、見付からなかった場合は何もせず "0"、
   エラーが起きた場合は "-1" を返します。 キーが存在しなくても
   "KeyError" は送出しません。 *key* がハッシュ不可能な場合は
   "TypeError" を送出します。 Python の "discard()" メソッドとは異なり
   、ハッシュ不可能な集合を一時的な frozenset に自動変換しません。
   *set* が "set" またはそのサブタイプのインスタンスでない場合は、
   "SystemError" を送出します。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" の場合、この操作
     は *フリースレッドビルド* でアトミックです。

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

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

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

   既存の集合のすべての要素を取り除いて空にします。 成功すると "0" を
   返します。 *set* が "set" またはそのサブタイプのインスタンスでない
   場合、"SystemError" を送出して "-1" を返します。

   注釈:

     *フリースレッドビルド* では、エントリーをクリアする前に集合を空に
     するため、他のスレッドからは途中の状態ではなく空の集合が見えます
     。


非推奨の API
============

PySet_MINSIZE

   "PySetObject" インスタンスの内部に事前確保されたテーブルのサイズを
   表す定数。

   CPython のどのバージョンでも固定サイズの事前確保テーブルを使うとい
   う保証はないため、網羅性のためだけに記載しています。 集合の不安定な
   内部実装を扱わないコードでは、"PySet_MINSIZE" を "8" のような小さな
   定数に置き換えられます。

   集合のサイズを求める場合は、代わりに "PySet_Size()" を使ってくださ
   い。

   バージョン 3.14 で ソフト非推奨 <Soft deprecated>.
