Module java.base
Package java.util

Interface NavigableSet<E>

类型参数：
E - 此集合中维护的元素类型
所有超接口：
Collection<E>, Iterable<E>, SequencedCollection<E>, SequencedSet<E>, Set<E>, SortedSet<E>
所有已知实现类：
ConcurrentSkipListSet, TreeSet
public interface NavigableSet<E> extends SortedSet<E>
一个SortedSet，具有报告给定搜索目标的最接近匹配项的导航方法。方法lower(E)、floor(E)、ceiling(E)和higher(E)分别返回小于、小于或等于、大于或等于给定元素的元素，并在没有这样的元素时返回null。

NavigableSet可以按升序或降序访问和遍历。方法descendingSet()返回一个视图，其中所有关系和方向方法的意义被倒置。升序操作和视图的性能可能比降序操作更快。此接口还定义了方法pollFirst()和pollLast()，如果存在最低和最高元素，则返回并删除它们，否则返回null。方法subSet(E, boolean, E, boolean)、headSet(E, boolean)和tailSet(E, boolean)与同名的SortedSet方法不同，它们接受描述下限和上限是包含还是排除的附加参数。任何NavigableSet的子集必须实现NavigableSet接口。

在允许null元素的实现中，导航方法的返回值可能是模棱两可的。但是，即使在这种情况下，可以通过检查contains(null)来消除歧义。为了避免这种问题，鼓励此接口的实现不允许插入null元素。（请注意，Comparable元素的排序集固有地不允许null。）

方法subSet(E, E)、headSet(E)和tailSet(E)被指定为返回SortedSet，以允许现有的SortedSet实现兼容地改装为实现NavigableSet，但是鼓励此接口的扩展和实现重写这些方法以返回NavigableSet。

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

自Java版本：
1.6

  • Method Details

    • lower

      E lower(E e)
      返回此集合中严格小于给定元素的最大元素，如果没有这样的元素则返回null。
      参数：
      e - 要匹配的值
      返回：
      小于e的最大元素，如果没有这样的元素则返回null
      抛出：
      ClassCastException - 如果指定的元素无法与集合中当前元素进行比较
      NullPointerException - 如果指定的元素为null且此集合不允许null元素

    • floor

      E floor(E e)
      返回此集合中小于或等于给定元素的最大元素，如果没有这样的元素则返回null。
      参数：
      e - 要匹配的值
      返回：
      小于或等于e的最大元素，如果没有这样的元素则返回null
      抛出：
      ClassCastException - 如果指定的元素无法与集合中当前元素进行比较
      NullPointerException - 如果指定的元素为null且此集合不允许null元素

    • ceiling

      E ceiling(E e)
      返回此集合中大于或等于给定元素的最小元素，如果没有这样的元素则返回null。
      参数：
      e - 要匹配的值
      返回：
      大于或等于e的最小元素，如果没有这样的元素则返回null
      抛出：
      ClassCastException - 如果指定的元素无法与集合中当前元素进行比较
      NullPointerException - 如果指定的元素为null且此集合不允许null元素

    • higher

      E higher(E e)
      返回此集合中严格大于给定元素的最小元素，如果没有这样的元素则返回null。
      参数：
      e - 要匹配的值
      返回：
      大于e的最小元素，如果没有这样的元素则返回null
      抛出：
      ClassCastException - 如果指定的元素无法与集合中当前元素进行比较
      NullPointerException - 如果指定的元素为null且此集合不允许null元素

    • pollFirst

      E pollFirst()
      检索并删除第一个（最低）元素，如果此集合为空则返回null。
      返回：
      第一个元素，如果此集合为空则返回null

    • pollLast

      E pollLast()
      检索并删除最后一个（最高）元素，如果此集合为空则返回null。
      返回：
      最后一个元素，如果此集合为空则返回null

    • iterator

      Iterator<E> iterator()
      返回此集合中元素的迭代器，按升序排列。
      指定者：
      iterator 在接口 Collection<E>中
      指定者：
      iterator 在接口 Iterable<E>中
      指定者：
      iterator 在接口 Set<E>中
      返回：
      返回此集合中元素的迭代器，按升序排列

    • descendingSet

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

      返回的集合具有等效于Collections.reverseOrder(comparator())的排序。表达式s.descendingSet().descendingSet()返回与s本质上等效的视图。

      返回：
      此集合的逆序视图

    • descendingIterator

      Iterator<E> descendingIterator()
      返回此集合中元素的迭代器，按降序排列。在效果上等同于descendingSet().iterator()。
      返回：
      此集合中元素的迭代器，按降序排列

    • subSet

      NavigableSet<E> subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive)
      返回此集合部分元素的视图，这些元素的范围从fromElement到toElement。如果fromElement和toElement相等，则返回的集合为空，除非fromInclusive和toInclusive都为true。返回的集合由此集合支持，因此返回集合中的更改会反映在此集合中，反之亦然。返回的集合支持此集合支持的所有可选集合操作。

      如果尝试在其范围之外插入元素，则返回的集合将抛出IllegalArgumentException。

      参数：
      fromElement - 返回集合的低端点
      fromInclusive - 如果要在返回视图中包含低端点，则为true
      toElement - 返回集合的高端点
      toInclusive - 如果要在返回视图中包含高端点，则为true
      返回：
      从fromElement（包括）到toElement（不包括）的此集合部分元素的视图
      抛出：
      ClassCastException - 如果无法使用此集合的比较器将fromElement和toElement相互比较（或者，如果集合没有比较器，则使用自然排序）。如果fromElement或toElement无法与集合中当前元素进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果fromElement或toElement为null且此集合不允许空元素
      IllegalArgumentException - 如果fromElement大于toElement；或者如果此集合本身具有受限范围，并且fromElement或toElement位于范围的边界之外

    • headSet

      NavigableSet<E> headSet(E toElement, boolean inclusive)
      返回此集合部分元素的视图，这些元素小于（如果inclusive为true，则小于或等于）toElement。返回的集合由此集合支持，因此返回集合中的更改会反映在此集合中，反之亦然。返回的集合支持此集合支持的所有可选集合操作。

      如果尝试在其范围之外插入元素，则返回的集合将抛出IllegalArgumentException。

      参数：
      toElement - 返回集合的高端点
      inclusive - 如果要在返回视图中包含高端点，则为true
      返回：
      小于（如果inclusive为true，则小于或等于）toElement的此集合部分元素的视图
      抛出：
      ClassCastException - 如果toElement与此集合的比较器不兼容（或者，如果集合没有比较器，则toElement未实现Comparable）。如果toElement无法与集合中当前元素进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果toElement为null且此集合不允许空元素
      IllegalArgumentException - 如果此集合本身具有受限范围，并且toElement位于范围的边界之外

    • tailSet

      NavigableSet<E> tailSet(E fromElement, boolean inclusive)
      返回此集合部分元素的视图，这些元素大于（如果inclusive为true，则大于或等于）fromElement。返回的集合由此集合支持，因此返回集合中的更改会反映在此集合中，反之亦然。返回的集合支持此集合支持的所有可选集合操作。

      如果尝试在其范围之外插入元素，则返回的集合将抛出IllegalArgumentException。

      参数：
      fromElement - 返回集合的低端点
      inclusive - 如果要在返回视图中包含低端点，则为true
      返回：
      大于或等于fromElement的此集合部分元素的视图
      抛出：
      ClassCastException - 如果fromElement与此集合的比较器不兼容（或者，如果集合没有比较器，则fromElement未实现Comparable）。如果fromElement无法与集合中当前元素进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果fromElement为null且此集合不允许空元素
      IllegalArgumentException - 如果此集合本身具有受限范围，并且fromElement位于范围的边界之外

    • subSet

      SortedSet<E> subSet(E fromElement, E toElement)
      返回此集合部分元素的视图，这些元素的范围从fromElement（包括）到toElement（不包括）。（如果fromElement和toElement相等，则返回的集合为空。）返回的集合由此集合支持，因此返回集合中的更改会反映在此集合中，反之亦然。返回的集合支持此集合支持的所有可选集合操作。

      如果尝试在其范围之外插入元素，则返回的集合将抛出IllegalArgumentException。

      等效于subSet(fromElement, true, toElement, false)。

      指定者：
      subSet 在接口 SortedSet<E>中
      参数：
      fromElement - 返回集合的低端点（包括）
      toElement - 返回集合的高端点（不包括）
      返回：
      从fromElement（包括）到toElement（不包括）的此集合部分元素的视图
      抛出：
      ClassCastException - 如果无法使用此集合的比较器将fromElement和toElement相互比较（或者，如果集合没有比较器，则使用自然排序）。如果fromElement或toElement无法与集合中当前元素进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果fromElement或toElement为null且此集合不允许空元素
      IllegalArgumentException - 如果fromElement大于toElement；或者如果此集合本身具有受限范围，并且fromElement或toElement位于范围的边界之外

    • headSet

      SortedSet<E> headSet(E toElement)
      返回此集合部分元素的视图，这些元素严格小于toElement。返回的集合由此集合支持，因此返回集合中的更改会反映在此集合中，反之亦然。返回的集合支持此集合支持的所有可选集合操作。

      如果尝试在其范围之外插入元素，则返回的集合将抛出IllegalArgumentException。

      等效于headSet(toElement, false)。

      指定者：
      headSet 在接口 SortedSet<E>中
      参数：
      toElement - 返回集合的高端点（不包括）
      返回：
      小于toElement的此集合部分元素的视图
      抛出：
      ClassCastException - 如果toElement与此集合的比较器不兼容（或者，如果集合没有比较器，则toElement未实现Comparable）。如果toElement无法与集合中当前元素进行比较，则实现可能会但不是必须抛出此异常。
      NullPointerException - 如果toElement为null且此集合不允许空元素
      IllegalArgumentException - 如果此集合本身具有受限范围，并且toElement位于范围的边界之外

    • tailSet

      SortedSet<E> tailSet(E fromElement)
      返回该集合中元素大于或等于fromElement的部分的视图。返回的集合由该集合支持，因此返回集合中的更改会反映在该集合中，反之亦然。返回的集合支持该集合支持的所有可选集合操作。

      尝试插入超出范围的元素时，返回的集合将抛出IllegalArgumentException异常。

      等效于tailSet(fromElement, true)。

      指定者：
      tailSet 在接口 SortedSet<E>中
      参数：
      fromElement - 返回集合的低端点（包括）
      返回：
      返回该集合中元素大于或等于fromElement的部分的视图
      抛出：
      ClassCastException - 如果fromElement与该集合的比较器不兼容（或者，如果集合没有比较器，并且fromElement没有实现Comparable），则抛出此异常。如果fromElement无法与当前集合中的元素进行比较，实现可以但不是必须抛出此异常。
      NullPointerException - 如果fromElement为null且该集合不允许空元素
      IllegalArgumentException - 如果该集合本身具有受限范围，并且fromElement超出范围的边界

    • removeFirst

      default E removeFirst()
      移除并返回该集合的第一个元素（可选操作）。
      指定者：
      removeFirst 在接口 SequencedCollection<E>中
      指定者：
      removeFirst 在接口 SortedSet<E>中
      实现要求：
      如果该集合不为空，则该接口中的实现返回调用pollFirst方法的结果。否则，抛出NoSuchElementException。
      返回：
      被移除的元素
      抛出：
      NoSuchElementException - 如果该集合为空
      UnsupportedOperationException - 如果该集合实现不支持此操作
      自：
      21

    • removeLast

      default E removeLast()
      移除并返回该集合的最后一个元素（可选操作）。
      指定者：
      removeLast 在接口 SequencedCollection<E>中
      指定者：
      removeLast 在接口 SortedSet<E>中
      实现要求：
      如果该集合不为空，则该接口中的实现返回调用pollLast方法的结果。否则，抛出NoSuchElementException。
      返回：
      被移除的元素
      抛出：
      NoSuchElementException - 如果该集合为空
      UnsupportedOperationException - 如果该集合实现不支持此操作
      自：
      21

    • reversed

      default NavigableSet<E> reversed()
      返回该集合的逆序视图。返回视图中元素的遭遇顺序与该集合中元素的遭遇顺序相反。逆序排序会影响所有对顺序敏感的操作，包括对返回视图的视图集合的操作。如果集合实现允许修改此视图，则对底层集合的修改会“写入”到该视图。对底层集合的更改可能会或可能不会在此逆序视图中可见，这取决于实现。

      此方法等效于descendingSet。

      指定者：
      reversed 在接口 SequencedCollection<E>中
      指定者：
      reversed 在接口 SequencedSet<E>中
      指定者：
      reversed 在接口 SortedSet<E>中
      实现要求：
      该接口中的实现返回调用descendingSet方法的结果。
      返回：
      作为NavigableSet的该集合的逆序视图
      自：
      21