java.util

接口
异常
错误
类型参数:
K - 此映射维护的键的类型
V - 被映射的值的类型
所有超级接口:
Map<K,V>, SortedMap<K,V>
所有已知子接口:
ConcurrentNavigableMap<K,V>
所有已知实现类:
ConcurrentSkipListMap, TreeMap

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

扩展的 SortedMap,具有了针对给定搜索目标返回最接近匹配项的导航方法。方法 lowerEntryfloorEntryceilingEntryhigherEntry 分别返回与小于、小于等于、大于等于、大于给定键的键关联的 Map.Entry 对象,如果不存在这样的键,则返回 null。类似地,方法 lowerKeyfloorKeyceilingKeyhigherKey 只返回关联的键。所有这些方法是为查找条目而不是遍历条目而设计的。

可以按照键的升序或降序访问和遍历 NavigableMapdescendingMap 方法返回映射的一个视图,该视图表示的所有关系方法和方向方法都是逆向的。升序操作和视图的性能很可能比降序操作和视图的性能要好。subMapheadMaptailMap 方法与名称相似的 SortedMap 方法的不同之处在于:可以接受用于描述是否包括(或不包括)下边界和上边界的附加参数。任何 NavigableMap 的 Submap 必须实现 NavigableMap 接口。

此外,此接口还定义了 firstEntrypollFirstEntrylastEntrypollLastEntry 方法,它们返回和/或移除最小和最大的映射关系(如果存在),否则返回 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)
          返回此映射的部分视图,其键的范围从 fromKeytoKey
 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.removeSet.removeremoveAllretainAllclear 操作从映射中移除相应的映射关系。它不支持 addaddAll 操作。

返回:
此映射中键的可导航 set 视图

descendingKeySet

NavigableSet<K> descendingKeySet()
返回此映射中所包含键的逆序 NavigableSet 视图。set 的迭代器按降序返回键。set 受映射支持,因此对映射的更改将反映在 set 中,反之亦然。如果正在对 set 进行迭代的同时修改了映射(通过迭代器自己的 remove 操作除外),则迭代结果是不确定的。set 支持元素移除,即通过 Iterator.removeSet.removeremoveAllretainAllclear 操作从映射中移除相应的映射关系。它不支持 addaddAll 操作。

返回:
此映射中键的逆序可导航 set 视图

subMap

NavigableMap<K,V> subMap(K fromKey,
                         boolean fromInclusive,
                         K toKey,
                         boolean toInclusive)
返回此映射的部分视图,其键的范围从 fromKeytoKey。如果 fromKeytoKey 相等,则返回的映射为空,除非 fromExclusivetoExclusive 都为 true。返回的映射受此映射支持,因此返回映射中的更改将反映在此映射中,反之亦然。返回的映射支持此映射支持的所有可选映射操作。

如果试图在返回映射的范围之外插入一个键,或者构造一个任一端点位于其范围之外的子映射,则返回的映射将抛出 IllegalArgumentException

参数:
fromKey - 返回映射中键的低端点
fromInclusive - 如果低端点要包含在返回的视图中,则为 true
toKey - 返回映射中键的高端点
toInclusive - 如果高端点要包含在返回的视图中,则为 true
返回:
此映射的部分视图,其键范围从 fromKeytoKey
抛出:
ClassCastException - 如果不能使用此映射的比较器(如果映射没有比较器,则使用自然顺序)比较 fromKeytoKey。如果 fromKeytoKey 不能与映射中当前键进行比较,则实现可以(但不是必须)抛出此异常。
NullPointerException - 如果 fromKeytoKey 为 null 并且此映射不允许 null 键
IllegalArgumentException - 如果 fromKey 大于 toKey;如果此映射本身有范围限制,并且 fromKeytoKey 位于范围的边界之外

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(不包括)。(如果 fromKeytoKey 相等,则返回映射为空。)返回的映射受此映射支持,所以在返回映射中的更改将反映在此映射中,反之亦然。返回的映射支持此映射支持的所有可选映射操作。

如果试图在返回映射的范围之外插入键,则返回的映射将抛出 IllegalArgumentException

等效于 subMap(fromKey, true, toKey, false)

指定者:
接口 SortedMap<K,V> 中的 subMap
参数:
fromKey - 返回映射中键的低端点(包括)
toKey - 返回映射中键的高端点(不包括)
返回:
此映射的部分视图,其键值的范围从 fromKey(包括)到 toKey(不包括)
抛出:
ClassCastException - 如果无法使用此映射的比较器(如果此映射没有比较器,则使用自然顺序)比较 fromKeytoKey。如果 fromKeytoKey 不能与映射中当前键进行比较,则实现可以(但不是必须)抛出此异常。
NullPointerException - 如果 fromKeytoKey 为 null,并且此映射不允许使用 null 键
IllegalArgumentException - 如果 fromKey 大于 toKey;如果此映射本身有范围限制,并且 fromKeytoKey 位于范围的边界之外

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 位于范围的边界之外