java.util
接口 NavigableSet<E>

类型参数：

E - 此 set 维护的元素类型

所有超级接口：

Collection<E>, Iterable<E>, Set<E>, SortedSet<E>

所有已知实现类：

ConcurrentSkipListSet, TreeSet

public interface NavigableSet<E>
extends SortedSet<E>

扩展的 SortedSet，具有了为给定搜索目标报告最接近匹配项的导航方法。方法 lower、floor、ceiling 和 higher 分别返回小于、小于等于、大于等于、大于给定元素的元素，如果不存在这样的元素，则返回 null。可以按升序或降序访问和遍历 NavigableSet。descendingSet 方法返回 set 的一个视图，该视图表示的所有关系方法和方向方法都是逆向的。升序操作和视图的性能很可能比降序操作和视图的性能要好。此外，此接口还定义了 pollFirst 和 pollLast 方法，它们返回并移除最小和最大的元素（如果存在），否则返回 null。subSet、headSet 和 tailSet 方法与名称相似的 SortedSet 方法的不同之处在于：可以接受用于描述是否包括（或不包括）下边界和上边界的附加参数。任何 NavigableSet 的 Submap 必须实现 NavigableSet 接口。

导航方法的返回值在允许 null 元素的实现中可能是不确定的。不过，即使在这种情况下，也可以通过检查 contains(null) 来明确结果。为了避免这样的问题，建议在此接口的实现中不 允许插入 null 元素。（注意，Comparable 元素的有序集本身不允许 null。）

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

此接口是 Java Collections Framework 的成员。

从以下版本开始：

1.6

方法摘要

E	ceiling(E e) 返回此 set 中大于等于给定元素的最小元素；如果不存在这样的元素，则返回 null。
Iterator<E>	descendingIterator() 以降序返回在此 set 的元素上进行迭代的迭代器。
NavigableSet<E>	descendingSet() 返回此 set 中所包含元素的逆序视图。
E	floor(E e) 返回此 set 中小于等于给定元素的最大元素；如果不存在这样的元素，则返回 null。
SortedSet<E>	headSet(E toElement) 返回此 set 的部分视图，其元素严格小于 toElement。
NavigableSet<E>	headSet(E toElement, boolean inclusive) 返回此 set 的部分视图，其元素小于（或等于，如果 inclusive 为 true）toElement。
E	higher(E e) 返回此 set 中严格大于给定元素的最小元素；如果不存在这样的元素，则返回 null。
Iterator<E>	iterator() 以升序返回在此 set 的元素上进行迭代的迭代器。
E	lower(E e) 返回此 set 中严格小于给定元素的最大元素；如果不存在这样的元素，则返回 null。
E	pollFirst() 获取并移除第一个（最低）元素；如果此 set 为空，则返回 null。
E	pollLast() 获取并移除最后一个（最高）元素；如果此 set 为空，则返回 null。
NavigableSet<E>	subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) 返回此 set 的部分视图，其元素范围从 fromElement 到 toElement。
SortedSet<E>	subSet(E fromElement, E toElement) 返回此 set 的部分视图，其元素从 fromElement（包括）到 toElement（不包括）。
SortedSet<E>	tailSet(E fromElement) 返回此 set 的部分视图，其元素大于等于 fromElement。
NavigableSet<E>	tailSet(E fromElement, boolean inclusive) 返回此 set 的部分视图，其元素大于（或等于，如果 inclusive 为 true）fromElement。

从接口 java.util.SortedSet 继承的方法

comparator, first, last

从接口 java.util.Set 继承的方法

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, size, toArray, toArray

方法详细信息

lower

E lower(E e)

返回此 set 中严格小于给定元素的最大元素；如果不存在这样的元素，则返回 null。

参数：

e - 要匹配的值

返回：

小于 e 的最大元素；如果不存在这样的元素，则返回 null

抛出：

ClassCastException - 如果指定元素不能与 set 中的当前元素进行比较

NullPointerException - 如果指定元素为 null 并且此 set 不允许 null 元素

floor

E floor(E e)

返回此 set 中小于等于给定元素的最大元素；如果不存在这样的元素，则返回 null。

参数：

e - 要匹配的值

返回：

小于等于 e 的最大元素；如果不存在这样的元素，则返回 null

抛出：

ClassCastException - 如果指定元素不能与 set 中的当前元素进行比较

NullPointerException - 如果指定元素为 null 并且此 set 不允许 null 元素

ceiling

E ceiling(E e)

返回此 set 中大于等于给定元素的最小元素；如果不存在这样的元素，则返回 null。

参数：

e - 要匹配的值

返回：

大于等于 e 的最小元素；如果不存在这样的元素，则返回 null

抛出：

ClassCastException - 如果指定元素不能与 set 中的当前元素进行比较

NullPointerException - 如果指定元素为 null 并且此 set 不允许 null 元素

higher

E higher(E e)

返回此 set 中严格大于给定元素的最小元素；如果不存在这样的元素，则返回 null。

参数：

e - 要匹配的值

返回：

大于 e 的最小元素；如果不存在这样的元素，则返回 null

抛出：

ClassCastException - 如果指定元素不能与 set 中的当前元素进行比较

NullPointerException - 如果指定元素为 null 并且此 set 不允许 null 元素

pollFirst

E pollFirst()

获取并移除第一个（最低）元素；如果此 set 为空，则返回 null。

返回：

第一个元素；如果此 set 为空，则返回 null

pollLast

E pollLast()

获取并移除最后一个（最高）元素；如果此 set 为空，则返回 null。

返回：

最后一个元素；如果此 set 为空，则返回 null

iterator

Iterator<E> iterator()

以升序返回在此 set 的元素上进行迭代的迭代器。

指定者：

接口 Collection<E> 中的 iterator

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Set<E> 中的 iterator

返回：

以升序返回在此 set 的元素上进行迭代的迭代器

descendingSet

NavigableSet<E> descendingSet()

返回此 set 中所包含元素的逆序视图。降序 set 受此 set 的支持，因此对此 set 的更改将反映在降序 set 中，反之亦然。如果在对任一 set 进行迭代的同时修改了任一 set（通过迭代器自己的 remove 操作除外），则迭代结果是不确定的。

返回 set 的顺序等于 Collections.reverseOrder(comparator())。表达式 s.descendingSet().descendingSet() 返回的 s 视图基本等于 s。

返回：

此 set 的逆序视图

descendingIterator

Iterator<E> descendingIterator()

以降序返回在此 set 的元素上进行迭代的迭代器。效果等同于 descendingSet().iterator()。

返回：

在此 set 的元素上以降序进行迭代的迭代器

subSet

NavigableSet<E> subSet(E fromElement,
                       boolean fromInclusive,
                       E toElement,
                       boolean toInclusive)

返回此 set 的部分视图，其元素范围从 fromElement 到 toElement。如果 fromElement 和 toElement 相等，则返回的 set 为空，除非 fromExclusive 和 toExclusive 都为 true。返回的 set 受此 set 支持，所以在返回 set 中的更改将反映在此 set 中，反之亦然。返回 set 支持此 set 支持的所有可选 set 操作。

如果试图在返回 set 的范围之外插入元素，则返回的 set 将抛出 IllegalArgumentException。

参数：

fromElement - 返回 set 的低端点

fromInclusive - 如果低端点要包含在返回的视图中，则为 true

toElement - 返回 set 的高端点

toInclusive - 如果高端点要包含在返回的视图中，则为 true

返回：

此 set 的部分视图，其元素范围从 fromElement（包括）到 toElement（不包括）

抛出：

ClassCastException - 如果不能使用此 set 的比较器或者使用自然顺序（如果 set 没有比较器）比较 fromElement 和 toElement。如果 fromElement 或 toElement 不能与 set 中的当前元素进行比较，则实现可以（但不是必须）抛出此异常。

NullPointerException - 如果 fromElement 或 toElement 为 null 并且此 set 不允许 null 元素

IllegalArgumentException - 如果 fromElement 大于 toElement；如果此 set 本身有范围限制，并且 fromElement 或 toElement 位于范围的边界之外。

headSet

NavigableSet<E> headSet(E toElement,
                        boolean inclusive)

返回此 set 的部分视图，其元素小于（或等于，如果 inclusive 为 true）toElement。返回的 set 受此 set 支持，所以在返回 set 中的更改将反映在此 set 中，反之亦然。返回 set 支持此 set 支持的所有可选 set 操作。

如果试图在返回 set 的范围之外插入元素，则返回的 set 将抛出 IllegalArgumentException。

参数：

toElement - 返回 set 的高端点

inclusive - 如果高端点要包含在返回的视图中，则为 true

返回：

此 set 的部分视图，其元素小于（或等于，如果 inclusive 为 true）toElement

抛出：

ClassCastException - 如果 toElement 与此 set 的比较器不兼容（如果 set 没有比较器；如果 toElement 没有实现 Comparable）。如果 toElement 不能与 set 中的当前元素进行比较，则实现可以（但不是必须）抛出此异常。

NullPointerException - 如果 toElement 为 null 并且此 set 不允许 null 元素

IllegalArgumentException - 如果此 set 本身有范围限制，并且 toElement 位于范围的边界之外

tailSet

NavigableSet<E> tailSet(E fromElement,
                        boolean inclusive)

返回此 set 的部分视图，其元素大于（或等于，如果 inclusive 为 true）fromElement。返回的 set 受此 set 支持，所以在返回 set 中的更改将反映在此 set 中，反之亦然。返回 set 支持此 set 支持的所有可选 set 操作。

如果试图在返回 set 的范围之外插入元素，则返回的 set 将抛出 IllegalArgumentException。

参数：

fromElement - 返回 set 的低端点

inclusive - 如果低端点要包含在返回的视图中，则为 true

返回：

此 set 的部分视图，其元素大于等于 fromElement

抛出：

ClassCastException - 如果 fromElement 与此 set 的比较器不兼容（如果 set 没有任何比较器；如果 fromElement 没有实现 Comparable）。如果 fromElement 不能与 set 中的当前元素进行比较，则实现可以（但不是必须）抛出此异常。

NullPointerException - 如果 fromElement 为 null 并且此 set 不允许 null 元素

IllegalArgumentException - 如果此 set 本身有范围限制，并且 fromElement 位于范围的边界之外

subSet

SortedSet<E> subSet(E fromElement,
                    E toElement)

返回此 set 的部分视图，其元素从 fromElement（包括）到 toElement（不包括）。（如果 fromElement 和 toElement 相等，则返回空的 set）。返回的 set 受此 set 支持，所以在返回 set 中的更改将反映在此 set 中，反之亦然。返回的 set 支持此 set 支持的所有可选 set 操作。

如果试图在返回 set 的范围之外插入元素，则返回的 set 将抛出 IllegalArgumentException。

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

指定者：

接口 SortedSet<E> 中的 subSet

参数：

fromElement - 返回 set 的低端点（包括）

toElement - 返回 set 的高端点（不包括）

返回：

此 set 的部分视图，其元素的范围从 fromElement（包括）到 toElement（不包括）

抛出：

ClassCastException - 如果无法使用此 set 的比较器（如果 set 没有比较器，则使用自然顺序）比较 fromElement 和 toElement。如果 fromElement 或 toElement 不能与 set 中的当前元素进行比较，则实现可以（但不是必须）抛出此异常。

NullPointerException - 如果 fromElement 或 toElement 为 null，并且此 set 不允许 null 元素

IllegalArgumentException - 如果 fromElement 大于 toElement；如果此 set 本身有范围限制，并且 fromElement 或 toElement 位于范围的边界之外

headSet

SortedSet<E> headSet(E toElement)

返回此 set 的部分视图，其元素严格小于 toElement。返回的 set 受此 set 支持，所以在返回 set 中的更改将反映在此 set 中，反之亦然。返回的 set 支持此 set 支持的所有可选 set 操作。

如果试图在返回 set 的范围之外插入元素，则返回的 set 将抛出 IllegalArgumentException。

等效于 headSet(toElement, false)。

指定者：

接口 SortedSet<E> 中的 headSet

参数：

toElement - 返回 set 的高端点（不包括）

返回：

此 set 的部分视图，其元素严格小于 toElement

抛出：

ClassCastException - 如果 toElement 与此 set 的比较器不兼容（如果 set 没有比较器；如果 toElement 没有实现 Comparable）。如果 toElement 不能与 set 中的当前元素进行比较，则实现可以（但不是必须）抛出此异常。

NullPointerException - 如果 toElement 为 null，并且此 set 不允许 null 元素

IllegalArgumentException - 如果此 set 本身有范围限制，并且 toElement 位于范围的边界之外

tailSet

SortedSet<E> tailSet(E fromElement)

返回此 set 的部分视图，其元素大于等于 fromElement。返回的 set 受此 set 支持，所以在返回 set 中的更改将反映在此 set 中，反之亦然。返回的 set 支持此 set 支持的所有可选 set 操作。

如果试图在返回 set 的范围之外插入元素，则返回的 set 将抛出 IllegalArgumentException。

等效于 tailSet(fromElement, true)。

指定者：

接口 SortedSet<E> 中的 tailSet

参数：

fromElement - 返回 set 的低端点（包括）

返回：

此 set 的部分视图，其元素大于等于 fromElement

抛出：

ClassCastException - 如果 fromElement 与此 set 的比较器不兼容（如果 set 没有比较器；如果 fromElement 没有实现 Comparable）。如果 fromElement 不能与 set 中的当前元素进行比较，则实现可以（但不是必须）抛出此异常。

NullPointerException - 如果 fromElement 为 null，并且此 set 不允许 null 元素

IllegalArgumentException - 如果此 set 本身有范围限制，并且 fromElement 位于范围的边界之外