NavigableMap (Java Platform SE 6)

指定されたターゲットにもっとも近い要素を返すナビゲーションメソッドで拡張された SortedMap です。lowerEntry、floorEntry、ceilingEntry、higherEntry メソッドはそれぞれ、指定されたキーよりも小さいキー、小さいか等しいキー、大きいか等しいキー、大きいキーに関連付けられた Map.Entry オブジェクトを返します。ただし、そのようなキーが存在しない場合は null を返します。同様に、lowerKey、floorKey、ceilingKey、および higherKey メソッドは、関連するキーのみを返します。これらのすべてのメソッドの設計目的は、エントリをトラバースすることではなく、エントリを特定することです。

NavigableMap へのアクセスやトラバースは、キーの昇順、降順のいずれかで行えます。descendingMap メソッドから返されるこのマップのビューでは、関係や方向に関するメソッドがすべて反転されたかのように感じられます。オペレーションやビューのパフォーマンスは通常、降順よりも昇順のほうが高速になります。subMap、headMap、および tailMap メソッドは、下限と上限を含めるかどうかを記述する追加の引数を受け取るという点で、SortedMap の類似の名前を持つメソッドとは異なります。任意の NavigableMap のサブマップは、NavigableMap インタフェースを実装します。

このインタフェースにはさらに、firstEntry、pollFirstEntry、lastEntry、および pollLastEntry メソッドも定義されています。これらのメソッドは、最小、最大のマッピングが存在する場合はそのリターンまたは削除、あるいはその両方を行い、それ以外の場合は null を返します。

エントリを返すメソッドの実装は、マッピングの生成時点でのスナップショットを表す Map.Entry ペアを返すことを期待されるため、通常は省略可能な Entry.setValue メソッドをサポートしません。ただし、関連するマップ内のマッピングは put メソッドを使って変更できることに注意してください。

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

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

導入されたバージョン:: 1.6

入れ子のクラスの概要

インタフェース java.util.Map から継承された入れ子のクラス/インタフェース
`Map.Entry<K,V>`

メソッドの概要
`Map.Entry<K,V>`	`ceilingEntry(K key)` 指定されたキーと等しいかそれよりも大きいキーのなかで最小のものに関連付けられた、キーと値のマッピングを返します。
`K`	`ceilingKey(K key)` 指定されたキーと等しいかそれよりも大きいキーのなかで最小のものを返します。
`NavigableSet<K>`	`descendingKeySet()` このマップに含まれるキーの逆順の `NavigableSet` ビューを返します。
`NavigableMap<K,V>`	`descendingMap()` マップ内に保持されているマッピングの逆順のビューを返します。
`Map.Entry<K,V>`	`firstEntry()` このマップ内で最小のキーに関連付けられたキーと値のマッピングを返します。
`Map.Entry<K,V>`	`floorEntry(K key)` 指定されたキーと等しいかそれよりも小さいキーのなかで最大のものに関連付けられた、キーと値のマッピングを返します。
`K`	`floorKey(K key)` 指定されたキーと等しいかそれよりも小さいキーのなかで最大のものを返します。
`SortedMap<K,V>`	`headMap(K toKey)` マップの `toKey` より小さいキーを持つ部分のビューを返します。
`NavigableMap<K,V>`	`headMap(K toKey, boolean inclusive)` `toKey` よりも小さいキー (`inclusive` が true の場合はそれよりも小さいかそれと等しいキー) を含むこのマップの部分のビューを返します。
`Map.Entry<K,V>`	`higherEntry(K key)` 指定されたキーよりも確実に大きいキーのなかで最小のものに関連付けられた、キーと値のマッピングを返します。
`K`	`higherKey(K key)` 指定されたキーよりも確実に大きいキーのなかで最小のものを返します。
`Map.Entry<K,V>`	`lastEntry()` このマップ内で最大のキーに関連付けられたキーと値のマッピングを返します。
`Map.Entry<K,V>`	`lowerEntry(K key)` 指定されたキーよりも確実に小さいキーのなかで最大のものに関連付けられた、キーと値のマッピングを返します。
`K`	`lowerKey(K key)` 指定されたキーよりも確実に小さいキーのなかで最大のものを返します。
`NavigableSet<K>`	`navigableKeySet()` このマップに含まれるキーの `NavigableSet` ビューを返します。
`Map.Entry<K,V>`	`pollFirstEntry()` このマップ内で最小のキーに関連付けられたキーと値のマッピングを削除して返します。
`Map.Entry<K,V>`	`pollLastEntry()` このマップ内で最大のキーに関連付けられたキーと値のマッピングを削除して返します。
`NavigableMap<K,V>`	`subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)` マップの `fromKey` 〜 `toKey` のキー範囲を持つ部分のビューを返します。
`SortedMap<K,V>`	`subMap(K fromKey, K toKey)` マップの `fromKey` (これを含む) 〜 `toKey` (これを含まない) のキー範囲を持つ部分のビューを返します。
`SortedMap<K,V>`	`tailMap(K fromKey)` マップの `fromKey` 以上のキーを持つ部分のビューを返します。
`NavigableMap<K,V>`	`tailMap(K fromKey, boolean inclusive)` `fromKey` よりも大きいキー (`inclusive` が true の場合はそれよりも大きいかそれと等しいキー) を含むこのマップの部分のビューを返します。

インタフェース java.util.SortedMap から継承されたメソッド
`comparator, entrySet, firstKey, keySet, lastKey, values`

インタフェース java.util.Map から継承されたメソッド
`clear, containsKey, containsValue, equals, get, hashCode, isEmpty, put, putAll, remove, size`

メソッドの詳細

lowerEntry

Map.Entry<K,V> lowerEntry(K key)

指定されたキーよりも確実に小さいキーのなかで最大のものに関連付けられた、キーと値のマッピングを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key よりも小さいキーのなかで最大のものを持つエントリ。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

lowerKey

K lowerKey(K key)

指定されたキーよりも確実に小さいキーのなかで最大のものを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key よりも小さいキーのなかで最大のもの。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

floorEntry

Map.Entry<K,V> floorEntry(K key)

指定されたキーと等しいかそれよりも小さいキーのなかで最大のものに関連付けられた、キーと値のマッピングを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key と等しいかそれよりも小さいキーのなかで最大のものを持つエントリ。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

floorKey

K floorKey(K key)

指定されたキーと等しいかそれよりも小さいキーのなかで最大のものを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key と等しいかそれよりも小さいキーのなかで最大のもの。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

ceilingEntry

Map.Entry<K,V> ceilingEntry(K key)

指定されたキーと等しいかそれよりも大きいキーのなかで最小のものに関連付けられた、キーと値のマッピングを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key と等しいかそれよりも大きいキーのなかで最小のものを持つエントリ。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

ceilingKey

K ceilingKey(K key)

指定されたキーと等しいかそれよりも大きいキーのなかで最小のものを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key と等しいかそれよりも大きいキーのなかで最小のもの。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

higherEntry

Map.Entry<K,V> higherEntry(K key)

指定されたキーよりも確実に大きいキーのなかで最小のものに関連付けられた、キーと値のマッピングを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key よりも大きいキーのなかで最小のものを持つエントリ。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

higherKey

K higherKey(K key)

指定されたキーよりも確実に大きいキーのなかで最小のものを返します。そのようなキーが存在しない場合は null を返します。

パラメータ:: key - キー
戻り値:: key よりも大きいキーのなかで最小のもの。そのようなキーが存在しない場合は null
例外:: ClassCastException - 指定されたキーがマップ内に現在あるキーと比較できない場合; NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合

firstEntry

Map.Entry<K,V> firstEntry()

このマップ内で最小のキーに関連付けられたキーと値のマッピングを返します。このマップが空の場合は null を返します。

戻り値:: 最小のキーを持つエントリ。このマップが空の場合は null

lastEntry

Map.Entry<K,V> lastEntry()

このマップ内で最大のキーに関連付けられたキーと値のマッピングを返します。このマップが空の場合は null を返します。

戻り値:: 最大のキーを持つエントリ。このマップが空の場合は null

pollFirstEntry

Map.Entry<K,V> pollFirstEntry()

このマップ内で最小のキーに関連付けられたキーと値のマッピングを削除して返します。このマップが空の場合は null を返します。

戻り値:: このマップの削除された最初のエントリ。このマップが空の場合は null

pollLastEntry

Map.Entry<K,V> pollLastEntry()

このマップ内で最大のキーに関連付けられたキーと値のマッピングを削除して返します。このマップが空の場合は null を返します。

戻り値:: このマップの削除された最後のエントリ。このマップが空の場合は null

descendingMap

NavigableMap<K,V> descendingMap()

マップ内に保持されているマッピングの逆順のビューを返します。降順マップはこのマップに連動しており、このマップでの変更は降順マップに反映され、その逆の場合も同様です。いずれかのマップのコレクションビューの反復処理中にいずれかのマップが変更された場合、反復処理の結果は定義されません (反復子自身の remove オペレーションを除く)。

返されたマップの順序付けは、Collections.reverseOrder(comparator()) と等価になります。式 m.descendingMap().descendingMap() から返される m のビューは基本的に、m と等価になります。

戻り値:: このマップの逆順のビュー

navigableKeySet

NavigableSet<K> navigableKeySet()

このマップに含まれるキーの NavigableSet ビューを返します。セットの反復子は、キーを昇順で返します。セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。セットの反復処理中にマップが変更された場合、反復処理の結果は定義されません (反復子自身の remove オペレーションを除く)。セットは要素の削除をサポートしており、対応するマッピングをマップから削除することができます。削除は、Iterator.remove、Set.remove、removeAll、retainAll、および clear の各オペレーションを通して行います。add および addAll オペレーションはサポートされません。

戻り値:: このマップ内のキーのナビゲート可能なセットビュー

descendingKeySet

NavigableSet<K> descendingKeySet()

このマップに含まれるキーの逆順の NavigableSet ビューを返します。セットの反復子は、キーを降順で返します。セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。セットの反復処理中にマップが変更された場合、反復処理の結果は定義されません (反復子自身の remove オペレーションを除く)。セットは要素の削除をサポートしており、対応するマッピングをマップから削除することができます。削除は、Iterator.remove、Set.remove、removeAll、retainAll、および clear の各オペレーションを通して行います。add および addAll オペレーションはサポートされません。

戻り値:: このマップ内のキーのナビゲート可能な逆順セットビュー

subMap

NavigableMap<K,V> subMap(K fromKey,
                         boolean fromInclusive,
                         K toKey,
                         boolean toInclusive)

マップの fromKey 〜 toKey のキー範囲を持つ部分のビューを返します。fromKey と toKey が等しい場合、返されるマップは空になります。ただし、fromExclusive と toExclusive がどちらも true の場合は除きます。返されるマップはこのマップに連動しており、返されるマップでの変更はこのマップに反映され、その逆の場合も同様です。返されるマップは、このマップがサポートするオプションのマップオペレーションをすべてサポートします。

返されるマップは、その範囲外のキーが挿入されようとしたり、端点のいずれかがその範囲外にあるようなサブマップが構築されようとしたりすると、IllegalArgumentException をスローします。

パラメータ:: fromKey - 返されるマップ内のキーの下端点; fromInclusive - 返されるビューに下端点が含まれるようにする場合は true; toKey - 返されるマップ内のキーの上端点; toInclusive - 返されるビューに上端点が含まれるようにする場合は true
戻り値:: マップの fromKey 〜 toKey のキー範囲を持つ部分のビュー
例外:: ClassCastException - このマップのコンパレータを使って (このマップがコンパレータを持たない場合は自然順序付けを使って) fromKey と toKey との相互比較を行えない場合。実装は、マップ内に現在存在しているキーと fromKey または toKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - fromKey または toKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - fromKey が toKey よりも大きい場合、またはこのマップ自体が制限された範囲を持っており、fromKey または toKey がその範囲の境界の外側にある場合

headMap

NavigableMap<K,V> headMap(K toKey,
                          boolean inclusive)

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

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:: toKey - 返されるマップ内のキーの上端点; inclusive - 返されるビューに上端点が含まれるようにする場合は true
戻り値:: toKey よりも小さいキー (inclusive が true の場合はそれよりも小さいかそれと等しいキー) を含むこのマップの部分のビュー
例外:: ClassCastException - toKey がこのマップのコンパレータと互換性がない場合 (または、このマップがコンパレータを持たない場合、toKey が Comparable を実装していない場合)。実装は、マップ内に現在存在しているキーと toKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - toKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - このマップ自体が制限された範囲を持っており、toKey がその範囲の境界の外側にある場合

tailMap

NavigableMap<K,V> tailMap(K fromKey,
                          boolean inclusive)

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

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:: fromKey - 返されるマップ内のキーの下端点; inclusive - 返されるビューに下端点が含まれるようにする場合は true
戻り値:: fromKey よりも大きいキー (inclusive が true の場合はそれよりも大きいかそれと等しいキー) を含むこのマップの部分のビュー
例外:: ClassCastException - fromKey がこのマップのコンパレータと互換性がない場合 (または、このマップがコンパレータを持たない場合、fromKey が Comparable を実装していない場合)。実装は、マップ内に現在存在しているキーと fromKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - fromKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - このマップ自体が制限された範囲を持っており、fromKey がその範囲の境界の外側にある場合

subMap

SortedMap<K,V> subMap(K fromKey,
                      K toKey)

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

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

subMap(fromKey, true, toKey, false) と等価です。

定義:: インタフェース SortedMap<K,V> 内の subMap

パラメータ:: fromKey - 返されるマップ内のキーの下端点 (これを含む); toKey - 返されるマップ内のキーの上端点 (これを含まない)
戻り値:: マップの fromKey (これを含む) 〜 toKey (これを含まない) のキー範囲を持つ部分のビュー
例外:: ClassCastException - このマップのコンパレータを使って (このマップがコンパレータを持たない場合は自然順序付けを使って) fromKey と toKey との相互比較を行えない場合。実装は、マップ内に現在存在しているキーと fromKey または toKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - fromKey または toKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - fromKey が toKey よりも大きい場合、またはこのマップ自体が制限された範囲を持っており、fromKey または toKey がその範囲の境界の外側にある場合

headMap

SortedMap<K,V> headMap(K toKey)

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

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

headMap(toKey, false) と等価です。

定義:: インタフェース SortedMap<K,V> 内の headMap

パラメータ:: toKey - 返されるマップ内のキーの上端点 (これを含まない)
戻り値:: マップの toKey より小さいキーを持つ部分のビュー
例外:: ClassCastException - toKey がこのマップのコンパレータと互換性がない場合 (または、このマップがコンパレータを持たない場合、toKey が Comparable を実装していない場合)。実装は、マップ内に現在存在しているキーと toKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - toKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - このマップ自体が制限された範囲を持っており、toKey がその範囲の境界の外側にある場合

tailMap

SortedMap<K,V> tailMap(K fromKey)

マップの fromKey 以上のキーを持つ部分のビューを返します。返されるマップはこのマップに連動しており、返されるマップでの変更はこのマップに反映され、その逆の場合も同様です。返されるマップは、このマップがサポートするオプションのマップオペレーションをすべてサポートします。

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

tailMap(fromKey, true) と等価です。

定義:: インタフェース SortedMap<K,V> 内の tailMap

パラメータ:: fromKey - 返されるマップ内のキーの下端点 (これを含む)
戻り値:: マップの fromKey 以上のキーを持つ部分のビュー
例外:: ClassCastException - fromKey がこのマップのコンパレータと互換性がない場合 (または、このマップがコンパレータを持たない場合、fromKey が Comparable を実装していない場合)。実装は、マップ内に現在存在しているキーと fromKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - fromKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - このマップ自体が制限された範囲を持っており、fromKey がその範囲の境界の外側にある場合