java容器 接口NavigableSet源码分析

目录

简介

​lower,floor,ceiling,higher,pollFirst,pollLast

iterator,descendingSet,descendingIterator

subSet,tailSet,headSet，各2个

---

简介

/**
 * SortedSet扩展了navigation方法，报告给定搜索目标的最接近匹配。
 * 方法分别返回小于、小于或等于、大于或等于和大于给定元素的低、下限、上限和高元素，如果没有这样的元素，则返回null。
 * 可按升序或降序访问和遍历NavigableSet。
 * 派生集方法返回集合的一个视图，该视图具有所有反向的关系和方向方法的意义。
 * 升序操作和视图的性能可能比降序操作和视图的性能更快。
 * 这个接口还定义了pollFirst和pollLast方法，它们返回并删除最低和最高的元素(如果有的话)，否则返回null。
 * 方法subSet、headSet和tailSet与类似名称的SortedSet方法不同，它们接受额外的参数，这些参数描述了下界和上界是包含的还是排他的。
 * 任何NavigableSet的子集都必须实现NavigableSet接口。
 *
 * 
在允许空元素的实现中，navigation方法的返回值可能是不明确的。
 * 但是，即使在这种情况下，也可以通过检查contains(null)消除歧义。
 * 为了避免此类问题，建议这个接口的实现不允许插入空元素。
 * (注意，可比较元素的排序集在本质上不允许为null。)
 *
 * 
方法subSet(E, E), headSet(E), and tailSet(E)被指定为返回SortedSet，
 * 以允许对SortedSet的现有实现进行兼容的改进以实现NavigableSet，
 * 但是这个接口的扩展和实现被鼓励重写这些方法以返回NavigableSet。
 *
 * @author Doug Lea
 * @author Josh Bloch
 * @param  the type of elements maintained by this set
 * @since 1.6
 */
public interface NavigableSet extends SortedSet 

lower,floor,ceiling,higher,pollFirst,pollLast

    /**
     * 返回这个集合中严格小于给定元素的最大元素，如果没有这样的元素，则返回null。
     *
     * @param e the value to match
     * @return the greatest element less than {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E lower(E e);

    /**
     * 返回这个集合中小于或等于给定元素的最大元素，如果没有这样的元素，则返回null。
     *
     * @param e the value to match
     * @return the greatest element less than or equal to {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E floor(E e);

    /**
     * 返回该集合中大于或等于给定元素的最小元素，如果没有这样的元素，则返回null。
     *
     * @param e the value to match
     * @return the least element greater than or equal to {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E ceiling(E e);

    /**
     * 返回该集合中严格大于给定元素的最小元素，如果没有这样的元素，则返回null。
     *
     * @param e the value to match
     * @return the least element greater than {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E higher(E e);

    /**
     * 检索并删除第一个(最低的)元素，如果该集合为空，则返回null。
     *
     * @return the first element, or {@code null} if this set is empty
     */
    E pollFirst();

    /**
     * 检索并删除最后一个(最高的)元素，如果该集合为空，则返回null。
     *
     * @return the last element, or {@code null} if this set is empty
     */
    E pollLast();

iterator,descendingSet,descendingIterator

    /**
     * 以升序返回该集合中元素的迭代器。
     *
     * @return an iterator over the elements in this set, in ascending order
     */
    Iterator iterator();

    /**
     * 返回该集合中所包含元素的逆序视图。
     * 降序集合由该集合支持，因此对该集合的更改将反映在降序集合中，反之亦然。
     * 如果任何一个集合在迭代过程中被修改(除了通过迭代器自己的删除操作)，迭代的结果都是未定义的。
     *
     * 
返回的集合的顺序相当于Collections.reverseOrder(comparator())。
     * 表达式s.descendingSet().descendingSet()返回一个本质上与s等价的s视图。
     *
     * @return a reverse order view of this set
     */
    NavigableSet descendingSet();

    /**
     * 按降序返回该集合中元素的迭代器。实际上等同于descendingSet().iterator()。
     *
     * @return an iterator over the elements in this set, in descending order
     */
    Iterator descendingIterator();

subSet,tailSet,headSet，各2个

    /**
     * 返回该集合中元素范围从fromElement到toElement的部分的视图。
     * 如果fromElement和toElement相等，则返回的集合为空，除非fromInclusive和toinclusion都为true。
     * 返回的集合由这个集合支持，所以返回的集合中的变化反映在这个集合中，反之亦然。
     * 返回的集合支持此集合支持的所有可选集合操作。
     *
     * 
返回的集合将在试图插入超出其范围的元素时抛出IllegalArgumentException。
     *
     * @param fromElement low endpoint of the returned set
     * @param fromInclusive {@code true} if the low endpoint
     *        is to be included in the returned view
     * @param toElement high endpoint of the returned set
     * @param toInclusive {@code true} if the high endpoint
     *        is to be included in the returned view
     * @return a view of the portion of this set whose elements range from
     *         {@code fromElement}, inclusive, to {@code toElement}, exclusive
     * @throws ClassCastException if {@code fromElement} and
     *         {@code toElement} cannot be compared to one another using this
     *         set's comparator (or, if the set has no comparator, using
     *         natural ordering).  Implementations may, but are not required
     *         to, throw this exception if {@code fromElement} or
     *         {@code toElement} cannot be compared to elements currently in
     *         the set.
     * @throws NullPointerException if {@code fromElement} or
     *         {@code toElement} is null and this set does
     *         not permit null elements
     * @throws IllegalArgumentException if {@code fromElement} is
     *         greater than {@code toElement}; or if this set itself
     *         has a restricted range, and {@code fromElement} or
     *         {@code toElement} lies outside the bounds of the range.
     */
    NavigableSet subSet(E fromElement, boolean fromInclusive,
                           E toElement,   boolean toInclusive);

    /**
     * 返回该集合中元素小于(或等于，如果包含为真)toElement部分的视图。
     * 返回的集合由这个集合支持，所以返回的集合中的变化反映在这个集合中，反之亦然。
     * 返回的集合支持此集合支持的所有可选集合操作。
     *
     * 
返回的集合将在试图插入超出其范围的元素时抛出IllegalArgumentException。
     *
     * @param toElement high endpoint of the returned set
     * @param inclusive {@code true} if the high endpoint
     *        is to be included in the returned view
     * @return a view of the portion of this set whose elements are less than
     *         (or equal to, if {@code inclusive} is true) {@code toElement}
     * @throws ClassCastException if {@code toElement} is not compatible
     *         with this set's comparator (or, if the set has no comparator,
     *         if {@code toElement} does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if {@code toElement} cannot be compared to elements
     *         currently in the set.
     * @throws NullPointerException if {@code toElement} is null and
     *         this set does not permit null elements
     * @throws IllegalArgumentException if this set itself has a
     *         restricted range, and {@code toElement} lies outside the
     *         bounds of the range
     */
    NavigableSet headSet(E toElement, boolean inclusive);

    /**
     * 返回该集合中元素大于(或等于，如果包含为真)fromElement部分的视图。
     * 返回的集合由这个集合支持，所以返回的集合中的变化反映在这个集合中，反之亦然。
     * 返回的集合支持此集合支持的所有可选集合操作。
     *
     * 
返回的集合将在试图插入超出其范围的元素时抛出IllegalArgumentException。
     *
     * @param fromElement low endpoint of the returned set
     * @param inclusive {@code true} if the low endpoint
     *        is to be included in the returned view
     * @return a view of the portion of this set whose elements are greater
     *         than or equal to {@code fromElement}
     * @throws ClassCastException if {@code fromElement} is not compatible
     *         with this set's comparator (or, if the set has no comparator,
     *         if {@code fromElement} does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if {@code fromElement} cannot be compared to elements
     *         currently in the set.
     * @throws NullPointerException if {@code fromElement} is null
     *         and this set does not permit null elements
     * @throws IllegalArgumentException if this set itself has a
     *         restricted range, and {@code fromElement} lies outside the
     *         bounds of the range
     */
    NavigableSet tailSet(E fromElement, boolean inclusive);

    /**
     * {@inheritDoc}
     *
     * 
等于 {@code subSet(fromElement, true, toElement, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    SortedSet subSet(E fromElement, E toElement);

    /**
     * {@inheritDoc}
     *
     * 
等于 {@code headSet(toElement, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    SortedSet headSet(E toElement);

    /**
     * {@inheritDoc}
     *
     * 
等于 {@code tailSet(fromElement, true)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    SortedSet tailSet(E fromElement);