モジュール java.base

パッケージ java.util

インタフェースNavigableMap<K,V>

型パラメータ:

K - このマップで保持されるキーの型

V - マップされる値の型

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

Map<K,V>, SortedMap<K,V>

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

ConcurrentNavigableMap<K,V>

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

ConcurrentSkipListMap, TreeMap

public interface NavigableMap<K,V>
extends SortedMap<K,V>

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

NavigableMapへのアクセスやトラバースは、キーの昇順、降順のいずれかで行えます。 descendingMap()メソッドは、すべての関係メソッドと方向メソッドの感覚が反転したマップのビューを返します。 オペレーションやビューのパフォーマンスは通常、降順よりも昇順のほうが高速になります。 メソッドsubMap(K, boolean, K, boolean)、headMap(K, boolean)、およびtailMap(K, boolean)は、SortedMapメソッドとは異なり、下限と上限が排他的か排他的かを記述する追加の引数を受け入れます。 どのNavigableMapのサブマップでもNavigableMapインタフェースを実装する必要があります。

このインタフェースでは、最小のマッピングと最大のマッピングがあればそれを返すか削除するメソッドfirstEntry()、pollFirstEntry()、lastEntry()、およびpollLastEntry()が追加されています。存在しない場合はnullを返します。

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

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

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

導入されたバージョン:

1.6

ネストされたクラスのサマリー

インタフェース java.util.Mapで宣言されたネストされたクラス/インタフェース

Map.Entry<K,V>

メソッドのサマリー

修飾子と型	メソッド	説明
Map.Entry<K,V>	ceilingEntry(K key)	指定されたキー以上の、最小のキーと関連するキーと値のマッピングを返します。そのようなキーが存在しない場合は、nullを返します。
K	ceilingKey(K key)	指定されたキーと等しいかそれよりも大きいキーの中で最小のものを返します。そのようなキーが存在しない場合はnullを返します。
NavigableSet<K>	descendingKeySet()	このマップに含まれるキーの逆順のNavigableSetビューを返します。
NavigableMap<K,V>	descendingMap()	このマップ内に保持されているマッピングの逆順のビューを返します。
Map.Entry<K,V>	firstEntry()	このマップ内の最小のキーに関連付けられたキーと値のマッピングを返します。マップが空の場合、nullを返します。
Map.Entry<K,V>	floorEntry(K key)	指定されたキー以下の、最大のキーに関連付けられたキーと値のマッピングを返します。そのようなキーが存在しない場合は、nullを返します。
K	floorKey(K key)	指定されたキーと等しいかそれよりも小さいキーの中で最大のものを返します。そのようなキーが存在しない場合はnullを返します。
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)	指定されたキーよりも確実に大きい、最小のキーに関連付けられたキーと値のマッピングを返します。そのようなキーが存在しない場合は、nullを返します。
K	higherKey(K key)	指定されたキーよりも確実に大きいキーの中で最小のものを返します。そのようなキーが存在しない場合はnullを返します。
Map.Entry<K,V>	lastEntry()	このマップ内の最大のキーに関連付けられたキーと値のマッピングを返します。マップが空の場合、nullを返します。
Map.Entry<K,V>	lowerEntry(K key)	指定されたキーよりも確実に小さい、最大のキーに関連付けられたキーと値のマッピングを返します。そのようなキーが存在しない場合は、nullを返します。
K	lowerKey(K key)	指定されたキーよりも確実に小さいキーの中で最大のものを返します。そのようなキーが存在しない場合はnullを返します。
NavigableSet<K>	navigableKeySet()	このマップに含まれるキーのNavigableSetビューを返します。
Map.Entry<K,V>	pollFirstEntry()	このマップ内の最小のキーに関連付けられたキーと値のマッピングを削除し、返します。マップが空の場合、nullを返します。
Map.Entry<K,V>	pollLastEntry()	このマップ内の最大のキーに関連付けられたキーと値のマッピングを削除し、返します。マップが空の場合、nullを返します。
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.Mapで宣言されたメソッド

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size

インタフェース java.util.SortedMapで宣言されたメソッド

comparator, entrySet, firstKey, keySet, lastKey, values

メソッドの詳細

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が等しい場合、返されるマップは、fromInclusiveとtoInclusiveの両方が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がその範囲から外れている場合