java.util
インタフェース Set

すべてのスーパーインタフェース:

Collection

既知のサブインタフェースの一覧:

SortedSet

既知の実装クラスの一覧:

AbstractSet, HashSet, LinkedHashSet, TreeSet

public interface Set
extends Collection

重複要素のないコレクションです。すなわち、セットは、e1.equals(e2) である e1 と e2 の要素ペアは持たず、null 要素を最大 1 つしか持ちません。その名前が示すように、このインタフェースは、数学で言う集合の抽象化オブジェクトをモデル化します。

Set インタフェースは、Collection インタフェースから継承した規定だけでなく、すべてのコンストラクタの規約、および add、equals、hashCode の各メソッドの規約に追加の規定を適用します。便宜上、ほかの継承メソッドの宣言もここに含まれます。これらの宣言に付随する仕様は Set インタフェースに合わせて調整済みですが、追加規定は含まれていません。

コンストラクタについての追加規定として、すべてのコンストラクタは、重複要素のないセットを作成しなければなりません (上記を参照)。

注:可変オブジェクトがセット要素として使用される場合は、細心の注意が必要です。オブジェクトがセット内の要素であるうちに equals 比較に影響する方式でその値が変更された場合、セットの動作は保証されません。この禁止事項の特例により、セットがそれ自体を要素として持つことは許可されません。

セットの実装には、格納できる要素に制限があるものもあります。たとえば、null 要素を禁止する実装や、null 要素の型に制限がある実装もあります。不適当な要素を追加しようとすると、通常 NullPointerException または ClassCastException のようなチェックされない例外がスローされます。不適当な要素を照会しようとすると、例外がスローされる場合や、ただ false を返す場合もあります。 前の動作を禁止する実装もあれば、後の動作を禁止する実装もあります。もう少し一般的に言うと、セットへの挿入がされない不適当な要素を処理しようとすると、例外がスローされる場合や、処理が有効になる場合があります。このインタフェースに関するそうした例外は、「任意」の仕様としてマークされます。

このインタフェースは、Java Collections Framework のメンバーです。

導入されたバージョン:

1.2

関連項目:

Collection, List, SortedSet, HashSet, TreeSet, AbstractSet, Collections.singleton(java.lang.Object), Collections.EMPTY_SET

メソッドの概要

boolean	add(Object o) 指定された要素がセット内になかった場合、セットに追加します (任意のオペレーション)。
boolean	addAll(Collection c) 指定されたコレクションのすべての要素について、その要素がこのセット内にない場合、セットに追加します (任意のオペレーション)。
void	clear() セットからすべての要素を削除します (任意のオペレーション)。
boolean	contains(Object o) セットが、指定された要素を保持している場合に true を返します。
boolean	containsAll(Collection c) 指定されたコレクションのすべての要素がセット内にある場合に true を返します。
boolean	equals(Object o) 指定されたオブジェクトがセットと同じかどうかを比較します。
int	hashCode() セットのハッシュコード値を返します。
boolean	isEmpty() セットが要素を 1 つも保持していない場合に true を返します。
Iterator	iterator() セット内の各要素についての反復子を返します。
boolean	remove(Object o) 指定された要素がセット内にあった場合、セットから削除します (任意のオペレーション)。
boolean	removeAll(Collection c) このセットから、指定されたコレクションに含まれる要素をすべて削除します (任意のオペレーション)。
boolean	retainAll(Collection c) セット内の要素のうち、指定されたコレクション内にある要素だけを保持します (任意のオペレーション)。
int	size() セット内の要素数 (そのカーディナリティー) を返します。
Object[]	toArray() セット内のすべての要素が格納されている配列を返します。
Object[]	toArray(Object[] a) セット内のすべての要素を格納している配列を返します。

メソッドの詳細

size

int size()

セット内の要素数 (そのカーディナリティー) を返します。このセットに Integer.MAX_VALUE より多くの要素がある場合は、Integer.MAX_VALUE を返します。

定義:

インタフェース Collection 内の size

戻り値:

セット内の要素数 (そのカーディナリティー)

isEmpty

boolean isEmpty()

セットが要素を 1 つも保持していない場合に true を返します。

定義:

インタフェース Collection 内の isEmpty

戻り値:

セットが要素を 1 つも保持していない場合は true

contains

boolean contains(Object o)

セットが、指定された要素を保持している場合に true を返します。つまり、このセットに、(o==null ? e==null : o.equals(e)) となる要素 e が含まれている場合にだけ true を返します。

定義:

インタフェース Collection 内の contains

パラメータ:

o - セットにあるかどうかを調べる要素

戻り値:

セットが、指定された要素を保持している場合は true

例外:

ClassCastException - 指定された要素の型が、このセットと互換性がない場合 (省略可能)

NullPointerException - 指定された要素が null で、このセットが null 要素をサポートしない場合 (省略可能)

iterator

Iterator iterator()

セット内の各要素についての反復子を返します。セットが順序を保証する特定クラスのインスタンスでないかぎり、要素は特定の順序では返されません。

定義:

インタフェース Collection 内の iterator

戻り値:

セットの要素の反復子

toArray

Object[] toArray()

セット内のすべての要素が格納されている配列を返します。Collection.toArray メソッドの一般規約に従います。

定義:

インタフェース Collection 内の toArray

戻り値:

セット内のすべての要素を保持している配列

toArray

Object[] toArray(Object[] a)

セット内のすべての要素を格納している配列を返します。 返される配列の実行時の型は、指定された配列の型になります。Collection.toArray(Object[]) メソッドの一般規約に従います。

定義:

インタフェース Collection 内の toArray

パラメータ:

a - このセットの要素の格納先の配列。配列のサイズが十分でない場合は、同じ実行時の型で新しい配列が格納用として割り当てられる

戻り値:

セットの要素が格納されている配列

例外:

ArrayStoreException - a の実行時の型が、このセット内の各要素の実行時の型のスーパータイプでない場合

NullPointerException - 指定された配列が null である場合

add

boolean add(Object o)

指定された要素がセット内になかった場合、セットに追加します (任意のオペレーション)。つまり、このセットに、(o==null ? e==null : o.equals(e)) となる要素 e が含まれていない場合、このセットに指定された要素 o を追加します。このセット内にすでに指定された要素がある場合、呼び出しはこのセットを変更せずに false を返します。このため、コンストラクタについての制約との組み合わせにより、セットが重複要素を持たないことを保証します。

この規定は、セットがすべての要素を受け付けなければならないことを意味するわけではありません。つまり、セットでは、null を含む任意の要素の追加を拒否したり、例外をスローすることを任意に指定できます (Collection.add の仕様を参照)。セットの各実装では、セットが持つことのできる要素についての制約を明記するようにしてください。

定義:

インタフェース Collection 内の add

パラメータ:

o - セットに追加される要素

戻り値:

このセットが指定された要素を保持していなかった場合は true

例外:

UnsupportedOperationException - このセットが add メソッドをサポートしていない場合

ClassCastException - 指定された要素のクラスのために、セットに要素を追加できない場合

NullPointerException - 指定された要素が null で、このセットが null 要素をサポートしない場合

IllegalArgumentException - 指定された要素の一部の特性のために、このセットに要素を追加できない場合

remove

boolean remove(Object o)

指定された要素がセット内にあった場合、セットから削除します (任意のオペレーション)。つまり、セット内に、(o==null ? e==null : o.equals(e)) のような要素 e が含まれている場合は、その要素を削除します。指定された要素がセットに含まれていた場合、つまり、呼び出しの結果としてセットが変更された場合に true を返します。呼び出しが復帰したあとは、セットは指定された要素を持っていません。

定義:

インタフェース Collection 内の remove

パラメータ:

o - セットにあれば削除されるオブジェクト

戻り値:

指定された要素がセット内にあった場合は true

例外:

ClassCastException - 指定された要素の型が、このセットと互換性がない場合 (省略可能)

NullPointerException - 指定された要素が null で、このセットが null 要素をサポートしない場合 (省略可能)

UnsupportedOperationException - このセットが remove メソッドをサポートしていない場合

containsAll

boolean containsAll(Collection c)

指定されたコレクションのすべての要素がセット内にある場合に true を返します。指定されたコレクションもセットである場合、指定されたセットがこのセットの「サブセット」であれば、このメソッドは true を返します。

定義:

インタフェース Collection 内の containsAll

パラメータ:

c - このセットにあるかどうかを調べるコレクション

戻り値:

指定されたコレクションのすべての要素がこのセットに含まれている場合は true

例外:

ClassCastException - 指定されたコレクションの 1 つ以上の要素の型が、このセットと互換性がない場合 (省略可能)

NullPointerException - 指定されたコレクションに 1 つ以上の null 要素が含まれていて、このセットが null 要素をサポートしない場合 (省略可能)

NullPointerException - 指定されたコレクションが null である場合

関連項目:

contains(Object)

addAll

boolean addAll(Collection c)

指定されたコレクションのすべての要素について、その要素がこのセット内にない場合、セットに追加します (任意のオペレーション)。指定されたコレクションもセットである場合、addAll オペレーションは効率的にセットを変更して、その値が 2 つのセットの「和集合」になるようにします。オペレーションの進行中に、指定されたコレクションが変更された場合の、このオペレーションの動作は指定されていません。

定義:

インタフェース Collection 内の addAll

パラメータ:

c - 要素がセットに追加されるコレクション

戻り値:

この呼び出しの結果、このセットが変更された場合は true

例外:

UnsupportedOperationException - このセットが addAll メソッドをサポートしていない場合

ClassCastException - 指定されたコレクションの要素のクラスが原因で、その要素をこのセットに追加できない場合

NullPointerException - 指定されたコレクションに 1 つ以上の null 要素が含まれており、このセットが null 要素をサポートしない場合 (省略可能)。または指定されたコレクションが null の場合

IllegalArgumentException - 指定されたコレクションの要素の特性が原因で、その要素をこのセットに追加できない場合

関連項目:

add(Object)

retainAll

boolean retainAll(Collection c)

セット内の要素のうち、指定されたコレクション内にある要素だけを保持します (任意のオペレーション)。つまり、セットから、指定されたコレクション内にない要素をすべて削除します。指定されたコレクションもセットである場合、このオペレーションの結果、セットの値は 2 つのセットの「共通部分」になります。

定義:

インタフェース Collection 内の retainAll

パラメータ:

c - セットが保持する要素を定義するコレクション

戻り値:

呼び出しの結果、このコレクションが変更された場合は true

例外:

UnsupportedOperationException - コレクションが retainAll メソッドをサポートしていない場合

ClassCastException - このセットの 1 つ以上の要素の型が、指定されたコレクションと互換性がない場合 (省略可能)

NullPointerException - このセットに null 要素が含まれていて、指定されたコレクションが null 要素をサポートしない場合 (省略可能)

NullPointerException - 指定されたコレクションが null である場合

関連項目:

remove(Object)

removeAll

boolean removeAll(Collection c)

このセットから、指定されたコレクションに含まれる要素をすべて削除します (任意のオペレーション)。指定されたコレクションもセットである場合、このオペレーションは、値が 2 つのセットの「非対称集合差分」になるようにセットを効率的に変更します。

定義:

インタフェース Collection 内の removeAll

パラメータ:

c - どの要素がこのセットから削除されるかを定義するコレクション

戻り値:

この呼び出しの結果、このセットが変更された場合は true

例外:

UnsupportedOperationException - このコレクションが removeAll メソッドをサポートしない場合

ClassCastException - このセットの 1 つ以上の要素の型が、指定されたコレクションと互換性がない場合 (省略可能)

NullPointerException - このセットに null 要素が含まれていて、指定されたコレクションが null 要素をサポートしない場合 (省略可能)

NullPointerException - 指定されたコレクションが null である場合

関連項目:

remove(Object)

clear

void clear()

セットからすべての要素を削除します (任意のオペレーション)。このセットは、この呼び出しが返されると、呼び出しが例外をスローしないかぎり、空になります。

定義:

インタフェース Collection 内の clear

例外:

UnsupportedOperationException - このセットが clear メソッドをサポートしていない場合

equals

boolean equals(Object o)

指定されたオブジェクトがセットと同じかどうかを比較します。指定されたオブジェクトもセットで、2 つのセットが同じサイズを持ち、指定されたセットのすべてのメンバーがこのセットに含まれる場合、または、このセットのすべてのメンバーが指定されたセットに含まれる場合は、true を返します。この定義により、equals メソッドがセットインタフェースのさまざまな実装で適切に動作することが保証されます。

定義:

インタフェース Collection 内の equals

オーバーライド:

クラス Object 内の equals

パラメータ:

o - このセットと等しいかどうかが比較される Object

戻り値:

指定された Object がセットと同じ場合は true

関連項目:

Object.hashCode(), Hashtable

hashCode

int hashCode()

セットのハッシュコード値を返します。セットのハッシュコードは、セット内の各要素のハッシュコードの合計です。ただし、null 要素のハッシュコードはゼロになります。これにより、Object.hashCode メソッドの一般規約で要求されるとおりに、任意の 2 つのセット s1 と s2 について、s1.equals(s2) の場合 s1.hashCode()==s2.hashCode() になります。

定義:

インタフェース Collection 内の hashCode

オーバーライド:

クラス Object 内の hashCode

戻り値:

セットのハッシュコード値

関連項目:

Object.hashCode(), Object.equals(Object), equals(Object)