java.util 类 HashMap<K,V>

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.HashMap<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 大致相同。）此类不保证映射的顺序，特别是它不保证该顺序恒久不变。

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

HashMap 的实例有两个参数影响其性能：初始容量 和加载因子。容量 是哈希表中桶的数量，初始容量只是哈希表在创建时的容量。加载因子 是哈希表在其容量自动增加之前可以达到多满的一种尺度。当哈希表中的条目数超出了加载因子与当前容量的乘积时，通过调用 rehash 方法将容量翻倍。

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

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

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

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

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

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

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.2

另请参见：

Object.hashCode(), Collection, Map, TreeMap, Hashtable, 序列化表格

---

<!----> <!---->

构造方法摘要

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()           返回此映射所包含的映射关系的 collection 视图。
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。返回值为 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 - 指定键将要关联的值。

返回：

与指定键相关联的旧值，如果键没有任何映射关系，则返回 null。返回 null 还可能表示该 HashMap 以前将 null 与指定键关联。

---

<!---->

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 - 其映射关系要从映射中移除的键。

返回：

与指定键相关联的旧值，如果键没有任何映射关系，则返回 null。返回 null 还可能表示该映射以前将 null 与指定键关联。

---

<!---->

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 视图。该集合受映射的支持，所以映射的变化也反映在该集合中，反之亦然。该集合支持元素的移除，通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作，从该映射中移除相应的映射关系。它不支持 add 或 addAll 操作。

指定者：

接口 Map<K,V> 中的 keySet

覆盖：

类 AbstractMap<K,V> 中的 keySet

返回：

此映射所包含的键的 set 视图。

---

<!---->

values

public Collection<V> values()

返回此映射所包含的值的 collection 视图。该集合受映射的支持，所以映射的变化也反映在该集合中，反之亦然。该集合支持元素的移除，通过 Iterator.remove、Collection.remove、removeAll、retainAll 和 clear 操作，从该映射中移除相应的映射关系。它不支持 add 或 addAll 操作。

指定者：

接口 Map<K,V> 中的 values

覆盖：

类 AbstractMap<K,V> 中的 values

返回：

此映射所包含的值的 collection 视图。

---

<!---->

entrySet

public Set<Map.Entry<K,V>> entrySet()

返回此映射所包含的映射关系的 collection 视图。在返回的集合中，每个元素都是一个 Map.Entry。该集合受映射的支持，所以映射的变化也反映在该集合中，反之亦然。该集合支持元素的移除，通过 Iterator.remove、Collection.remove、removeAll、retainAll 和 clear 操作，从该映射中移除相应的映射关系。它不支持 add 或 addAll 操作。

指定者：

接口 Map<K,V> 中的 entrySet

指定者：

类 AbstractMap<K,V> 中的 entrySet

返回：

此映射所包含的映射关系的 collection 视图。

另请参见：

Map.Entry