java.util

インタフェース Set<E>

型パラメータ:

E - このセットで保持される要素の型

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

Collection<E>, Iterable<E>

既知のすべてのサブインタフェース:

NavigableSet<E>, SortedSet<E>

既知のすべての実装クラス:

AbstractSet, ConcurrentSkipListSet, CopyOnWriteArraySet, EnumSet, HashSet, JobStateReasons, LinkedHashSet, TreeSet

public interface Set<E>
extends Collection<E>

重複要素のないコレクションです。すなわち、セットは、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(E e) 指定された要素がセット内になかった場合、セットに追加します (オプションの操作)。
boolean	addAll(Collection<? extends E> c) 指定されたコレクションのすべての要素について、その要素がこのセット内にない場合、セットに追加します (オプションの操作)。
void	clear() セットからすべての要素を削除します (オプションの操作)。
boolean	contains(Object o) 指定された要素がセットに含まれている場合に true を返します。
boolean	containsAll(Collection<?> c) 指定されたコレクションのすべての要素がこのセットに含まれている場合に true を返します。
boolean	equals(Object o) 指定されたオブジェクトがセットと同じかどうかを比較します。
int	hashCode() セットのハッシュコード値を返します。
boolean	isEmpty() このセットに要素が 1 つも含まれていない場合に true を返します。
Iterator<E>	iterator() セット内の各要素についてのイテレータを返します。
boolean	remove(Object o) 指定された要素がセット内にあった場合、セットから削除します (オプションの操作)。
boolean	removeAll(Collection<?> c) このセットから、指定されたコレクションに含まれる要素をすべて削除します (オプションの操作)。
boolean	retainAll(Collection<?> c) セット内の要素のうち、指定されたコレクション内にある要素だけを保持します (オプションの操作)。
int	size() セット内の要素数 (そのカーディナリティー) を返します。
Object[]	toArray() セット内のすべての要素が格納されている配列を返します。
<T> T[]	toArray(T[] a) セット内のすべての要素を格納している配列を返します。返される配列の実行時の型は、指定された配列の型になります。

メソッドの詳細

size

int size()

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

定義:

size、インタフェース: Collection<E>

戻り値:

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

isEmpty

boolean isEmpty()

このセットに要素が 1 つも含まれていない場合に true を返します。

定義:

isEmpty、インタフェース: Collection<E>

戻り値:

このセットに要素が 1 つも含まれていない場合は true

contains

boolean contains(Object o)

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

定義:

contains、インタフェース: Collection<E>

パラメータ:

o - このセット内にあるかどうかが判定される要素

戻り値:

指定された要素がこのセットに含まれている場合は true

例外:

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

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

iterator

Iterator<E> iterator()

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

定義:

iterator、インタフェース: Collection<E>

定義:

iterator、インタフェース: Iterable<E>

戻り値:

セットの要素のイテレータ

toArray

Object[] toArray()

セット内のすべての要素が格納されている配列を返します。イテレータによって要素が返される順序をセットが保証する場合、このメソッドは同じ順序で要素を返さなければいけません。

返される配列への参照をセットが維持しないという点で、この配列は安全です。つまり、このメソッドは、セットが配列に連動している場合でも新しい配列を割り当てます。このため、呼び出し側は、返された配列を自由に変更できます。

このメソッドは、配列ベースの API とコレクションベースの API の間の橋渡し役として機能します。

定義:

toArray、インタフェース: Collection<E>

戻り値:

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

toArray

<T> T[] toArray(T[] a)

セット内のすべての要素を格納している配列を返します。返される配列の実行時の型は、指定された配列の型になります。セットが指定された配列に収まる場合は、その中に返されます。そうでない場合は、指定された配列の実行時の型とセットのサイズを持つ新しい配列が割り当てられます。

このセットが指定された配列に収まり、その配列にさらに余裕がある場合 (つまり、配列がセットより多くの要素を持つ場合)、その配列内でセットの終端よりあとの要素は null に設定されます。このセットに null 要素がないことを呼び出し側が知っている場合にだけ、この特性を利用してこのセットの長さを判断できます。

イテレータによって要素が返される順序をセットが保証する場合、このメソッドは同じ順序で要素を返さなければいけません。

toArray() メソッドと同じように、このメソッドは、配列ベースの API とコレクションベースの API の間の橋渡し役として機能します。さらに、このメソッドでは出力配列の実行時の型を正確に制御できるため、環境によっては割り当ての手間を抑えるために使用できます。

x が、文字列だけからなるセットであることがわかっていると仮定します。次のコードを使うと、新しく割り当てられた String の配列内にセットをダンプできます。

     String[] y = x.toArray(new String[0]);

toArray(new Object[0]) は、機能の点で toArray() と同一です。

定義:

toArray、インタフェース: Collection<E>

パラメータ:

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

戻り値:

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

例外:

ArrayStoreException - 指定された配列の実行時の型が、このセット内のすべての要素の実行時の型のスーパータイプでない場合

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

add

boolean add(E e)

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

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

定義:

add、インタフェース: Collection<E>

パラメータ:

e - このセットに追加される要素

戻り値:

このセット内に、指定された要素がなかった場合は true

例外:

UnsupportedOperationException - add オペレーションがこのセットでサポートされない場合

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

NullPointerException - 指定された要素が null であり、このセットが null 要素を許可しない場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、このセットにその要素を追加できない場合

remove

boolean remove(Object o)

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

定義:

remove、インタフェース: Collection<E>

パラメータ:

o - このセットから削除されるオブジェクト (そのオブジェクトが存在する場合)

戻り値:

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

例外:

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

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

UnsupportedOperationException - remove オペレーションがこのセットでサポートされない場合

containsAll

boolean containsAll(Collection<?> c)

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

定義:

containsAll、インタフェース: Collection<E>

パラメータ:

c - このセットに含まれているかどうかがチェックされるコレクション

戻り値:

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

例外:

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

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

関連項目:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

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

定義:

addAll、インタフェース: Collection<E>

パラメータ:

c - このセットに追加される要素を含むコレクション

戻り値:

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

例外:

UnsupportedOperationException - addAll オペレーションがこのセットでサポートされない場合

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

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

IllegalArgumentException - 指定されたコレクションの要素のあるプロパティーが原因で、このセットにその要素を追加できない場合

関連項目:

add(Object)

retainAll

boolean retainAll(Collection<?> c)

セット内の要素のうち、指定されたコレクション内にある要素だけを保持します (オプションの操作)。つまり、セットから、指定されたコレクション内にない要素をすべて削除します。指定されたコレクションもセットである場合、このオペレーションは、その値が 2 つのセットの共通部分になるようにこのセットを効率的に変更します。

定義:

retainAll、インタフェース: Collection<E>

パラメータ:

c - このセットで保持される要素を含むコレクション

戻り値:

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

例外:

UnsupportedOperationException - retainAll オペレーションがこのセットでサポートされない場合

ClassCastException - このセットのある要素のクラスが、指定されたコレクションと互換でない場合 (省略可能)

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

関連項目:

remove(Object)

removeAll

boolean removeAll(Collection<?> c)

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

定義:

removeAll、インタフェース: Collection<E>

パラメータ:

c - このセットから削除される要素を含むコレクション

戻り値:

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

例外:

UnsupportedOperationException - removeAll オペレーションがこのセットでサポートされない場合

ClassCastException - このセットのある要素のクラスが、指定されたコレクションと互換でない場合 (省略可能)

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

関連項目:

remove(Object), contains(Object)

clear

void clear()

セットからすべての要素を削除します (オプションの操作)。この呼び出しが戻ると、セットは空になります。

定義:

clear、インタフェース: Collection<E>

例外:

UnsupportedOperationException - clear メソッドがこのセットでサポートされない場合

equals

boolean equals(Object o)

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

定義:

equals、インタフェース: Collection<E>

オーバーライド:

equals、クラス: Object

パラメータ:

o - このセットと等しいかどうかが比較されるオブジェクト

戻り値:

指定されたオブジェクトがこのセットと等しい場合は true

関連項目:

Object.hashCode()、HashMap

hashCode

int hashCode()

セットのハッシュコード値を返します。セットのハッシュコードは、そのセット内の要素のハッシュコードの合計になるように定義されています。ただし、null 要素のハッシュコードはゼロになるように定義されています。これにより、Object.hashCode() の一般規約によって要求されるように、任意の 2 つのセット s1 と s2 で s1.equals(s2) であれば、s1.hashCode()==s2.hashCode() となることが保証されます。

定義:

hashCode、インタフェース: Collection<E>

オーバーライド:

hashCode、クラス: Object

戻り値:

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

関連項目:

Object.equals(Object), equals(Object)