JavaTM Platform
Standard Ed. 6

java.util
类 HashMap<K,V>

java.lang.Object
  继承者 java.util.AbstractMap<K,V>
      继承者 java.util.HashMap<K,V>
类型参数:
K - 此映射所维护的键的类型
V - 所映射值的类型
所有已实现的接口:
Serializable, Cloneable, Map<K,V>
直接已知子类:
LinkedHashMap, PrinterStateReasons

public class HashMap<K,V>
extends AbstractMap<K,V>
implements Map<K,V>, Cloneable, Serializable

基于哈希表的 Map 接口的实现。此实现提供所有可选的映射操作,并允许使用 null 值和 null 键。(除了非同步和允许使用 null 之外,HashMap 类与 Hashtable 大致相同。)此类不保证映射的顺序,特别是它不保证该顺序恒久不变。

此实现假定哈希函数将元素适当地分布在各桶之间,可为基本操作(getput)提供稳定的性能。迭代 collection 视图所需的时间与 HashMap 实例的“容量”(桶的数量)及其大小(键-值映射关系数)成比例。所以,如果迭代性能很重要,则不要将初始容量设置得太高(或将加载因子设置得太低)。

HashMap 的实例有两个参数影响其性能:初始容量加载因子容量 是哈希表中桶的数量,初始容量只是哈希表在创建时的容量。加载因子 是哈希表在其容量自动增加之前可以达到多满的一种尺度。当哈希表中的条目数超出了加载因子与当前容量的乘积时,则要对该哈希表进行 rehash 操作(即重建内部数据结构),从而哈希表将具有大约两倍的桶数。

通常,默认加载因子 (.75) 在时间和空间成本上寻求一种折衷。加载因子过高虽然减少了空间开销,但同时也增加了查询成本(在大多数 HashMap 类的操作中,包括 getput 操作,都反映了这一点)。在设置初始容量时应该考虑到映射中所需的条目数及其加载因子,以便最大限度地减少 rehash 操作次数。如果初始容量大于最大条目数除以加载因子,则不会发生 rehash 操作。

如果很多映射关系要存储在 HashMap 实例中,则相对于按需执行自动的 rehash 操作以增大表的容量来说,使用足够大的初始容量创建它将使得映射关系能更有效地存储。

注意,此实现不是同步的。如果多个线程同时访问一个哈希映射,而其中至少一个线程从结构上修改了该映射,则它必须 保持外部同步。(结构上的修改是指添加或删除一个或多个映射关系的任何操作;仅改变与实例已经包含的键关联的值不是结构上的修改。)这一般通过对自然封装该映射的对象进行同步操作来完成。如果不存在这样的对象,则应该使用 Collections.synchronizedMap 方法来“包装”该映射。最好在创建时完成这一操作,以防止对映射进行意外的非同步访问,如下所示:

   Map m = Collections.synchronizedMap(new HashMap(...));

由所有此类的“collection 视图方法”所返回的迭代器都是快速失败 的:在迭代器创建之后,如果从结构上对映射进行修改,除非通过迭代器本身的 remove 方法,其他任何时间任何方式的修改,迭代器都将抛出 ConcurrentModificationException。因此,面对并发的修改,迭代器很快就会完全失败,而不冒在将来不确定的时间发生任意不确定行为的风险。

注意,迭代器的快速失败行为不能得到保证,一般来说,存在非同步的并发修改时,不可能作出任何坚决的保证。快速失败迭代器尽最大努力抛出 ConcurrentModificationException。因此,编写依赖于此异常的程序的做法是错误的,正确做法是:迭代器的快速失败行为应该仅用于检测程序错误。

此类是 Java Collections Framework 的成员。

从以下版本开始:
1.2
另请参见:
Object.hashCode(), Collection, Map, TreeMap, Hashtable, 序列化表格

嵌套类摘要
 
从类 java.util.AbstractMap 继承的嵌套类/接口
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>
 
构造方法摘要
HashMap()
          构造一个具有默认初始容量 (16) 和默认加载因子 (0.75) 的空 HashMap
HashMap(int initialCapacity)
          构造一个带指定初始容量和默认加载因子 (0.75) 的空 HashMap
HashMap(int initialCapacity, float loadFactor)
          构造一个带指定初始容量和加载因子的空 HashMap
HashMap(Map<? extends K,? extends V> m)
          构造一个映射关系与指定 Map 相同的新 HashMap
 
方法摘要
 void clear()
          从此映射中移除所有映射关系。
 Object clone()
          返回此 HashMap 实例的浅表副本:并不复制键和值本身。
 boolean containsKey(Object key)
          如果此映射包含对于指定键的映射关系,则返回 true
 boolean containsValue(Object value)
          如果此映射将一个或多个键映射到指定值,则返回 true
 Set<Map.Entry<K,V>> entrySet()
          返回此映射所包含的映射关系的 Set 视图。
 V get(Object key)
          返回指定键所映射的值;如果对于该键来说,此映射不包含任何映射关系,则返回 null
 boolean isEmpty()
          如果此映射不包含键-值映射关系,则返回 true
 Set<K> keySet()
          返回此映射中所包含的键的 Set 视图。
 V put(K key, V value)
          在此映射中关联指定值与指定键。
 void putAll(Map<? extends K,? extends V> m)
          将指定映射的所有映射关系复制到此映射中,这些映射关系将替换此映射目前针对指定映射中所有键的所有映射关系。
 V remove(Object key)
          从此映射中移除指定键的映射关系(如果存在)。
 int size()
          返回此映射中的键-值映射关系数。
 Collection<V> values()
          返回此映射所包含的值的 Collection 视图。
 
从类 java.util.AbstractMap 继承的方法
equals, hashCode, toString
 
从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, wait, wait, wait
 
从接口 java.util.Map 继承的方法
equals, hashCode
 

构造方法详细信息

HashMap

public HashMap(int initialCapacity,
               float loadFactor)
构造一个带指定初始容量和加载因子的空 HashMap

参数:
initialCapacity - 初始容量
loadFactor - 加载因子
抛出:
IllegalArgumentException - 如果初始容量为负或者加载因子为非正

HashMap

public HashMap(int initialCapacity)
构造一个带指定初始容量和默认加载因子 (0.75) 的空 HashMap

参数:
initialCapacity - 初始容量。
抛出:
IllegalArgumentException - 如果初始容量为负。

HashMap

public HashMap()
构造一个具有默认初始容量 (16) 和默认加载因子 (0.75) 的空 HashMap


HashMap

public HashMap(Map<? extends K,? extends V> m)
构造一个映射关系与指定 Map 相同的新 HashMap。所创建的 HashMap 具有默认加载因子 (0.75) 和足以容纳指定 Map 中映射关系的初始容量。

参数:
m - 映射,其映射关系将存放在此映射中
抛出:
NullPointerException - 如果指定的映射为 null
方法详细信息

size

public int size()
返回此映射中的键-值映射关系数。

指定者:
接口 Map<K,V> 中的 size
覆盖:
AbstractMap<K,V> 中的 size
返回:
此映射中的键-值映射关系数

isEmpty

public boolean isEmpty()
如果此映射不包含键-值映射关系,则返回 true

指定者:
接口 Map<K,V> 中的 isEmpty
覆盖:
AbstractMap<K,V> 中的 isEmpty
返回:
如果此映射不包含键-值映射关系,则返回 true

get

public V get(Object key)
返回指定键所映射的值;如果对于该键来说,此映射不包含任何映射关系,则返回 null

更确切地讲,如果此映射包含一个满足 (key==null ? k==null : key.equals(k)) 的从 k 键到 v 值的映射关系,则此方法返回 v;否则返回 null。(最多只能有一个这样的映射关系。)

返回 null 值并不一定 表明该映射不包含该键的映射关系;也可能该映射将该键显示地映射为 null。可使用 containsKey 操作来区分这两种情况。

指定者:
接口 Map<K,V> 中的 get
覆盖:
AbstractMap<K,V> 中的 get
参数:
key - 要返回其关联值的键
返回:
指定键所映射的值;如果此映射不包含该键的映射关系,则返回 null
另请参见:
put(Object, Object)

containsKey

public boolean containsKey(Object key)
如果此映射包含对于指定键的映射关系,则返回 true

指定者:
接口 Map<K,V> 中的 containsKey
覆盖:
AbstractMap<K,V> 中的 containsKey
参数:
key - 要测试其是否在此映射中存在的键
返回:
如果此映射包含对于指定键的映射关系,则返回 true

put

public V put(K key,
             V value)
在此映射中关联指定值与指定键。如果该映射以前包含了一个该键的映射关系,则旧值被替换。

指定者:
接口 Map<K,V> 中的 put
覆盖:
AbstractMap<K,V> 中的 put
参数:
key - 指定值将要关联的键
value - 指定键将要关联的值
返回:
key 关联的旧值;如果 key 没有任何映射关系,则返回 null。(返回 null 还可能表示该映射之前将 nullkey 关联。)

putAll

public void putAll(Map<? extends K,? extends V> m)
将指定映射的所有映射关系复制到此映射中,这些映射关系将替换此映射目前针对指定映射中所有键的所有映射关系。

指定者:
接口 Map<K,V> 中的 putAll
覆盖:
AbstractMap<K,V> 中的 putAll
参数:
m - 要在此映射中存储的映射关系
抛出:
NullPointerException - 如果指定的映射为 null

remove

public V remove(Object key)
从此映射中移除指定键的映射关系(如果存在)。

指定者:
接口 Map<K,V> 中的 remove
覆盖:
AbstractMap<K,V> 中的 remove
参数:
key - 其映射关系要从映射中移除的键
返回:
key 关联的旧值;如果 key 没有任何映射关系,则返回 null。(返回 null 还可能表示该映射之前将 nullkey 关联。)

clear

public void clear()
从此映射中移除所有映射关系。此调用返回后,映射将为空。

指定者:
接口 Map<K,V> 中的 clear
覆盖:
AbstractMap<K,V> 中的 clear

containsValue

public boolean containsValue(Object value)
如果此映射将一个或多个键映射到指定值,则返回 true

指定者:
接口 Map<K,V> 中的 containsValue
覆盖:
AbstractMap<K,V> 中的 containsValue
参数:
value - 要测试其是否在此映射中存在的值
返回:
如果此映射将一个或多个键映射到指定值,则返回 true

clone

public Object clone()
返回此 HashMap 实例的浅表副本:并不复制键和值本身。

覆盖:
AbstractMap<K,V> 中的 clone
返回:
此映射的浅表副本
另请参见:
Cloneable

keySet

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

指定者:
接口 Map<K,V> 中的 keySet
覆盖:
AbstractMap<K,V> 中的 keySet
返回:
此映射中包含的键的 set 视图

values

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

指定者:
接口 Map<K,V> 中的 values
覆盖:
AbstractMap<K,V> 中的 values
返回:
此映射中包含的值的 collection 视图

entrySet

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

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

JavaTM Platform
Standard Ed. 6

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

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