java.util
インタフェース Set<E>

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

Collection<E>, Iterable<E>

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

SortedSet<E>

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

AbstractSet, 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 o) 指定された要素がセット内になかった場合、セットに追加します (任意のオペレーション)。
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 を返します。

定義:

インタフェース Collection<E> 内の size

戻り値:

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

isEmpty

boolean isEmpty()

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

定義:

インタフェース Collection<E> 内の isEmpty

戻り値:

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

contains

boolean contains(Object o)

指定された要素がセット内にある場合に true を返します。つまり、セット内に、(o==null ? e==null : o.equals(e)) に該当する要素 e がある場合にだけ true を返します。

定義:

インタフェース Collection<E> 内の contains

パラメータ:

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

戻り値:

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

例外:

ClassCastException - 指定された要素の型が、このセットと互換でない場合 (任意のオプション)

NullPointerException - 指定された要素が null で、このセットが null 要素をサポートしない場合 (任意のオプション)

iterator

Iterator<E> iterator()

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

定義:

インタフェース Collection<E> 内の iterator

定義:

インタフェース Iterable<E> 内の iterator

戻り値:

セットの要素の反復子

toArray

Object[] toArray()

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

定義:

インタフェース Collection<E> 内の toArray

戻り値:

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

toArray

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

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

定義:

インタフェース Collection<E> 内の toArray

パラメータ:

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

戻り値:

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

例外:

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

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

add

boolean add(E o)

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

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

定義:

インタフェース Collection<E> 内の 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<E> 内の remove

パラメータ:

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

戻り値:

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

例外:

ClassCastException - 指定された要素の型が、このセットと互換でない場合 (任意のオプション)

NullPointerException - 指定された要素が null で、このセットが null 要素をサポートしない場合 (任意のオプション)

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

containsAll

boolean containsAll(Collection<?> c)

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

定義:

インタフェース Collection<E> 内の containsAll

パラメータ:

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

戻り値:

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

例外:

ClassCastException - 指定されたコレクションの 1 つまたは複数の要素の型が、このセットと互換でない場合 (任意のオプション)

NullPointerException - 指定されたコレクションが 1 つまたは複数のnull 要素を含み、このセットが null 要素をサポートしない場合 (任意のオプション)

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

関連項目:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

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

定義:

インタフェース Collection<E> 内の addAll

パラメータ:

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

戻り値:

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

例外:

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

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

NullPointerException - 指定されたコレクション内に 1 つまたは複数の null 要素が含まれず、このセットが null 要素をサポートしない場合。または指定されたコレクションが null の場合

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

関連項目:

add(Object)

retainAll

boolean retainAll(Collection<?> c)

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

定義:

インタフェース Collection<E> 内の retainAll

パラメータ:

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

戻り値:

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

例外:

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

ClassCastException - このコレクションの 1 つまたは複数の要素の型が、指定されたセットと互換でない場合 (任意のオプション)

NullPointerException - このセットが null 要素を含み、指定されたコレクションが null 要素をサポートしない場合 (任意のオプション)

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

関連項目:

remove(Object)

removeAll

boolean removeAll(Collection<?> c)

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

定義:

インタフェース Collection<E> 内の removeAll

パラメータ:

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

戻り値:

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

例外:

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

ClassCastException - このコレクションの 1 つまたは複数の要素の型が、指定されたセットと互換でない場合 (任意のオプション)

NullPointerException - このセットが null 要素を含み、指定されたコレクションが null 要素をサポートしない場合 (任意のオプション)

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

関連項目:

remove(Object)

clear

void clear()

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

定義:

インタフェース Collection<E> 内の clear

例外:

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

equals

boolean equals(Object o)

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

定義:

インタフェース Collection<E> 内の 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<E> 内の hashCode

オーバーライド:

クラス Object 内の hashCode

戻り値:

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

関連項目:

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