JavaTM Platform
Standard Ed. 6

java.util
接口 NavigableSet<E>

类型参数:
E - 此 set 维护的元素类型
所有超级接口:
Collection<E>, Iterable<E>, Set<E>, SortedSet<E>
所有已知实现类:
ConcurrentSkipListSet, TreeSet

public interface NavigableSet<E>
     
extends SortedSet<E>

扩展的 SortedSet,具有了为给定搜索目标报告最接近匹配项的导航方法。方法 lowerfloorceilinghigher 分别返回小于、小于等于、大于等于、大于给定元素的元素,如果不存在这样的元素,则返回 null。可以按升序或降序访问和遍历 NavigableSetdescendingSet 方法返回 set 的一个视图,该视图表示的所有关系方法和方向方法都是逆向的。升序操作和视图的性能很可能比降序操作和视图的性能要好。此外,此接口还定义了 pollFirstpollLast 方法,它们返回并移除最小和最大的元素(如果存在),否则返回 nullsubSetheadSettailSet 方法与名称相似的 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 的部分视图,其元素范围从 fromElementtoElement
 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 的部分视图,其元素范围从 fromElementtoElement。如果 fromElementtoElement 相等,则返回的 set 为空,除非 fromExclusivetoExclusive 都为 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 没有比较器)比较 fromElementtoElement。如果 fromElementtoElement 不能与 set 中的当前元素进行比较,则实现可以(但不是必须)抛出此异常。
NullPointerException - 如果 fromElementtoElement 为 null 并且此 set 不允许 null 元素
IllegalArgumentException - 如果 fromElement 大于 toElement;如果此 set 本身有范围限制,并且 fromElementtoElement 位于范围的边界之外。

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(不包括)。(如果 fromElementtoElement 相等,则返回空的 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 没有比较器,则使用自然顺序)比较 fromElementtoElement。如果 fromElementtoElement 不能与 set 中的当前元素进行比较,则实现可以(但不是必须)抛出此异常。
NullPointerException - 如果 fromElementtoElement 为 null,并且此 set 不允许 null 元素
IllegalArgumentException - 如果 fromElement 大于 toElement;如果此 set 本身有范围限制,并且 fromElementtoElement 位于范围的边界之外

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

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

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