Module java.base
Package java.util

Interface NavigableMap<K,V>

类型参数:
K - 此映射维护的键的类型
V - 映射值的类型
所有超接口:
Map<K,V>, SequencedMap<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。

方法ceilingEntry(K)、firstEntry()、floorEntry(K)、higherEntry(K)、lastEntry()、lowerEntry(K)、pollFirstEntry()和pollLastEntry()返回作为调用时映射快照的Map.Entry实例。它们不支持通过可选的setValue方法对底层映射进行更改。

方法subMap(K, K)、headMap(K)和tailMap(K)被指定为返回SortedMap，以允许现有的SortedMap实现兼容地改装为实现NavigableMap，但鼓励此接口的扩展和实现重写这些方法以返回NavigableMap。类似地，SortedMap.keySet()可以被重写为返回NavigableSet。

此接口是Java集合框架的成员。

自版本:
1.6

  • Method Details

    • lowerEntry

      Map.Entry<K,V> lowerEntry(K key)
      返回与严格小于给定键的最大键关联的键值映射，如果没有这样的键则返回null。
      参数:
      key - 键
      返回:
      与key小于的最大键的条目，如果没有这样的键则返回null
      抛出:
      ClassCastException - 如果指定的键无法与当前映射中的键进行比较
      NullPointerException - 如果指定的键为null且此映射不允许空键

    • lowerKey

      K lowerKey(K key)
      返回严格小于给定键的最大键，如果没有这样的键则返回null。
      参数:
      key - 键
      返回:
      小于key的最大键，如果没有这样的键则返回null
      抛出:
      ClassCastException - 如果指定的键无法与当前映射中的键进行比较
      NullPointerException - 如果指定的键为null且此映射不允许空键

    • floorEntry

      Map.Entry<K,V> floorEntry(K key)
      返回与小于或等于给定键的最大键关联的键值映射，如果没有这样的键则返回null。
      参数:
      key - 键
      返回:
      与小于或等于key的最大键的条目，如果没有这样的键则返回null
      抛出:
      ClassCastException - 如果指定的键无法与当前映射中的键进行比较
      NullPointerException - 如果指定的键为null且此映射不允许空键

    • floorKey

      K floorKey(K key)
      返回小于或等于给定键的最大键，如果没有这样的键则返回null。
      参数:
      key - 键
      返回:
      小于或等于key的最大键，如果没有这样的键则返回null
      抛出:
      ClassCastException - 如果指定的键无法与当前映射中的键进行比较
      NullPointerException - 如果指定的键为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。
      指定者:
      firstEntry 在接口 SequencedMap<K,V>
      返回:
      最小键对应的条目，如果此地图为空则返回null

    • lastEntry

      Map.Entry<K,V> lastEntry()
      返回此地图中最大键相关联的键值映射，如果地图为空则返回null。
      指定者:
      lastEntry 在接口 SequencedMap<K,V>
      返回:
      最大键对应的条目，如果此地图为空则返回null

    • pollFirstEntry

      Map.Entry<K,V> pollFirstEntry()
      移除并返回此地图中最小键相关联的键值映射，如果地图为空则返回null。
      指定者:
      pollFirstEntry 在接口 SequencedMap<K,V>
      返回:
      此地图的第一个条目，如果地图为空则返回null

    • pollLastEntry

      Map.Entry<K,V> pollLastEntry()
      移除并返回此地图中最大键相关联的键值映射，如果地图为空则返回null。
      指定者:
      pollLastEntry 在接口 SequencedMap<K,V>
      返回:
      此地图的最后一个条目，如果地图为空则返回null

    • descendingMap

      NavigableMap<K,V> descendingMap()
      返回此地图中包含的映射的逆序视图。降序地图由此地图支持，因此对地图的更改会反映在降序地图中，反之亦然。如果在对任一地图的集合视图进行迭代时（除非通过迭代器自身的remove操作），在进行修改，则迭代的结果是未定义的。

      返回的地图具有等同于Collections.reverseOrder(comparator())的排序。表达式m.descendingMap().descendingMap()返回与m本质上等效的视图。

      返回:
      此地图的逆序视图

    • 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)
      返回此地图中键小于（如果inclusive为true则为小于或等于）toKey的部分的视图。返回的地图由此地图支持，因此返回地图中的更改会反映在此地图中，反之亦然。返回的地图支持此地图支持的所有可选地图操作。

      如果尝试插入超出其范围的键，则返回的地图将抛出IllegalArgumentException。

      参数:
      toKey - 返回的地图中键的高端点
      inclusive - 如果要包括返回视图中的高端点，则为true
      返回:
      返回此地图部分的视图，其键小于（如果inclusive为true，则为小于或等于）toKey
      抛出:
      ClassCastException - 如果toKey与此地图的比较器不兼容（或者，如果地图没有比较器，则如果toKey未实现Comparable）。如果toKey无法与地图中当前的键进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果toKey为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且此地图不允许空键
      IllegalArgumentException - 如果此地图本身具有受限范围，并且fromKey超出范围的边界

    • subMap

      SortedMap<K,V> subMap(K fromKey, K toKey)
      返回一个视图，其中键的范围从fromKey（包括）到toKey（不包括）。（如果fromKey和toKey相等，则返回的地图为空。）返回的地图由此地图支持，因此返回地图中的更改会反映在此地图中，反之亦然。返回的地图支持此地图支持的所有可选地图操作。

      如果尝试在其范围之外插入键，则返回的地图将抛出IllegalArgumentException。

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

      指定者:
      subMap 在接口 SortedMap<K,V>
      参数:
      fromKey - 返回地图中键的低端点（包括）
      toKey - 返回地图中键的高端点（不包括）
      返回:
      返回此地图部分的视图，其键的范围从fromKey（包括）到toKey（不包括）
      抛出:
      ClassCastException - 如果fromKey和toKey无法使用此地图的比较器进行比较（或者，如果地图没有比较器，则使用自然排序）。如果fromKey或toKey无法与地图中当前的键进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果fromKey或toKey为null且此地图不允许空键
      IllegalArgumentException - 如果fromKey大于toKey；或者如果此地图本身具有受限范围，并且fromKey或toKey超出范围的边界

    • headMap

      SortedMap<K,V> headMap(K toKey)
      返回一个视图，其中键严格小于toKey。返回的地图由此地图支持，因此返回地图中的更改会反映在此地图中，反之亦然。返回的地图支持此地图支持的所有可选地图操作。

      如果尝试在其范围之外插入键，则返回的地图将抛出IllegalArgumentException。

      等同于headMap(toKey, false)。

      指定者:
      headMap 在接口 SortedMap<K,V>
      参数:
      toKey - 返回地图中键的高端点（不包括）
      返回:
      返回此地图部分的视图，其键严格小于toKey
      抛出:
      ClassCastException - 如果toKey与此地图的比较器不兼容（或者，如果地图没有比较器，则如果toKey未实现Comparable）。如果toKey无法与地图中当前的键进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果toKey为null且此地图不允许空键
      IllegalArgumentException - 如果此地图本身具有受限范围，并且toKey超出范围的边界

    • tailMap

      SortedMap<K,V> tailMap(K fromKey)
      返回一个视图，其中键大于或等于fromKey。返回的地图由此地图支持，因此返回地图中的更改会反映在此地图中，反之亦然。返回的地图支持此地图支持的所有可选地图操作。

      如果尝试在其范围之外插入键，则返回的地图将抛出IllegalArgumentException。

      等同于tailMap(fromKey, true)。

      指定者:
      tailMap 在接口 SortedMap<K,V>
      参数:
      fromKey - 返回地图中键的低端点（包括）
      返回:
      返回此地图部分的视图，其键大于或等于fromKey
      抛出:
      ClassCastException - 如果fromKey与此地图的比较器不兼容（或者，如果地图没有比较器，则如果fromKey未实现Comparable）。如果fromKey无法与地图中当前的键进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果fromKey为null且此地图不允许空键
      IllegalArgumentException - 如果此地图本身具有受限范围，并且fromKey超出范围的边界

    • reversed

      default NavigableMap<K,V> reversed()
      返回此地图的逆序视图。返回视图中映射的遭遇顺序与此地图中映射的遭遇顺序相反。逆序排序会影响所有对顺序敏感的操作，包括对返回视图的视图集合的操作。如果实现允许对此视图进行修改，则修改会“写入”到基础地图。对基础地图的更改可能会或可能不会在此反转视图中可见，这取决于实现。

      此方法等同于descendingMap。

      指定者:
      reversed 在接口 SequencedMap<K,V>
      指定者:
      reversed 在接口 SortedMap<K,V>
      实现要求:
      此接口中的实现返回调用descendingMap方法的结果。
      返回:
      作为NavigableMap的此地图的逆序视图
      自:
      21