鸿蒙OS NavigableMap

NavigableMap

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

使用navigation方法扩展的 SortedMap，返回给定搜索目标的最接近匹配项。 方法lowerEntry、floorEntry、ceilingEntry和higherEntry分别返回与键关联的Map.Entry对象小于、小于或等于、大于或等于、大于给定键，如果没有该键则返回null。 类似地，方法lowerKey、floorKey、ceilingKey 和higherKey 仅返回关联的键。 所有这些方法都是为定位而不是遍历条目而设计的。

可以按升序或降序键顺序访问和遍历 NavigableMap。 descendingMap 方法返回一个map视图，其中所有关系和方向方法的意义都颠倒了。 上升的操作和视图的性能可能比下降的快。 方法 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 集合框架的成员。

嵌套类摘要

从接口 java.util.Map 继承的嵌套类/接口
Map.Entry<K,V>

方法总结

修饰符和类型	方法	描述
Map.Entry<K,V>	ceilingEntry(K key)	返回与大于或等于给定键的最小键关联的键值映射，如果没有这样的键，则返回 null。
K	ceilingKey(K key)	返回大于或等于给定键的最小键，如果没有这样的键，则返回 null。
NavigableSetK	descendingKeySet()	返回此映射中包含的键的逆序 NavigableSet 视图。
NavigableMapK,V	descendingMap()	返回此映射中包含的映射的逆序视图。
Map.EntryK,V	firstEntry()	返回与此映射中的最小键关联的键值映射，如果映射为空，则返回 null。
Map.EntryK,V	floorEntry(K key)	返回与小于或等于给定键的最大键关联的键值映射，如果没有这样的键，则返回 null。
K	floorKey(K key)	返回小于或等于给定键的最大键，如果没有这样的键，则返回 null。
SortedMapK,V	headMap(K toKey)	返回此映射部分的视图，其键严格小于 toKey。
NavigableMapK,V	headMap(K toKey, boolean inclusive)	返回此映射部分的视图，其键小于（或等于，如果 inclusive 为真）toKey。
Map.EntryK,V	higherEntry(K key)	返回与严格大于给定键的最小键关联的键值映射，如果没有这样的键，则返回 null。
K	higherKey(K key)	返回严格大于给定键的最小键，如果没有这样的键，则返回 null。
Map.EntryK,V	lastEntry()	返回与此映射中最大键关联的键值映射，如果映射为空，则返回 null。
Map.EntryK,V	lowerEntry(K key)	返回与严格小于给定键的最大键关联的键值映射，如果没有这样的键，则返回 null。
K	lowerKey(K key)	返回严格小于给定键的最大键，如果没有这样的键，则返回 null。
NavigableSetK	navigableKeySet()	返回此map中包含的键的 NavigableSet 视图。
Map.EntryK,V	pollFirstEntry()	移除并返回与此映射中最小键关联的键值映射，如果映射为空，则返回 null。
Map.EntryK,V	pollLastEntry()	删除并返回与此映射中最大键关联的键值映射，如果映射为空，则返回 null。
NavigableMapK,V	subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)	返回此映射部分的视图，其键范围从 fromKey 到 toKey。
SortedMapK,V	subMap(K fromKey, K toKey)	返回此映射部分的视图，其键范围从 fromKey（包括）到 toKey（不包括）。
SortedMapK,V	tailMap(K fromKey)	返回此map部分的视图，其键大于或等于 fromKey。
NavigableMapK,V	tailMap(K fromKey, boolean inclusive)	返回此映射部分的视图，其键大于（或等于，如果 inclusive 为真）fromKey。

从接口 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.EntryK,V lowerEntry(K key)

返回与严格小于给定键的最大键关联的键值映射，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

最大键小于键的条目，如果没有这样的键，则返回 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

lowerKey

K lowerKey(K key)

返回严格小于给定键的最大键，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

小于 key 的最大键，如果没有这样的键，则为 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

floorEntry

Map.EntryK,V floorEntry(K key)

返回与小于或等于给定键的最大键关联的键值映射，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

最大键小于或等于键的条目，如果没有这样的键，则返回 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

floorKey

K floorKey(K key)

返回小于或等于给定键的最大键，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

小于或等于 key 的最大键，如果没有这样的键，则为 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

ceilingEntry

Map.EntryK,V ceilingEntry(K key)

返回与大于或等于给定键的最小键关联的键值映射，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

具有大于或等于 key 的最小键的条目，如果没有这样的键，则返回 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

ceilingKey

K ceilingKey(K key)

返回大于或等于给定键的最小键，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

大于或等于 key 的最小键，如果没有这样的键，则返回 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

higherEntry

Map.EntryK,V higherEntry(K key)

返回与严格大于给定键的最小键关联的键值映射，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

最小键大于键的条目，如果没有这样的键，则返回 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

higherKey

K higherKey(K key)

返回严格大于给定键的最小键，如果没有这样的键，则返回 null。

参数：

参数名称	参数描述
key	键

返回:

大于 key 的最小键，如果没有这样的键，则返回 null

Throws:

Throw名称	Throw描述
ClassCastException	如果指定的键无法与map中当前的键进行比较
NullPointerException	如果指定的键为空并且此映射不允许空键

firstEntry

Map.EntryK,V firstEntry()

返回与此映射中的最小键关联的键值映射，如果映射为空，则返回 null。

返回:

具有最少键的条目，如果此映射为空，则为 null

lastEntry

Map.EntryK,V lastEntry()

返回与此映射中最大键关联的键值映射，如果映射为空，则返回 null。

返回:

具有最大键的条目，如果此映射为空，则返回 null

pollFirstEntry

Map.EntryK,V pollFirstEntry()

移除并返回与此映射中最小键关联的键值映射，如果映射为空，则返回 null。

返回:

此映射的已删除第一个条目，如果此映射为空，则返回 null

pollLastEntry

Map.EntryK,V pollLastEntry()

删除并返回与此映射中最大键关联的键值映射，如果映射为空，则返回 null。

返回:

此映射的已删除最后一个条目，如果此映射为空，则返回 null

descendingMap

NavigableMapK,V descendingMap()

返回此映射中包含的映射的逆序视图。 下降映射由该映射支持，因此对映射的更改会反映在下降映射中，反之亦然。 如果在对任一映射的集合视图进行迭代时修改了任一映射（通过迭代器自己的删除操作除外），则迭代的结果是未定义的。

返回的映射具有等价于 Collections#reverseOrder(Comparator)(comparator()) 的排序。 表达式 m.descendingMap().descendingMap() 返回一个 m 的视图，基本上等同于 m。

返回:

此map的逆序视图

navigableKeySet

NavigableSetK navigableKeySet()

返回此map中包含的键的 NavigableSet 视图。 集合的迭代器按升序返回键。 集合由map支持，因此对map的更改会反映在集合中，反之亦然。 如果在对集合进行迭代时修改了映射（通过迭代器自己的删除操作除外），则迭代的结果是不确定的。 该集合支持元素移除，即通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作从映射中移除相应的映射。 它不支持 add 或 addAll 操作。

返回:

此map中键的可导航集视图

descendingKeySet

NavigableSetK descendingKeySet()

返回此映射中包含的键的逆序 NavigableSet 视图。 该集合的迭代器按降序返回键。 集合由map支持，因此对map的更改会反映在集合中，反之亦然。 如果在对集合进行迭代时修改了映射（通过迭代器自己的删除操作除外），则迭代的结果是不确定的。 该集合支持元素移除，即通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作从映射中移除相应的映射。 它不支持 add 或 addAll 操作。

返回:

此map中键的反向可导航集视图

subMap

NavigableMapK,V subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)

返回此映射部分的视图，其键范围从 fromKey 到 toKey。 如果 fromKey 和 toKey 相等，则返回的映射为空，除非 fromInclusive 和 toInclusive 都为真。 返回的map由此map支持，因此返回map中的更改会反映在此map中，反之亦然。 返回的map支持该map支持的所有可选map操作。

返回的映射将在尝试插入超出其范围的键或构造其端点位于其范围之外的子映射时抛出 IllegalArgumentException。

参数：

参数名称	参数描述
fromKey	返回映射中键的低端点
fromInclusive	如果要在返回的视图中包含低端点，则为 true
toKey	返回映射中键的高端点
toInclusive	如果要在返回的视图中包含高端端点，则为 true

返回:

此map部分的视图，其键范围从 fromKey 到 toKey

Throws:

Throw名称	Throw描述
ClassCastException	如果 fromKey 和 toKey 无法使用此映射的比较器相互比较（或者，如果映射没有比较器，则使用自然排序）。 如果无法将 fromKey 或 toKey 与映射中当前的键进行比较，则实现可以但不是必须抛出此异常。
NullPointerException	如果 fromKey 或 toKey 为空并且此映射不允许空键
IllegalArgumentException	如果 fromKey 大于 toKey； 或者如果此map本身具有限制范围，并且 fromKey 或 toKey 位于范围的范围之外

headMap

NavigableMapK,V headMap(K toKey, boolean inclusive)

返回此映射部分的视图，其键小于（或等于，如果 inclusive 为真）toKey。 返回的map由此map支持，因此返回map中的更改会反映在此map中，反之亦然。 返回的map支持该map支持的所有可选map操作。

返回的映射将在尝试在其范围之外插入键时抛出 IllegalArgumentException。

参数：

参数名称	参数描述
toKey	返回映射中键的高端点
inclusive	如果要在返回的视图中包含高端端点，则为 true

返回:

此map部分的视图，其键小于（或等于，如果 inclusive 为真）toKey

Throws:

Throw名称	Throw描述
ClassCastException	如果 toKey 与此map的比较器不兼容（或者，如果map没有比较器，如果 toKey 没有实现 Comparable）。 如果 toKey 无法与map中当前的键进行比较，则实现可以但不是必须抛出此异常。
NullPointerException	如果 toKey 为空并且此映射不允许空键
IllegalArgumentException	如果此map本身具有受限范围，并且 toKey 位于范围之外

tailMap

NavigableMapK,V tailMap(K fromKey, boolean inclusive)

返回此映射部分的视图，其键大于（或等于，如果 inclusive 为真）fromKey。 返回的map由此map支持，因此返回map中的更改会反映在此map中，反之亦然。 返回的map支持该map支持的所有可选map操作。

返回的映射将在尝试在其范围之外插入键时抛出 IllegalArgumentException。

参数：

参数名称	参数描述
fromKey	返回映射中键的低端点
inclusive	如果要在返回的视图中包含低端点，则为 true

返回:

此map部分的视图，其键大于（或等于，如果 inclusive 为真）fromKey

Throws:

Throw名称	Throw描述
ClassCastException	如果 fromKey 与此映射的比较器不兼容（或者，如果映射没有比较器，如果 fromKey 未实现 Comparable）。 如果无法将 fromKey 与当前映射中的键进行比较，则实现可以但不是必须抛出此异常。
NullPointerException	如果 fromKey 为空且此映射不允许空键
IllegalArgumentException	如果此map本身具有限制范围，并且 fromKey 位于范围范围之外

subMap

SortedMapK,V subMap(K fromKey, K toKey)

返回此映射部分的视图，其键范围从 fromKey（包括）到 toKey（不包括）。 （如果 fromKey 和 toKey 相等，则返回的映射为空。）返回的映射受此映射的支持，因此返回映射中的更改会反映在此映射中，反之亦然。 返回的map支持该map支持的所有可选map操作。

返回的映射将在尝试在其范围之外插入键时抛出 IllegalArgumentException。

等价于 subMap(fromKey, true, toKey, false)。

指定者：

接口 SortedMapK,V 中的 subMap

参数：

参数名称	参数描述
fromKey	返回映射中键的低端点（包括）
toKey	返回映射中键的高端（不包括）

返回:

此map部分的视图，其键范围从 fromKey（包括）到 toKey（不包括）

Throws:

Throw名称	Throw描述
ClassCastException	如果 fromKey 和 toKey 无法使用此映射的比较器相互比较（或者，如果映射没有比较器，则使用自然排序）。 如果无法将 fromKey 或 toKey 与映射中当前的键进行比较，则实现可以但不是必须抛出此异常。
NullPointerException	如果 fromKey 或 toKey 为空并且此映射不允许空键
IllegalArgumentException	如果 fromKey 大于 toKey； 或者如果此map本身具有限制范围，并且 fromKey 或 toKey 位于范围的范围之外

headMap

SortedMapK,V headMap(K toKey)

返回此映射部分的视图，其键严格小于 toKey。 返回的map由此map支持，因此返回map中的更改会反映在此map中，反之亦然。 返回的map支持该map支持的所有可选map操作。

返回的映射将在尝试在其范围之外插入键时抛出 IllegalArgumentException。

等效于 headMap(toKey, false)。

指定者：

接口 SortedMapK,V 中的 headMap

参数：

参数名称	参数描述
toKey	返回映射中键的高端（不包括）

返回:

此map部分的视图，其键严格小于 toKey

Throws:

Throw名称	Throw描述
ClassCastException	如果 toKey 与此map的比较器不兼容（或者，如果map没有比较器，如果 toKey 没有实现 Comparable）。 如果 toKey 无法与map中当前的键进行比较，则实现可以但不是必须抛出此异常。
NullPointerException	如果 toKey 为空并且此映射不允许空键
IllegalArgumentException	如果此map本身具有受限范围，并且 toKey 位于范围之外

tailMap

SortedMapK,V tailMap(K fromKey)

返回此map部分的视图，其键大于或等于 fromKey。 返回的map由此map支持，因此返回map中的更改会反映在此map中，反之亦然。 返回的map支持该map支持的所有可选map操作。

返回的映射将在尝试在其范围之外插入键时抛出 IllegalArgumentException。

等价于tailMap(fromKey, true)。

指定者：

接口 SortedMapK,V 中的 tailMap

参数：

参数名称	参数描述
fromKey	返回映射中键的低端点（包括）

返回:

此map部分的视图，其键大于或等于 fromKey

Throws:

Throw名称	Throw描述
ClassCastException	如果 fromKey 与此映射的比较器不兼容（或者，如果映射没有比较器，如果 fromKey 未实现 Comparable）。 如果无法将 fromKey 与当前映射中的键进行比较，则实现可以但不是必须抛出此异常。
NullPointerException	如果 fromKey 为空且此映射不允许空键
IllegalArgumentException	如果此map本身具有限制范围，并且 fromKey 位于范围范围之外