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

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

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。