##
14 集合オブジェクト (Set Objects)

バージョン 2.5 で 新たに追加 された仕様です。

このセクションでは `set` と `frozenset` の公開APIについて詳しく述べます。 以降で説明していない機能は、抽象オブジェクトプロトコル ( `PyObject_CallMethod()`, `PyObject_RichCompareBool()`, `PyObject_Hash()`, `PyObject_Repr()`, `PyObject_IsTrue()`, `PyObject_Print()`, `PyObject_GetIter()` を含む) か抽象数値プロトコル ( `PyNumber_Add()`, `PyNumber_Subtract()`, `PyNumber_Or()`, `PyNumber_Xor()`, `PyNumber_InPlaceAdd()`, `PyNumber_InPlaceSubtract()`, `PyNumber_InPlaceOr()`, `PyNumber_InPlaceXor()` を含む) を使って利用できます。

`PySetObject`
  この `PyObject` を継承した型は、 `set` と `frozenset` 両方の 内部データを保存するのに用いられます。 `PyDictObject` と同じように、小さい集合(set)に対しては(タプルのように)固定サイズであり、 そうでない集合に対しては(リストと同じように)可変長のメモリブロックを用います。 この構造体のどのフィールドも、非公開で変更される可能性があると考えて下さい。 すべてのアクセスは、構造体の中の値を直接操作するのではなく、ドキュメントされた APIを用いて行うべきです。

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

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

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

int `PyAnySet_Check`( | PyObject *p)

  p が `set` か `frozenset` 、あるいはそのサブタイプのオブジェクトで あれば、trueを返します。

int `PyAnySet_CheckExact`( | PyObject *p)

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

int `PyFrozenSet_CheckExact`( | PyObject *p)

  p が `frozenset` のオブジェクトであるときに true を返します。 サブタイプのオブジェクトは含みません。

PyObject* `PySet_New`( | PyObject *iterable)

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

PyObject* `PyFrozenSet_New`( | PyObject *iterable)

  戻り値: 新たな参照.
  iterable が返すオブジェクトを含む新しい `frozenset` を返します。 iterable が `NULL` のときは、空のfrozensetを返します。 iterable がイテレート可能で無い場合は、 `TypeError` を送出します。

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

int `PySet_Size`( | PyObject *anyset)

  `set` や `frozenset` のオブジェクトの長さを返します。 "`len(anyset)`" と同じです。 anyset が `set`、`frozenset`及びそのサブタイプのオブジェクトで 無い場合は、`PyExc_SystemError` を送出します。

int `PySet_GET_SIZE`( | PyObject *anyset)

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

int `PySet_Contains`( | PyObject *anyset, PyObject *key)

  見つかったら１を、見つからなかったら0を、エラーが発生したときは-1を返します。 Pythonの `__contains__()` メソッドと違って、この関数は非ハッシュsetを 一時frozensetに自動で変換しません。 keyがハッシュ可能で無い場合、`TypeError`を送出します。 anysetが`set`, `frozenset` 及びそのサブタイプのオブジェクトで無い 場合は `PyExc_SystemError` を送出します。

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

int `PySet_Add`( | PyObject *set, PyObject *key)

  `set` のインスタンスに key を追加します。 `frozenset`のインスタンスに使わないで下さい。 成功したら0を、失敗したら-1を返します。 keyがハッシュ可能でないなら、`TypeError`を送出します。 setを大きくする余裕が無い場合は、 `MemoryError`を送出します。 setが`set`とそのサブタイプのインスタンスで無い場合は、`SystemError`を送出します。

int `PySet_Discard`( | PyObject *set, PyObject *key)

  見つかって削除したら1を返します。 見つからなかったら何もせずに0を返します。 エラーが発生したら-1を返します。 keyが無くても`KeyError`を送出しません。 keyがハッシュ不可能であれば`TypeError`を送出します。 Pythonの`discard()`メソッドと違って、この関数は非ハッシュsetsを 一時frozensetに変換しません。 setが`set`とそのサブタイプのインスタンスで無いときは、 `PyExc_SystemError`を送出します。

PyObject* `PySet_Pop`( | PyObject *set)

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

int `PySet_Clear`( | PyObject *set)

  setを空にします。