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、floorEntry、ceilingEntry 和 higherEntry 分別返回與小於、小於等於、大於等於、大於給定鍵的鍵關聯的 Map.Entry 物件，如果不存在這樣的鍵，則返回 null。類似地，方法 lowerKey、floorKey、ceilingKey 和 higherKey 只返回關聯的鍵。所有這些方法是為尋找條目而不是遍歷條目而設計的。

可以按照鍵的升序或降序存取和遍歷 NavigableMap。descendingMap 方法返回映射的一個視圖，該視圖表示的所有關係方法和方向方法都是逆向的。升序操作和視圖的性能很可能比降序操作和視圖的性能要好。subMap、headMap 和 tailMap 方法與名稱相似的 SortedMap 方法的不同之處在於：可以接受用於描述是否包括（或不包括）下邊界和上邊界的附加參數。任何 NavigableMap 的 Submap 必須實作 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) 返回一個鍵-值映射關係，它與大於等於給定鍵的最小鍵關聯；如果不存在這樣的鍵，則返回 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) 返回此映射的部分視圖，其鍵小於（或等於，如果 inclusive 為 true）toKey。
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) 返回此映射的部分視圖，其鍵大於（或等於，如果 inclusive 為 true）fromKey。

從介面 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()

返回此映射中所包含映射關係的逆序視圖。降序映射受此映射的支持，因此對映射的更改將反映在降序映射中，反之亦然。如果在對任一映射的 collection 視圖進行迭代的同時修改了任一映射（通過迭代器自己的 remove 操作除外），則迭代結果是不確定的。

返回映射的順序等於 Collections.reverseOrder(comparator())。表達式 m.descendingMap().descendingMap() 返回的 m 視圖基本等於 m。

返回：

此映射的逆序視圖

navigableKeySet

NavigableSet<K> navigableKeySet()

返回此映射中所包含鍵的 NavigableSet 視圖。set 的迭代器按升序返回鍵。set 受映射支持，因此對映射的更改將反映在 set 中，反之亦然。如果正在對 set 進行迭代的同時修改了映射（通過迭代器自己的 remove 操作除外），則迭代結果是不確定的。set 支持元素移除，即通過 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作從映射中移除相應的映射關係。它不支持 add 或 addAll 操作。

返回：

此映射中鍵的可導航 set 視圖

descendingKeySet

NavigableSet<K> descendingKeySet()

返回此映射中所包含鍵的逆序 NavigableSet 視圖。set 的迭代器按降序返回鍵。set 受映射支持，因此對映射的更改將反映在 set 中，反之亦然。如果正在對 set 進行迭代的同時修改了映射（通過迭代器自己的 remove 操作除外），則迭代結果是不確定的。set 支持元素移除，即通過 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作從映射中移除相應的映射關係。它不支持 add 或 addAll 操作。

返回：

此映射中鍵的逆序可導航 set 視圖

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)

返回此映射的部分視圖，其鍵小於（或等於，如果 inclusive 為 true）toKey。返回的映射受此映射支持，因此返回映射中的更改將反映在此映射中，反之亦然。返回的映射支持此映射支持的所有可選映射操作。

如果試圖在返回映射的範圍之外插入一個鍵，則返回的映射將拋出 IllegalArgumentException。

參數：

toKey - 返回映射中鍵的高端點

inclusive - 如果高端點要包含在返回的視圖中，則為 true

返回：

此映射的部分視圖，其鍵小於（或等於，如果 inclusive 為 true）toKey

拋出：

ClassCastException - 如果 toKey 與此映射的比較器不相容（如果映射沒有比較器；如果 toKey 沒有實作 Comparable）。如果 toKey 不能與映射中的當前鍵進行比較，則實作可以（但不是必須）拋出此異常。

NullPointerException - 如果 toKey 為 null 並且此映射不允許 null 鍵

IllegalArgumentException - 如果此映射本身有範圍限制，並且 toKey 位於範圍的邊界之外

tailMap

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

返回此映射的部分視圖，其鍵大於（或等於，如果 inclusive 為 true）fromKey。返回的映射受此映射支持，因此返回映射中的更改將反映在此映射中，反之亦然。返回的映射支持此映射支持的所有可選映射操作。

如果試圖在返回映射的範圍之外插入一個鍵，則返回的映射將拋出 IllegalArgumentException。

參數：

fromKey - 返回映射中鍵的低端點

inclusive - 如果低端點要包含在返回的視圖中，則為 true

返回：

此映射的部分視圖，其鍵大於（或等於，如果 inclusive 為 true）fromKey

拋出：

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 位於範圍的邊界之外