JavaTM 2 Platform
Standard Ed. 6

java.util
接口 SortedMap<K,V>

类型参数:
K - 此映射所维护的键的类型
V - 映射值的类型
所有超级接口:
Map<K,V>
所有已知子接口:
ConcurrentNavigableMap<K,V>, NavigableMap<K,V>
所有已知实现类:
ConcurrentSkipListMap, TreeMap

public interface SortedMap<K,V>
extends Map<K,V>

进一步提供关于键的总体排序Map。该映射是根据其键的自然顺序进行排序的,或者根据通常在创建有序映射时提供的 Comparator 进行排序。对有序映射的 collection 视图(由 entrySetkeySetvalues 方法返回)进行迭代时,此顺序就会反映出来。要采用此排序方式,还需要提供一些其他操作(此接口是 SortedSet 的对应映射)。

插入有序映射的所有键都必须实现 Comparable 接口(或者被指定的比较器接受)。另外,所有这些键都必须是可互相比较的:对有序映射中的任意两个键 k1k2 执行 k1.compareTo(k2)(或 comparator.compare(k1, k2))都不得抛出 ClassCastException。试图违反此限制将导致违反规则的方法或者构造方法调用抛出 ClassCastException

注意,如果有序映射要正确实现 Map 接口,则有序映射所维持的顺序(无论是否提供了明确的比较器)都必须与 equals 一致。(有关与 equals 一致 的精确定义,请参阅 Comparable 接口或 Comparator 接口)。这是因为 Map 接口是按照 equals 操作定义的,但有序映射使用它的 compareTo(或 compare)方法对所有键进行比较,因此从有序映射的角度来看,此方法认为相等的两个键就是相等的。即使顺序与 equals 不一致,树映射的行为仍然 定义良好的,只不过没有遵守 Map 接口的常规协定。

所有通用有序映射实现类都应该提供 4 个“标准”构造方法:1) void(无参数)构造方法,它创建一个空的有序映射,按照键的自然顺序进行排序。2) 带有一个 Comparator 类型参数的构造方法,它创建一个空的有序映射,根据指定的比较器进行排序。3) 带有一个 Map 类型参数的构造方法,它创建一个新的有序映射,其键-值映射关系与参数相同,按照键的自然顺序进行排序。4) 带有一个 SortedMap 类型参数的构造方法,它创建一个新的有序映射,其键-值映射关系和排序方法与输入的有序映射相同。无法保证强制实施此建议,因为接口不能包含构造方法。

注:一些方法返回具有受限键范围的子映射。这些范围区间是半开的,也就是说,它们包括低端点,但不包括高端点(如果适用)。如果需要一个闭区间(同时包括两个端点),且键类型允许计算给定键值的后继值,则只需要请求从 lowEndpointsuccessor(highEndpoint) 的子区间。例如,假设 m 是一个用字符串作为键的映射。下面的语句将得到一个包含 m 中键在 lowhigh(包括)之间的所有键-值映射关系的视图:

   SortedMap<String, V> sub = m.subMap(low, high+"\0");
可使用类似的技术生成一个开区间 (两个端点都不包括)。下面的语句将得到一个包含 m 中键在 lowhigh(不包括)之间的所有键-值映射关系的视图:
   SortedMap<String, V> sub = m.subMap(low+"\0", high);

此接口是 Java Collections Framework 的成员。

从以下版本开始:
1.2
另请参见:
Map, TreeMap, SortedSet, Comparator, Comparable, Collection, ClassCastException

嵌套类摘要
 
从接口 java.util.Map 继承的嵌套类/接口
Map.Entry<K,V>
 
方法摘要
 Comparator<? super K> comparator()
          返回对此映射中的键进行排序的比较器;如果此映射使用键的自然顺序,则返回 null
 Set<Map.Entry<K,V>> entrySet()
          返回在此映射中包含的映射关系的 Set 视图。
 K firstKey()
          返回此映射中当前第一个(最低)键。
 SortedMap<K,V> headMap(K toKey)
          返回此映射的部分视图,其键值严格小于 toKey
 Set<K> keySet()
          返回在此映射中所包含键的 Set 视图。
 K lastKey()
          返回映射中当前最后一个(最高)键。
 SortedMap<K,V> subMap(K fromKey, K toKey)
          返回此映射的部分视图,其键值的范围从 fromKey(包括)到 toKey(不包括)。
 SortedMap<K,V> tailMap(K fromKey)
          返回此映射的部分视图,其键大于等于 fromKey
 Collection<V> values()
          返回在此映射中所包含值的 Collection 视图。
 
从接口 java.util.Map 继承的方法
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, put, putAll, remove, size
 

方法详细信息

comparator

Comparator<? super K> comparator()
返回对此映射中的键进行排序的比较器;如果此映射使用键的自然顺序,则返回 null

返回:
用来对此映射中的键进行排序的比较器;如果此映射使用键的自然顺序,则返回 null

subMap

SortedMap<K,V> subMap(K fromKey,
                      K toKey)
返回此映射的部分视图,其键值的范围从 fromKey(包括)到 toKey(不包括)。(如果 fromKeytoKey 相等,则返回映射为空。)返回的映射受此映射支持,所以在返回映射中的更改将反映在此映射中,反之亦然。返回的映射支持此映射支持的所有可选映射操作。

如果试图在返回映射的范围之外插入键,则返回的映射将抛出 IllegalArgumentException

参数:
fromKey - 返回映射中键的低端点(包括)
toKey - 返回映射中键的高端点(不包括)
返回:
此映射的部分视图,其键值的范围从 fromKey(包括)到 toKey(不包括)
抛出:
ClassCastException - 如果无法使用此映射的比较器(如果此映射没有比较器,则使用自然顺序)比较 fromKeytoKey。如果 fromKeytoKey 不能与映射中当前键进行比较,则实现可以(但不是必须)抛出此异常。
NullPointerException - 如果 fromKeytoKey 为 null,并且此映射不允许使用 null 键
IllegalArgumentException - 如果 fromKey 大于 toKey;如果此映射本身有范围限制,并且 fromKeytoKey 位于范围的边界之外

headMap

SortedMap<K,V> headMap(K toKey)
返回此映射的部分视图,其键值严格小于 toKey。返回的映射受此映射支持,所以在返回映射中的更改将反映在映射中,反之亦然。返回的映射支持此映射支持的所有可选映射操作。

如果试图在返回映射的范围之外插入键,则返回的映射将抛出 IllegalArgumentException

参数:
toKey - 返回映射中键的高端点(不包括)
返回:
此映射的部分视图,该映射的键严格小于 toKey
抛出:
ClassCastException - 如果 toKey 与此映射的比较器不兼容(如果该映射没有比较器;如果 toKey 没有实现 Comparable)。如果 toKey 不能与映射中的当前键进行比较,则实现可以(但不是必须)抛出此异常。
NullPointerException - 如果 toKey 为 null,并且此映射不允许使用 null 键
IllegalArgumentException - 如果此映射本身有范围限制,并且 toKey 位于范围的边界之外

tailMap

SortedMap<K,V> tailMap(K fromKey)
返回此映射的部分视图,其键大于等于 fromKey。返回的映射受此映射支持,所以在返回映射中的更改将反映在映射中,反之亦然。返回的映射支持此映射支持的所有可选映射操作。

如果试图在返回映射的范围之外插入键,则返回的映射将抛出 IllegalArgumentException

参数:
fromKey - 返回映射中键的低端点(包括)
返回:
此映射的部分视图,其键大于等于 fromKey
抛出:
ClassCastException - 如果 fromKey 与此映射的比较器不兼容(如果该映射没有比较器;如果 fromKey 没有实现 Comparable)。如果 fromKey 不能与映射中的当前键进行比较,则实现可以(但不是必须)抛出此异常。
NullPointerException - 如果 fromKey 为 null,并且此映射不允许使用 null 键
IllegalArgumentException - 如果此映射本身有范围限制,并且 fromKey 位于范围的边界之外

firstKey

K firstKey()
返回此映射中当前第一个(最低)键。

返回:
此映射中当前第一个(最低)键
抛出:
NoSuchElementException - 如果此映射为空

lastKey

K lastKey()
返回映射中当前最后一个(最高)键。

返回:
此映射中当前最后一个(最高)键
抛出:
NoSuchElementException - 如果此映射为空

keySet

Set<K> keySet()
返回在此映射中所包含键的 Set 视图。该 set 的迭代器将按升序返回这些键。该 set 受映射支持,所以对映射的更改将反映在此 set 中,反之亦然。如果对该 set 进行迭代的同时修改了映射(通过迭代器自己的 remove 操作除外),则迭代结果是不确定的。此 set 支持元素移除,通过 Iterator.removeSet.removeremoveAllretainAllclear 操作可从映射中移除相应的映射关系。它不支持 addaddAll 操作。

指定者:
接口 Map<K,V> 中的 keySet
返回:
此映射所包含的键的 set 视图,按升序排序

values

Collection<V> values()
返回在此映射中所包含值的 Collection 视图。该 collection 的迭代器将按对应键的升序返回这些值。该 collection 受映射支持,所以对映射的更改将反映在此 collection 中,反之亦然。如果对该 set 进行迭代的同时修改了映射(通过迭代器自己的 remove 操作除外),则迭代结果是不确定的。该 collection 支持元素的移除,通过 Iterator.removeCollection.removeremoveAllretainAllclear 操作可从映射中移除相应的映射关系。它不支持 addaddAll 操作。

指定者:
接口 Map<K,V> 中的 values
返回:
此映射所包含的值的 collection 视图,按升序排序

entrySet

Set<Map.Entry<K,V>> entrySet()
返回在此映射中包含的映射关系的 Set 视图。该 set 的迭代器将按升序键顺序返回这些条目。该 set 受映射支持,所以对映射的更改将反映在此 set 中,反之亦然。如果修改映射的同时正在对该 set 进行迭代(除了通过迭代器自己的 remove 操作,或者通过在迭代器返回的映射项上执行 setValue 操作外),则迭代结果是不确定的。此 set 支持元素移除,通过 Iterator.removeSet.removeremoveAllretainAllclear 操作可从映射中移除相应的映射关系。它不支持 addaddAll 操作。

指定者:
接口 Map<K,V> 中的 entrySet
返回:
此映射所包含的映射关系的 set 视图,按升序键排序

JavaTM 2 Platform
Standard Ed. 6

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

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