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) このセット内で、指定された要素と等しいかそれよりも大きい要素のなかで最小のものを返します。
Iterator<E>	descendingIterator() このセットの要素の反復子を降順で返します。
NavigableSet<E>	descendingSet() このセットに含まれる要素の逆順のビューを返します。
E	floor(E e) このセット内で、指定された要素と等しいかそれよりも小さい要素のなかで最大のものを返します。
SortedSet<E>	headSet(E toElement) セットの toElement より小さい要素を持つ部分のビューを返します。
NavigableSet<E>	headSet(E toElement, boolean inclusive) このセットの toElement よりも小さい要素 (inclusive が true の場合はそれよりも小さいかそれと等しい要素) を含む部分のビューを返します。
E	higher(E e) このセット内で、指定された要素よりも確実に大きい要素のなかで最小のものを返します。
Iterator<E>	iterator() このセットの要素の反復子を昇順で返します。
E	lower(E e) このセット内で、指定された要素よりも確実に小さい要素のなかで最大のものを返します。
E	pollFirst() 最初 (下端) の要素を取得して削除します。
E	pollLast() 最後 (上端) の要素を取得して削除します。
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()

このセットの要素の反復子を昇順で返します。

定義:

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

定義:

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

定義:

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

戻り値:

昇順の、このセットの要素の反復子

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 が等しい場合、返されるセットは空になります。ただし、fromExclusive と toExclusive がどちらも 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) と等価です。

定義:

インタフェース SortedSet<E> 内の subSet

パラメータ:

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) と等価です。

定義:

インタフェース SortedSet<E> 内の headSet

パラメータ:

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

戻り値:

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

例外:

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

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

IllegalArgumentException - このセット自体が制限された範囲を持っており、toElement がその範囲の境界の外側にある場合

tailSet

SortedSet<E> tailSet(E fromElement)

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

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

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

定義:

インタフェース SortedSet<E> 内の tailSet

パラメータ:

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

戻り値:

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

例外:

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

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

IllegalArgumentException - このセット自体が制限された範囲を持っており、fromElement がその範囲の境界の外側にある場合