java.util
介面 Map<K,V>

型別參數：

K - 此映射所維護的鍵的型別

V - 映射值的型別

所有已知子介面：

Bindings, ConcurrentMap<K,V>, ConcurrentNavigableMap<K,V>, LogicalMessageContext, MessageContext, NavigableMap<K,V>, SOAPMessageContext, SortedMap<K,V>

所有已知實作類別：

AbstractMap, Attributes, AuthProvider, ConcurrentHashMap, ConcurrentSkipListMap, EnumMap, HashMap, Hashtable, IdentityHashMap, LinkedHashMap, PrinterStateReasons, Properties, Provider, RenderingHints, SimpleBindings, TabularDataSupport, TreeMap, UIDefaults, WeakHashMap

public interface Map<K,V>

將鍵映射到值的物件。一個映射不能包含重複的鍵；每個鍵最多只能映射到一個值。

此介面取代 Dictionary 類別，後者完全是一個抽象類別，而不是一個介面。

Map 介面提供三種collection 視圖，允許以鍵集、值集或鍵-值映射關係集的形式查看某個映射的內容。映射順序 定義為迭代器在映射的 collection 視圖上返回其元素的順序。某些映射實作可明確保證其順序，如 TreeMap 類別；另一些映射實作則不保證順序，如 HashMap 類別。

註：將可變物件用作映射鍵時必須格外小心。當物件是映射中某個鍵時，如果以影響 equals 比較的方式更改了物件的值，則映射的行為將是不確定的。此項禁止的一種特殊情況是不允許某個映射將自身作為一個鍵包含。雖然允許某個映射將自身作為值包含，但請格外小心：在這樣的映射上 equals 和 hashCode 方法的定義將不再是明確的。

所有通用的映射實作類別應該提供兩個「標準的」建構子：一個 void（無參數）建構子，用於創建空映射；一個是帶有單個 Map 型別參數的建構子，用於創建一個與其參數具有相同鍵-值映射關係的新映射。實際上，後一個建構子允許使用者複製任意映射，產生所需類別的一個等價映射。儘管無法強制執行此建議（因為介面不能包含建構子），但是 JDK 中所有通用的映射實作都遵從它。

此介面中包含的「破壞」方法可修改其操作的映射，如果此映射不支持該操作，這些方法將拋出 UnsupportedOperationException。如果是這樣，那麼在調用對映射無效時，這些方法可以（但不要求）拋出 UnsupportedOperationException。例如，如果某個不可修改的映射（其映射關係是「重疊」的）為空，則對該映射調用 putAll(Map) 方法時，可以（但不要求）拋出異常。

某些映射實作對可能包含的鍵和值有所限制。例如，某些實作禁止 null 鍵和值，另一些則對其鍵的型別有限制。嘗試插入不合格的鍵或值將拋出一個未經檢查的異常，通常是 NullPointerException 或 ClassCastException。試圖查詢是否存在不合格的鍵或值可能拋出異常，或者返回 false；某些實作將表現出前一種行為，而另一些則表現後一種。一般來說，試圖對不合格的鍵或值執行操作且該操作的完成不會導致不合格的元素被插入映射中時，將可能拋出一個異常，也可能操作成功，這取決於實作本身。這樣的異常在此介面的規範中標記為「可選」。

此介面是 Java Collections Framework 的成員。

Collections Framework 介面中的很多方法是根據 equals 方法定義的。例如，containsKey(Object key) 方法的規範中寫道：「當且僅當此映射包含針對滿足 (key==null ? k==null : key.equals(k)) 的鍵 k 的映射關係時，返回 true」。不 應將此規範解釋為：調用具有非空(null)參數 key 的 Map.containsKey 將導致對任意的鍵 k 調用 key.equals(k)。實作可隨意進行優化，以避免調用 equals，例如，可首先比較兩個鍵的雜湊碼（Object.hashCode() 規範保證雜湊碼不相等的兩個物件不會相等）。一般來說，只要實作者認為合適，各種 Collections Framework 介面的實作可隨意利用底層 Object 方法的指定行為。

從以下版本開始：

1.2

另請參見：

HashMap, TreeMap, Hashtable, SortedMap, Collection, Set

巢狀類別摘要

static interface

Map.Entry<K,V> 映射項（鍵-值對）。

方法摘要

void	clear() 從此映射中移除所有映射關係（可選操作）。
boolean	containsKey(Object key) 如果此映射包含指定鍵的映射關係，則返回 true。
boolean	containsValue(Object value) 如果此映射將一個或多個鍵映射到指定值，則返回 true。
Set<Map.Entry<K,V>>	entrySet() 返回此映射中包含的映射關係的 Set 視圖。
boolean	equals(Object o) 比較指定的物件與此映射是否相等。
V	get(Object key) 返回指定鍵所映射的值；如果此映射不包含該鍵的映射關係，則返回 null。
int	hashCode() 返回此映射的雜湊碼值。
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 視圖。

方法詳細資訊

size

int size()

返回此映射中的鍵-值映射關係數。如果該映射包含的元素大於 Integer.MAX_VALUE，則返回 Integer.MAX_VALUE。

返回：

此映射中的鍵-值映射關係數

isEmpty

boolean isEmpty()

如果此映射未包含鍵-值映射關係，則返回 true。

返回：

如果此映射未包含鍵-值映射關係，則返回 true

containsKey

boolean containsKey(Object key)

如果此映射包含指定鍵的映射關係，則返回 true。更確切地講，當且僅當此映射包含針對滿足 (key==null ? k==null : key.equals(k)) 的鍵 k 的映射關係時，返回 true。（最多只能有一個這樣的映射關係）。

參數：

key - 測試是否存在於此映射中的鍵

返回：

如果此映射包含指定鍵的映射關係，則返回 true

拋出：

ClassCastException - 如果該鍵對於此映射是不合適的型別（可選）

NullPointerException - 如果指定鍵為 null 並且此映射不允許 null 鍵（可選）

containsValue

boolean containsValue(Object value)

如果此映射將一個或多個鍵映射到指定值，則返回 true。更確切地講，當且僅當此映射至少包含一個對滿足 (value==null ? v==null : value.equals(v)) 的值 v 的映射關係時，返回 true。對於大多數 Map 介面的實作而言，此操作需要的時間可能與映射大小呈線性關係。

參數：

value - 測試是否存在於此映射中的值

返回：

如果此映射將一個或多個鍵映射到指定值，則返回 true

拋出：

ClassCastException - 如果該值對於此映射是不合適的型別（可選）

NullPointerException - 如果指定值為 null 並且此映射不允許 null 值（可選）

get

V get(Object key)

返回指定鍵所映射的值；如果此映射不包含該鍵的映射關係，則返回 null。

更確切地講，如果此映射包含滿足 (key==null ? k==null : key.equals(k)) 的鍵 k 到值 v 的映射關係，則此方法返回 v；否則返回 null。（最多只能有一個這樣的映射關係）。

如果此映射允許 null 值，則返回 null 值並不一定 表示該映射不包含該鍵的映射關係；也可能該映射將該鍵顯示地映射到 null。使用 containsKey 操作可區分這兩種情況。

參數：

key - 要返回其關聯值的鍵

返回：

指定鍵所映射的值；如果此映射不包含該鍵的映射關係，則返回 null

拋出：

ClassCastException - 如果該鍵對於此映射是不合適的型別（可選）

NullPointerException - 如果指定鍵為 null 並且此映射不允許 null 鍵（可選）

put

V put(K key,
      V value)

將指定的值與此映射中的指定鍵關聯（可選操作）。如果此映射以前包含一個該鍵的映射關係，則用指定值替換舊值（當且僅當 m.containsKey(k) 返回 true 時，才能說映射 m 套件含鍵 k 的映射關係）。

參數：

key - 與指定值關聯的鍵

value - 與指定鍵關聯的值

返回：

以前與 key 關聯的值，如果沒有針對 key 的映射關係，則返回 null。（如果該實作支持 null 值，則返回 null 也可能表示此映射以前將 null 與 key 關聯）。

拋出：

UnsupportedOperationException - 如果此映射不支持 put 操作

ClassCastException - 如果指定鍵或值的類別不允許將其存儲在此映射中

NullPointerException - 如果指定鍵或值為 null，並且此映射不允許 null 鍵或值

IllegalArgumentException - 如果指定鍵或值的某些屬性不允許將其存儲在此映射中

remove

V remove(Object key)

如果存在一個鍵的映射關係，則將其從此映射中移除（可選操作）。更確切地講，如果此映射包含從滿足 (key==null ? k==null :key.equals(k)) 的鍵 k 到值 v 的映射關係，則移除該映射關係。（該映射最多只能包含一個這樣的映射關係。）

返回此映射中以前關聯該鍵的值，如果此映射不包含該鍵的映射關係，則返回 null。

如果此映射允許 null 值，則返回 null 值並不一定 表示該映射不包含該鍵的映射關係；也可能該映射將該鍵顯示地映射到 null。

調用返回後，此映射將不再包含指定鍵的映射關係。

參數：

key - 從映射中移除其映射關係的鍵

返回：

以前與 key 關聯的值；如果沒有 key 的映射關係，則返回 null。

拋出：

UnsupportedOperationException - 如果此映射不支持 remove 操作

ClassCastException - 如果該鍵對於此映射是不合適的型別（可選）

NullPointerException - 如果指定鍵為 null 並且此映射不允許 null 鍵（可選）

putAll

void putAll(Map<? extends K,? extends V> m)

從指定映射中將所有映射關係複製到此映射中（可選操作）。對於指定映射中的每個鍵 k 到值 v 的映射關係，此調用等效於對此映射調用一次 put(k, v)。如果正在進行此操作的同時修改了指定的映射，則此操作的行為是不確定的。

參數：

m - 要存儲在此映射中的映射關係

拋出：

UnsupportedOperationException - 如果此映射不支持 putAll 操作

ClassCastException - 如果指定映射中的鍵或值的類別不允許將其存儲在此映射中

NullPointerException - 如果指定映射為 null，或者此映射不允許 null 鍵或值，並且指定的映射包含 null 鍵或值

IllegalArgumentException - 如果指定映射中的鍵或值的某些屬性不允許將其存儲在此映射中

clear

void clear()

從此映射中移除所有映射關係（可選操作）。此調用返回後，該映射將為空。

拋出：

UnsupportedOperationException - 如果此映射不支持 clear 操作

keySet

Set<K> keySet()

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

返回：

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

values

Collection<V> values()

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

返回：

此映射中包含的值的 collection 視圖

entrySet

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

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

返回：

此映射中包含的映射關係的 set 視圖

equals

boolean equals(Object o)

比較指定的物件與此映射是否相等。如果給定的物件也是一個映射，並且這兩個映射表示相同的映射關係，則返回 true。更確切地講，如果 m1.entrySet().equals(m2.entrySet())，則兩個映射 m1 和 m2 表示相同的映射關係。這可以確保 equals 方法在不同的 Map 介面實作間運行正常。

覆寫：

類別 Object 中的 equals

參數：

o - 要與此映射進行相等性比較的物件

返回：

如果指定的物件等於此映射，則返回 true

另請參見：

Object.hashCode(), Hashtable

hashCode

int hashCode()

返回此映射的雜湊碼值。映射的雜湊碼定義為此映射 entrySet() 視圖中每個項的雜湊碼之和。這確保 m1.equals(m2) 對於任意兩個映射 m1 和 m2 而言，都意味著 m1.hashCode()==m2.hashCode()，正如 Object.hashCode() 常規協定的要求。

覆寫：

類別 Object 中的 hashCode

返回：

此映射的雜湊碼值

另請參見：

Map.Entry.hashCode(), Object.equals(Object), equals(Object)