java.util

インタフェース NavigableSet<E>

型パラメータ:

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

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

Collection<E>, Iterable<E>, Set<E>, SortedSet<E>

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

ConcurrentSkipListSet, TreeSet

public interface NavigableSet<E>
extends SortedSet<E>

指定の検索ターゲットにもっとも近い一致内容を報告するナビゲーションメソッドで拡張された SortedSet です。lower、floor、ceiling、higher メソッドはそれぞれ、指定された要素よりも小さい要素、小さいか等しい要素、大きいか等しい要素、大きい要素を返します。ただし、そのような要素が存在しない場合は null を返します。NavigableSet へのアクセスやトラバースは、昇順、降順のいずれかで行えます。descendingSet メソッドから返されるこのセットのビューでは、関係や方向に関するメソッドがすべて反転されたかのように感じられます。オペレーションやビューのパフォーマンスは通常、降順よりも昇順のほうが高速になります。このインタフェースにはさらに、pollFirst と pollLast メソッドも定義されています。これらのメソッドはそれぞれ、最下位の要素、最上位の要素が存在する場合はそれを返して削除し、それ以外の場合はnull を返します。subSet、headSet、および tailSet メソッドは、下限と上限を含めるかどうかを記述する追加の引数を受け取るという点で、SortedSet の類似の名前を持つメソッドとは異なります。どの NavigableSet のサブセットでも NavigableSet インタフェースを実装する必要があります。

null 要素を許可する実装では、ナビゲーションメソッドの戻り値があいまいになる可能性があります。ただし、その場合でも、contains(null) をチェックすることで、その結果のあいまいさを明確にできます。そのような問題を回避するため、このインタフェースの実装では、null 要素の挿入を許可しないようにすることをお勧めします。(Comparable 要素から成るソートセットは本来、null を許可しません。)

subSet(E, E)、headSet(E)、および tailSet(E) メソッドが SortedSet を返す仕様になっているのは、既存の SortedSet 実装を互換性を維持しながら改良して NavigableSet を実装できるようにするためです。ただし、このインタフェースの拡張や実装では、これらのメソッドをオーバーライドして NavigableSet が返されるようにすることをお勧めします。

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

導入されたバージョン:

1.6

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
E	ceiling(E e) このセット内で、指定された要素と等しいかそれよりも大きい要素の中で最小のものを返します。そのような要素が存在しない場合は null を返します。
Iterator<E>	descendingIterator() このセットの要素のイテレータを降順で返します。
NavigableSet<E>	descendingSet() このセットに含まれる要素の逆順のビューを返します。
E	floor(E e) このセット内で、指定された要素と等しいかそれよりも小さい要素の中で最大のものを返します。そのような要素が存在しない場合は null を返します。
SortedSet<E>	headSet(E toElement) このセットの toElement よりも確実に小さい要素を持つ部分のビューを返します。
NavigableSet<E>	headSet(E toElement, boolean inclusive) このセットの toElement よりも小さい要素 (inclusive が true の場合はそれよりも小さいかそれと等しい要素) を含む部分のビューを返します。
E	higher(E e) このセット内で、指定された要素よりも確実に大きい要素の中で最小のものを返します。そのような要素が存在しない場合は null を返します。
Iterator<E>	iterator() このセットの要素のイテレータを昇順で返します。
E	lower(E e) このセット内で、指定された要素よりも確実に小さい要素の中で最大のものを返します。そのような要素が存在しない場合は null を返します。
E	pollFirst() 最初 (下端) の要素を取得して削除します。このセットが空の場合は null を返します。
E	pollLast() 最後 (上端) の要素を取得して削除します。このセットが空の場合は null を返します。
NavigableSet<E>	subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) このセットの fromElement - toElement の要素範囲を持つ部分のビューを返します。
SortedSet<E>	subSet(E fromElement, E toElement) このセットの fromElement (これを含む) - toElement (これを含まない) の要素範囲を持つ部分のビューを返します。
SortedSet<E>	tailSet(E fromElement) このセットの fromElement に等しいかそれよりも大きい要素を持つ部分のビューを返します。
NavigableSet<E>	tailSet(E fromElement, boolean inclusive) このセットの fromElement よりも大きい要素 (inclusive が true の場合はそれよりも大きいかそれと等しい要素) を含む部分のビューを返します。

インタフェース java.util.SortedSet から継承されたメソッド

comparator, first, last

インタフェース java.util.Set から継承されたメソッド

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, size, toArray, toArray

メソッドの詳細

lower

E lower(E e)

このセット内で、指定された要素よりも確実に小さい要素の中で最大のものを返します。そのような要素が存在しない場合は null を返します。

パラメータ:

e - 照合する値

戻り値:

e よりも小さい要素の中で最大のもの。そのような要素が存在しない場合は null

例外:

ClassCastException - 指定された要素を、セット内に現在存在している要素と比較できない場合

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

floor

E floor(E e)

このセット内で、指定された要素と等しいかそれよりも小さい要素の中で最大のものを返します。そのような要素が存在しない場合は null を返します。

パラメータ:

e - 照合する値

戻り値:

e と等しいか、それよりも小さい要素の中で最大のもの。そのような要素が存在しない場合は null

例外:

ClassCastException - 指定された要素を、セット内に現在存在している要素と比較できない場合

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

ceiling

E ceiling(E e)

このセット内で、指定された要素と等しいかそれよりも大きい要素の中で最小のものを返します。そのような要素が存在しない場合は null を返します。

パラメータ:

e - 照合する値

戻り値:

e と等しいか、それよりも大きい要素の中で最小のもの。そのような要素が存在しない場合は null

例外:

ClassCastException - 指定された要素を、セット内に現在存在している要素と比較できない場合

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

higher

E higher(E e)

このセット内で、指定された要素よりも確実に大きい要素の中で最小のものを返します。そのような要素が存在しない場合は null を返します。

パラメータ:

e - 照合する値

戻り値:

e よりも大きい要素の中で最小のもの。そのような要素が存在しない場合は null

例外:

ClassCastException - 指定された要素を、セット内に現在存在している要素と比較できない場合

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

pollFirst

E pollFirst()

最初 (下端) の要素を取得して削除します。このセットが空の場合は null を返します。

戻り値:

最初の要素。このセットが空の場合は null

pollLast

E pollLast()

最後 (上端) の要素を取得して削除します。このセットが空の場合は null を返します。

戻り値:

最後の要素。このセットが空の場合は null

iterator

Iterator<E> iterator()

このセットの要素のイテレータを昇順で返します。

定義:

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

定義:

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

定義:

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

戻り値:

昇順の、このセットの要素のイテレータ

descendingSet

NavigableSet<E> descendingSet()

このセットに含まれる要素の逆順のビューを返します。降順セットはこのセットに連動しており、このセットでの変更は降順セットに反映され、その逆の場合も同様です。いずれかのセットの反復処理中にいずれかのセットが変更された場合、反復処理の結果は定義されていません (イテレータ自身の remove オペレーションを除く)。

返されるセットの順序付けは、Collections.reverseOrder(comparator()) と同等になります。式 s.descendingSet().descendingSet() から返される s のビューは基本的に s と同等になります。

戻り値:

このセットの逆順のビュー

descendingIterator

Iterator<E> descendingIterator()

このセットの要素のイテレータを降順で返します。実質的に descendingSet().iterator() と同等です。

戻り値:

降順の、このセットの要素のイテレータ

subSet

NavigableSet<E> subSet(E fromElement,
                     boolean fromInclusive,
                     E toElement,
                     boolean toInclusive)

このセットの fromElement - toElement の要素範囲を持つ部分のビューを返します。fromElement と toElement が等しい場合、返されるセットは、fromInclusive と toInclusive の両方が true でないかぎり、空になります。返されるセットはこのセットに連動しており、返されるセットでの変更はこのセットに反映され、その逆の場合も同様です。返されるセットは、このセットがサポートする任意のセットオペレーションをすべてサポートします。

返されるセットは、その範囲外の要素が挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:

fromElement - 返されるセットの下端点

fromInclusive - 返されるビューに下端点が含まれる場合は true

toElement - 返されるセットの上端点

toInclusive - 返されるビューに上端点が含まれる場合は true

戻り値:

このセットの fromElement (これを含む) - toElement (これを含まない) の要素範囲を持つ部分のビュー

例外:

ClassCastException - このセットのコンパレータを使用して (このセットがコンパレータを持たない場合は自然順序付けを使用して)、fromElement と toElement の相互比較を行えない場合。実装は、セット内に現在存在している要素と fromElement または toElement とを比較できない場合にこの例外をスローできる。ただし、必須ではない。

NullPointerException - fromElement または toElement が null であり、このセットが null 要素を許可しない場合

IllegalArgumentException - fromElement が toElement よりも大きい場合、またはこのセット自体が制限された範囲を持っており、fromElement または toElement がその範囲から外れている場合

headSet

NavigableSet<E> headSet(E toElement,
                      boolean inclusive)

このセットの toElement よりも小さい要素 (inclusive が true の場合はそれよりも小さいかそれと等しい要素) を含む部分のビューを返します。返されるセットはこのセットに連動しており、返されるセットでの変更はこのセットに反映され、その逆の場合も同様です。返されるセットは、このセットがサポートする任意のセットオペレーションをすべてサポートします。

返されるセットは、その範囲外の要素が挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:

toElement - 返されるセットの上端点

inclusive - 返されるビューに上端点が含まれる場合は true

戻り値:

このセットの toElement よりも小さい要素 (inclusive が true の場合はそれよりも小さいかそれと等しい要素) を含む部分のビュー

例外:

ClassCastException - toElement がこのセットのコンパレータと互換性がない場合 (または、そのセットがコンパレータを持たない場合、toElement が Comparable を実装していない場合)。実装は、セット内に現在存在している要素と toElement とを比較できない場合にこの例外をスローできる。ただし、必須ではない。

NullPointerException - toElement が null であり、このセットが null 要素を許可しない場合

IllegalArgumentException - このセット自体が制限された範囲を持っており、toElement がその範囲から外れている場合

tailSet

NavigableSet<E> tailSet(E fromElement,
                      boolean inclusive)

このセットの fromElement よりも大きい要素 (inclusive が true の場合はそれよりも大きいかそれと等しい要素) を含む部分のビューを返します。返されるセットはこのセットに連動しており、返されるセットでの変更はこのセットに反映され、その逆の場合も同様です。返されるセットは、このセットがサポートする任意のセットオペレーションをすべてサポートします。

返されるセットは、その範囲外の要素が挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:

fromElement - 返されるセットの下端点

inclusive - 返されるビューに下端点が含まれる場合は true

戻り値:

このセットの fromElement に等しいかそれよりも大きい要素を持つ部分のビュー

例外:

ClassCastException - fromElement がこのセットのコンパレータと互換性がない場合 (または、そのセットがコンパレータを持たない場合、fromElement が Comparable を実装していない場合)。実装は、セット内に現在存在している要素と fromElement とを比較できない場合にこの例外をスローできる。ただし、必須ではない。

NullPointerException - fromElement が null であり、このセットが null 要素を許可しない場合

IllegalArgumentException - このセット自体が制限された範囲を持っており、fromElement がその範囲から外れている場合

subSet

SortedSet<E> subSet(E fromElement,
                  E toElement)

このセットの fromElement (これを含む) - toElement (これを含まない) の要素範囲を持つ部分のビューを返します。fromElement と toElement が等しい場合は、空のセットが返されます。返されるセットはこのセットに連動しており、返されるセットでの変更はこのセットに反映され、その逆の場合も同様です。返されるセットは、このセットがサポートする任意のセットオペレーションをすべてサポートします。

返されるセットは、その範囲外の要素が挿入されようとすると、IllegalArgumentException をスローします。

subSet(fromElement, true, toElement, false) と同等です。

定義:

subSet、インタフェース: SortedSet<E>

パラメータ:

fromElement - 返されるセットの下端点 (これを含む)

toElement - 返されるセットの上端点 (これを含まない)

戻り値:

このセットの fromElement (これを含む) - toElement (これを含まない) の要素範囲を持つ部分のビュー

例外:

ClassCastException - このセットのコンパレータを使用して (このセットがコンパレータを持たない場合は自然順序付けを使用して)、fromElement と toElement の相互比較を行えない場合。実装は、セット内に現在存在している要素と fromElement または toElement とを比較できない場合にこの例外をスローできる。ただし、必須ではない。

NullPointerException - fromElement または toElement が null であり、このセットが null 要素を許可しない場合

IllegalArgumentException - fromElement が toElement よりも大きい場合、またはこのセット自体が制限された範囲を持っており、fromElement または toElement がその範囲から外れている場合

headSet

SortedSet<E> headSet(E toElement)

このセットの toElement よりも確実に小さい要素を持つ部分のビューを返します。返されるセットはこのセットに連動しており、返されるセットでの変更はこのセットに反映され、その逆の場合も同様です。返されるセットは、このセットがサポートする任意のセットオペレーションをすべてサポートします。

返されるセットは、その範囲外の要素が挿入されようとすると、IllegalArgumentException をスローします。

headSet(toElement, false) と同等です。

定義:

headSet、インタフェース: SortedSet<E>

パラメータ:

toElement - 返されるセットの上端点 (これを含まない)

戻り値:

このセットの toElement よりも確実に小さい要素を持つ部分のビュー

例外:

ClassCastException - toElement がこのセットのコンパレータと互換性がない場合 (または、そのセットがコンパレータを持たない場合、toElement が Comparable を実装していない場合)。実装は、セット内に現在存在している要素と toElement とを比較できない場合にこの例外をスローできる。ただし、必須ではない。

NullPointerException - toElement が null であり、このセットが null 要素を許可しない場合

IllegalArgumentException - このセット自体が制限された範囲を持っており、toElement がその範囲から外れている場合

tailSet

SortedSet<E> tailSet(E fromElement)

このセットの fromElement に等しいかそれよりも大きい要素を持つ部分のビューを返します。返されるセットはこのセットに連動しており、返されるセットでの変更はこのセットに反映され、その逆の場合も同様です。返されるセットは、このセットがサポートする任意のセットオペレーションをすべてサポートします。

返されるセットは、その範囲外の要素が挿入されようとすると、IllegalArgumentException をスローします。

tailSet(fromElement, true) と同等です。

定義:

tailSet、インタフェース: SortedSet<E>

パラメータ:

fromElement - 返されるセットの下端点 (これを含む)

戻り値:

このセットの fromElement に等しいかそれより大きい要素を持つ部分のビュー

例外:

ClassCastException - fromElement がこのセットのコンパレータと互換性がない場合 (または、そのセットがコンパレータを持たない場合、fromElement が Comparable を実装していない場合)。実装は、セット内に現在存在している要素と fromElement とを比較できない場合にこの例外をスローできる。ただし、必須ではない。

NullPointerException - fromElement が null であり、このセットが null 要素を許可しない場合

IllegalArgumentException - このセット自体が制限された範囲を持っており、fromElement がその範囲から外れている場合