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 大致相同。）此類別不保證映射的順序，特別是它不保證該順序恆久不變。

此實作假定雜湊函數將元素適當地分佈在各桶之間，可為基本操作（get 和 put）提供穩定的性能。迭代 collection 視圖所需的時間與 HashMap 實例的「容量」（桶的數量）及其大小（鍵-值映射關係數）成比例。所以，如果迭代性能很重要，則不要將初始容量設置得太高（或將載入因子設置得太低）。

HashMap 的實例有兩個參數影響其性能：初始容量 和載入因子。容量 是雜湊表中桶的數量，初始容量只是雜湊表在創建時的容量。載入因子 是雜湊表在其容量自動增加之前可以達到多滿的一種尺度。當雜湊表中的條目數超出了載入因子與當前容量的乘積時，則要對該雜湊表進行 rehash 操作（即重建內部資料結構），從而雜湊表將具有大約兩倍的桶數。

通常，預設載入因子 (.75) 在時間和空間成本上尋求一種折衷。載入因子過高雖然減少了空間開銷，但同時也增加了查詢成本（在大多數 HashMap 類別的操作中，包括 get 和 put 操作，都反映了這一點）。在設置初始容量時應該考慮到映射中所需的條目數及其載入因子，以便最大限度地減少 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 還可能表示該映射之前將 null 與 key 關聯。）

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 還可能表示該映射之前將 null 與 key 關聯。）

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.remove、Set.remove、removeAll、retainAll 和 clear 操作可從該映射中移除相應的映射關係。它不支持 add 或 addAll 操作。

指定者：

介面 Map<K,V> 中的 keySet

覆寫：

類別 AbstractMap<K,V> 中的 keySet

返回：

此映射中包含的鍵的 set 視圖

values

public Collection<V> values()

返回此映射所包含的值的 Collection 視圖。該 collection 受映射的支持，所以對映射的更改將反映在該 collection 中，反之亦然。如果在對 collection 進行迭代的同時修改了映射（通過迭代器自己的 remove 操作除外），則迭代結果是不確定的。該 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()

返回此映射所包含的映射關係的 Set 視圖。 該 set 受映射支持，所以對映射的更改將反映在此 set 中，反之亦然。如果在對 set 進行迭代的同時修改了映射（通過迭代器自己的 remove 操作，或者通過在該迭代器返回的映射項上執行 setValue 操作除外），則迭代結果是不確定的。該 set 支持元素的移除，通過 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作可從該映射中移除相應的映射關係。它不支持 add 或 addAll 操作。

指定者：

介面 Map<K,V> 中的 entrySet

指定者：

類別 AbstractMap<K,V> 中的 entrySet

返回：

此映射所包含的映射關係的 set 視圖。