java容器 接口SortedMap源码分析

目录

简介

comparator

subMap,headMap,tailMap

firstKey,lastKey

keySet,values,entrySet

---

简介

/**
 * 进一步提供其键的总排序的映射。
 * 映射是根据其键的自然顺序排序的，或者由一个比较器(通常在已排序的映射创建时提供)来排序的。
 * 这种顺序反映在遍历已排序映射的集合视图(由entrySet、keySet和values方法返回)时。
 * 还提供了几个额外的操作来利用排序。(此接口是SortedSet的映射模拟。)
 *
 * 
插入到排序映射中的所有键必须实现Comparable接口(或者被指定的比较器接受)。
 * 而且，所有这些键必须是相互可比的:  k1. compareto (k2)(或comparator.compare(k1, k2))
 * 不能让任何键k1和k2抛出ClassCastException。
 * 试图违反此限制将导致违规的方法或构造函数调用抛出ClassCastException。
 *
 * 
注意，如果要正确地实现map接口，排序后的map所维护的顺序(不管是否提供了显式的比较器)必须与equals一致。
 * (参见Comparable接口或Comparator接口，以获得与equals一致的精确定义。)
 * 这是因为Map接口是根据equals操作定义的，但是一个排序后的Map使用它的compareTo(或compare)方法执行所有的键比较，
 * 所以从排序后的Map的角度来看，这个方法认为相等的两个键是相等的。
 * 树映射的行为是定义良好的，即使它的顺序与equals不一致;它只是没有遵守map接口的通用契约。
 *
 * 
所有通用的排序映射实现类都应该提供四个“标准”构造函数。
 * 虽然接口无法指定所需的构造函数，但不可能强制执行此建议。预期的“标准”构造函数为所有排序的映射实现:
 * 

 *   
一个void(无参数)构造函数，它创建一个按键的自然顺序排序的空排序映射。
 *   
一个只有一个比较器类型参数的构造函数，它创建一个根据指定的比较器排序的空的排序映射。
 *   
具有Map类型的单个参数的构造函数，该构造函数创建一个具有与其参数相同的键-值映射的新映射，并根据键的自然顺序进行排序。
 *   
带有SortedMap类型的单个参数的构造函数，它创建一个新的排序映射，具有与输入排序映射相同的键-值映射和相同的顺序。
 * 
 *
 * 
注意:有几个方法返回键范围受限的子映射。
 * 这些范围是半开的，也就是说，它们包括它们的低端点，但不包括它们的高端点(如果适用的话)。
 * 如果您需要一个闭合范围(包括两个端点)，并且key类型允许计算给定key的后继，那么只需请求子区间从lowEndpoint到successor(highEndpoint)。
 * 例如，假设m是一个映射，它的键是字符串。下面的习惯用法获得了一个视图，其中包含了m中所有的键值映射，其键值介于低和高之间，包括:
 *   SortedMap<String, V> sub = m.subMap(low, high+"\0");
 *
 * 可以使用类似的技术生成一个开放范围(其中不包含端点)。
 * 下面的习惯用法获得一个视图，该视图包含m中所有键值映射，其键值在低和高之间，并且是互斥的:
 *   SortedMap<String, V> sub = m.subMap(low+"\0", high);
 *
 *
 * @param  the type of keys maintained by this map
 * @param  the type of mapped values
 *
 * @author  Josh Bloch
 * @see Map
 * @see TreeMap
 * @see SortedSet
 * @see Comparator
 * @see Comparable
 * @see Collection
 * @see ClassCastException
 * @since 1.2
 */

public interface SortedMap extends Map

comparator

    /**
     * 返回用于对该映射中的键排序的比较器，如果该映射使用其键的自然排序，则返回null。
     *
     * @return the comparator used to order the keys in this map,
     *         or {@code null} if this map uses the natural ordering
     *         of its keys
     */
    Comparator comparator();

subMap,headMap,tailMap

    /**
     * 返回该映射的一部分的视图，其键的范围从fromKey(包含)到toKey(排除)。[from,to)
     * (如果fromKey和toKey相等，则返回的映射为空。)返回的映射得到此映射的支持，
     * 因此返回映射中的更改将反映在此映射中，反之亦然。返回的映射支持此映射支持的所有可选映射操作。
     *
     * 
返回的映射将在试图插入超出其范围的键时抛出IllegalArgumentException。
     *
     * @param fromKey low endpoint (inclusive) of the keys in the returned map
     * @param toKey high endpoint (exclusive) of the keys in the returned map
     * @return a view of the portion of this map whose keys range from
     *         {@code fromKey}, inclusive, to {@code toKey}, exclusive
     * @throws ClassCastException if {@code fromKey} and {@code toKey}
     *         cannot be compared to one another using this map's comparator
     *         (or, if the map has no comparator, using natural ordering).
     *         Implementations may, but are not required to, throw this
     *         exception if {@code fromKey} or {@code toKey}
     *         cannot be compared to keys currently in the map.
     * @throws NullPointerException if {@code fromKey} or {@code toKey}
     *         is null and this map does not permit null keys
     * @throws IllegalArgumentException if {@code fromKey} is greater than
     *         {@code toKey}; or if this map itself has a restricted
     *         range, and {@code fromKey} or {@code toKey} lies
     *         outside the bounds of the range
     */
    SortedMap subMap(K fromKey, K toKey);

    /**
     * 返回该映射中键值严格小于toKey的部分的视图。(-min,to)
     * 返回的映射得到此映射的支持，因此返回映射中的更改将反映在此映射中，反之亦然。返回的映射支持此映射支持的所有可选映射操作。
     *
     * 
返回的映射将在试图插入超出其范围的键时抛出IllegalArgumentException。
     *
     * @param toKey high endpoint (exclusive) of the keys in the returned map
     * @return a view of the portion of this map whose keys are strictly
     *         less than {@code toKey}
     * @throws ClassCastException if {@code toKey} is not compatible
     *         with this map's comparator (or, if the map has no comparator,
     *         if {@code toKey} does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if {@code toKey} cannot be compared to keys
     *         currently in the map.
     * @throws NullPointerException if {@code toKey} is null and
     *         this map does not permit null keys
     * @throws IllegalArgumentException if this map itself has a
     *         restricted range, and {@code toKey} lies outside the
     *         bounds of the range
     */
    SortedMap headMap(K toKey);

    /**
     * 返回键值大于或等于fromKey的那部分映射的视图。[from,max)
     * 返回的映射得到此映射的支持，因此返回映射中的更改将反映在此映射中，反之亦然。返回的映射支持此映射支持的所有可选映射操作。
     *
     * 
返回的映射将在试图插入超出其范围的键时抛出IllegalArgumentException。
     *
     * @param fromKey low endpoint (inclusive) of the keys in the returned map
     * @return a view of the portion of this map whose keys are greater
     *         than or equal to {@code fromKey}
     * @throws ClassCastException if {@code fromKey} is not compatible
     *         with this map's comparator (or, if the map has no comparator,
     *         if {@code fromKey} does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if {@code fromKey} cannot be compared to keys
     *         currently in the map.
     * @throws NullPointerException if {@code fromKey} is null and
     *         this map does not permit null keys
     * @throws IllegalArgumentException if this map itself has a
     *         restricted range, and {@code fromKey} lies outside the
     *         bounds of the range
     */
    SortedMap tailMap(K fromKey);

firstKey,lastKey

    /**
     * 返回当前映射中的第一个(最小的)键。
     *
     * @return the first (lowest) key currently in this map
     * @throws NoSuchElementException if this map is empty
     */
    K firstKey();

    /**
     * 返回当前映射中的最后一个(最大的)键。
     *
     * @return the last (highest) key currently in this map
     * @throws NoSuchElementException if this map is empty
     */
    K lastKey();

keySet,values,entrySet

    /**
     * 返回此映射中包含的键的集合视图。
     * 集合的迭代器按升序返回键。集合由映射支持，因此对映射的更改将反映在集合中，反之亦然。
     * 如果在对集合进行迭代时修改了映射(除了通过迭代器自己的删除操作)，则迭代的结果是未定义的。
     * 集合支持元素删除，它通过Iterator.remove, Set.remove, removeAll, retainAll and clear操作。它不支持add或addAll操作。
     *
     * @return a set view of the keys contained in this map, sorted in
     *         ascending order
     */
    Set keySet();

    /**
     * 返回此映射中包含的值的集合视图。
     * 集合的迭代器按相应键的升序返回值。集合由映射支持，因此对映射的更改反映在集合中，反之亦然。
     * 如果在集合的迭代过程中修改了映射(除了通过迭代器自己的删除操作)，则迭代的结果是未定义的。
     * 集合支持元素删除，它通过Iterator.remove, Set.remove, removeAll, retainAll and clear操作。它不支持add或addAll操作。
     *
     * @return a collection view of the values contained in this map,
     *         sorted in ascending key order
     */
    Collection values();

    /**
     * 返回此映射中包含的值的集合视图。
     * 集合的迭代器按相应键的升序返回值。集合由映射支持，因此对映射的更改反映在集合中，反之亦然。
     * 如果在集合的迭代过程中修改了映射(除了通过迭代器自己的删除操作)，则迭代的结果是未定义的。
     * 集合支持元素删除，它通过Iterator.remove, Set.remove, removeAll, retainAll and clear操作。它不支持add或addAll操作。
     *
     * @return a set view of the mappings contained in this map,
     *         sorted in ascending key order
     */
    Set> entrySet();