モジュール java.base
パッケージ 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キーを使用できます。 HashMapクラスはHashtableと同じとみなしてもかまいませんが、HashMapの方は同期がとられず、nullの場合もあります。 このクラスはマップの順序を保証しません。特に、その順序を常に一定に保つことを保証しません。

この実装は、ハッシュ関数が複数のバケットで要素を適切に分散させることを想定し、基本オペレーション(getおよびput)で一定時間の性能を提供します。 コレクション・ビューの反復処理では、HashMapのインスタンスの「容量」(バケット数)とそのサイズ(キーと値のマッピングの数)の合計に比例した時間が必要です。 したがって、反復処理の性能が重要な場合は、初期容量をあまり高く(負荷係数をあまり低く)設定しないことが非常に重要です。

HashMapのインスタンスには、その性能に影響を与える2つのパラメータである初期容量および負荷係数があります。 容量はハッシュ表のバケット数であり、初期容量は単純にハッシュ表が作成された時点での容量です。 負荷係数は、ハッシュ表がどの程度いっぱいになると、その容量が自動的に増加されるかの基準です。 ハッシュ表エントリ数が負荷係数と現在の容量の積を超えると、ハッシュ表のハッシュがやり直され (つまり、内部データ構造が再構築され)、ハッシュ表のバケット数は約2倍になります。

ほとんどの場合、デフォルトの負荷係数(.75)では、時間コストとスペース・コストの釣合いを取ります。 この値を大きくすると、スペースのオーバーヘッドが減少しますが、参照コストが増加し、getおよびputを含むHashMapクラスのほとんどのオペレーションが影響を受けます。 初期容量を設定するときは、rehashオペレーションの回数を最小限に抑えるために、マップのエントリ予定数および負荷係数を考慮する必要があります。 初期容量が、エントリの最大数を負荷係数で割った値より大きい場合、rehashオペレーションは起こりません。

HashMapのインスタンスに多くのマッピングが格納される場合は、この表の作成時に十分な大きさの容量を設定すると、必要に応じてハッシュを自動的にやり直して表を大きくするよりも、マッピングをより効率的に格納できます。 同じhashCode()で多数のキーを使用すると、必ずいずれかのハッシュ表のパフォーマンスが低下することに注意してください。 影響を軽減するため、キーがComparableである場合は、このクラスでキー間の比較順序を使用してキーの重複を解消できます。

この実装はsynchronizedされません。 複数のスレッドが並行してハッシュ・マップにアクセスし、それらのスレッドの少なくとも1つが構造的にマップを変更する場合は、外部でその同期をとる必要があります。 構造的な変更とは、1つ以上のマッピングを追加または削除するオペレーションのことです。すでにインスタンスに格納されているキーに関連付けられた値を変更することは構造的な変更ではありません。 これは通常、マップを自然にカプセル化する一部のオブジェクトでsynchronizedすることによって達成されます。 そのようなオブジェクトが存在しない場合は、Collections.synchronizedMapメソッドを使用してマップを「ラップ」することをお薦めします。 マップが誤ってsynchronizedなしでアクセスされるのを防ぐために、作成時に行うことをお薦めします。 

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

このクラスの「コレクション・ビュー・メソッド」によって返されるイテレータはフェイルファストです。イテレータの作成後に、イテレータ自体のremoveメソッド以外の方法でマップが構造的に変更されると、イテレータはConcurrentModificationExceptionをスローします。 このように、並行して変更が行われると、イテレータは、将来の予測できない時点において予測できない動作が発生する危険を回避するために、ただちにかつ手際よく例外をスローします。

通常、非同期の並行変更がある場合、確かな保証を行うことは不可能なので、イテレータのフェイルファストの動作を保証することはできません。 フェイルファスト・イテレータは、ベスト・エフォート・ベースでConcurrentModificationExceptionをスローします。 したがって、正確を期すためにこの例外に依存するプログラムを書くことは誤りです。イテレータのフェイルファストの動作はバグを検出するためにのみ使用すべきです。

このクラスは、Java Collections Frameworkのメンバーです。

導入されたバージョン:
1.2
関連項目:

  • ネストされたクラスのサマリー

    クラス java.util.AbstractMapで宣言されたネストされたクラス/インタフェース

    AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

    インタフェース java.util.Mapで宣言されたネストされたクラス/インタフェース

    Map.Entry<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インスタンスのシャロー・コピーを返します。キーおよび値自体は複製されません。
    V
    compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    指定されたキーと現在マップされている値に対するマッピングの計算を試みます(現在のマッピングが存在しない場合はnull)。
    V
    computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
    指定されたキーがまだ値に関連付けられていない(またはnullにマップされている)場合、指定されたマッピング関数を使用してその値の計算を試行し、nullでない場合はそれをこのマップに入力します。
    V
    computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
    指定されたキーの値が存在していてnull以外の場合、キーと現在マップされている値から新しいマッピングの計算を試みます。
    boolean
    containsKey(Object key)
    指定されたキーのマッピングがこのマップに含まれている場合にtrueを返します。
    boolean
    containsValue(Object value)
    このマップが1つまたは複数のキーと指定された値をマッピングしている場合にtrueを返します。
    Set<Map.Entry<K,V>>
    entrySet()
    このマップに含まれるマッピングのSetビューを返します。
    V
    get(Object key)
    指定されたキーがマップされている値を返します。そのキーのマッピングがこのマップに含まれていない場合はnullを返します。
    boolean
    isEmpty()
    このマップがキーと値のマッピングを保持しない場合にtrueを返します。
    Set<K>
    keySet()
    このマップに含まれるキーのSetビューを返します。
    V
    merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
    指定されたキーがまだ値と関連付けられていないかnullと関連付けられている場合、指定されたnull以外の値に関連付けます。
    static <K, V> HashMap<K,V>
    newHashMap(int numMappings)
    必要なマッピング数に適した新しい空のHashMapを作成します。
    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, forEach, getOrDefault, hashCode, putIfAbsent, remove, replace, replace, replaceAll

  • コンストラクタの詳細

    • HashMap

      public HashMap(int initialCapacity, float loadFactor)
      指定された初期容量と負荷係数を持つ、空のHashMapを作成します。
      APIのノート:
      予想される数のマッピングに対応する初期容量を持つHashMapを作成するには、newHashMapを使用します。
      パラメータ:
      initialCapacity - 初期容量
      loadFactor - 負荷係数
      例外:
      IllegalArgumentException - 初期容量が負であるか、負荷係数が正でない場合

    • HashMap

      public HashMap(int initialCapacity)
      指定された初期容量とデフォルトの負荷係数(0.75)を持つ、空のHashMapを作成します。
      APIのノート:
      予想される数のマッピングに対応する初期容量を持つHashMapを作成するには、newHashMapを使用します。
      パラメータ:
      initialCapacity - 初期容量。
      例外:
      IllegalArgumentException - 初期容量が負の場合。

    • HashMap

      public HashMap()
      デフォルトの初期容量(16)とデフォルトの負荷係数(0.75)を持つ、空のHashMapを作成します。

    • HashMap

      public HashMap(Map<? extends K,? extends V> m)
      指定されたMapと同じマッピングで新しいHashMapを作成します。 デフォルトの負荷係数(0.75)、および指定されたMapのマッピングを保持するのに十分な初期容量で、HashMapは作成されます。
      パラメータ:
      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を返します。 (このようなマッピングは1つのみ存在できます。)

      戻り値nullは、マップがキーのマッピングを保持していないことを示すとはかぎりません。つまり、マップが明示的にキーをnullにマップすることもあります。 containsKey操作を使うと、これら2つのケースを見分けることができます。

      定義:
      インタフェースMap<K,V>内のget
      オーバーライド:
      クラスAbstractMap<K,V>のget
      パラメータ:
      key - 関連付けられた値が返されるキー
      戻り値:
      指定されたキーがマップされている値。そのキーのマッピングがこのマップに含まれていない場合はnull
      関連項目:

    • 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)
      このマップが1つまたは複数のキーと指定された値をマッピングしている場合にtrueを返します。
      定義:
      インタフェースMap<K,V>内のcontainsValue
      オーバーライド:
      クラスAbstractMap<K,V>のcontainsValue
      パラメータ:
      value - このマップにあるかどうかが判定される値
      戻り値:
      このマップが1つまたは複数のキーを指定された値にマッピングしている場合はtrue

    • keySet

      public Set<K> keySet()
      このマップに含まれるキーのSetビューを返します。 セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。 セットの反復処理中にマップが変更された場合、反復処理の結果は定義されていません(イテレータ自身のremoveオペレーションを除く)。 セットは要素の削除をサポートします。Iterator.remove、Set.remove、removeAll、retainAll、およびclearオペレーションで対応するマッピングをマップから削除します。 addまたはaddAll操作はサポートされていません。
      定義:
      インタフェースMap<K,V>内のkeySet
      オーバーライド:
      クラスAbstractMap<K,V>のkeySet
      戻り値:
      マップに含まれているキーのセット・ビュー

    • values

      public Collection<V> values()
      このマップに含まれる値のCollectionビューを返します。 コレクションはマップと連動しているので、マップに対する変更はコレクションに反映され、またコレクションに対する変更はマップに反映されます。 コレクションの反復処理中にマップが変更された場合、反復処理の結果は定義されません(イテレータ自身のremoveオペレーションを除く)。 コレクションは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Collection.remove、removeAll、retainAll、およびclearオペレーションを通して行います。 addまたはaddAll操作はサポートされていません。
      定義:
      インタフェースMap<K,V>内のvalues
      オーバーライド:
      クラスAbstractMap<K,V>のvalues
      戻り値:
      このマップに含まれている値のビュー

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      このマップに含まれるマッピングのSetビューを返します。 セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。 セットの反復処理中にマップが変更された場合、反復処理の結果は定義されません(イテレータ自身のremoveオペレーション、またはイテレータにより返されるマップ・エントリに対するsetValueオペレーションを除く)。 セットは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Set.remove、removeAll、retainAll、およびclearオペレーションを通して行います。 addまたはaddAll操作はサポートされていません。
      定義:
      インタフェースMap<K,V>内のentrySet
      戻り値:
      マップ内に保持されているマッピングのセット・ビュー

    • computeIfAbsent

      public V computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
      指定されたキーがまだ値に関連付けられていない(またはnullにマップされている)場合、指定されたマッピング関数を使用してその値の計算を試行し、nullでない場合はそれをこのマップに入力します。

      マッピング関数がnullを返した場合、マッピングは記録されません。 マッピング関数自体が(unchecked)例外をスローすると、例外は再スローされ、マッピングは記録されません。 もっとも一般的な用途は、次のように初期のマップされた値またはメモ化された結果として機能する新しいオブジェクトを構築することです。 

       
 map.computeIfAbsent(key, k -> new Value(f(k)));

      または、1つのキーで複数の値をサポートする複数値マップMap<K,Collection<V>>を実装することです。 

       
 map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);

      マッピング関数は、計算中にこのマップを変更すべきではありません。

      このメソッドは、最善の努力で、マッピング関数が計算中にこのマップを変更することが検出された場合にConcurrentModificationExceptionをスローします。

      定義:
      インタフェースMap<K,V>内のcomputeIfAbsent
      パラメータ:
      key - 指定された値が関連付けられるキー
      mappingFunction - 値をコンピュートするマッピング関数
      戻り値:
      指定されたキーに関連付けられている現在の(既存の、または計算された)値。計算された値がnullである場合はnull
      例外:
      ConcurrentModificationException - マップ機能がこのマップを変更したことが検出された場合

    • computeIfPresent

      public V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
      指定されたキーの値が存在していてnull以外の場合、キーと現在マップされている値から新しいマッピングの計算を試みます。

      リマッピング関数がnullを返した場合、マッピングは削除されます。 再マップ関数自体が(unchecked)例外をスローすると、例外が再スローされ、現在のマッピングは変更されません。

      再マップ関数は、計算中にこのマップを変更すべきではありません。

      このメソッドは、リマップ関数が計算中にこのマップを変更することが検出された場合、ベスト・エフォート・ベースでConcurrentModificationExceptionをスローします。

      定義:
      インタフェースMap<K,V>内のcomputeIfPresent
      パラメータ:
      key - 指定された値が関連付けられるキー
      remappingFunction - 値をコンピュートするための再マップ関数
      戻り値:
      指定されたキーに関連付けられる新しい値。存在しない場合はnull
      例外:
      ConcurrentModificationException - リマッピング機能がこのマップを変更したことが検出された場合

    • compute

      public V compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
      指定されたキーと現在マップされている値に対するマッピングの計算を試みます(現在のマッピングが存在しない場合はnull)。 たとえば、次のように、値のマッピングにString msgを作成または追加します。 
       
 map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))
      (このような目的で使用するmerge()メソッドは、多くの場合、より単純です。)

      再マッピング関数がnullを返した場合、マッピングは削除されます。(最初に欠席した場合は不在のままです)。 再マップ関数自体が(unchecked)例外をスローすると、例外が再スローされ、現在のマッピングは変更されません。

      再マップ関数は、計算中にこのマップを変更すべきではありません。

      このメソッドは、リマップ関数が計算中にこのマップを変更することが検出された場合、ベスト・エフォート・ベースでConcurrentModificationExceptionをスローします。

      定義:
      インタフェースMap<K,V>内のcompute
      パラメータ:
      key - 指定された値が関連付けられるキー
      remappingFunction - 値をコンピュートするための再マップ関数
      戻り値:
      指定されたキーに関連付けられる新しい値。存在しない場合はnull
      例外:
      ConcurrentModificationException - リマッピング機能がこのマップを変更したことが検出された場合

    • merge

      public V merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
      指定されたキーがまだ値と関連付けられていないかnullと関連付けられている場合、指定されたnull以外の値に関連付けます。 それ以外の場合は、指定された再マッピング関数の結果で関連する値を置換し、結果がnullの場合は削除します。 このメソッドは、1つのキーに対する複数のマップされた値を結合するときに使用できます。 たとえば、次のように、値のマッピングにString msgを作成または追加します。 
       
 map.merge(key, msg, String::concat)

      リマッピング関数がnullを返した場合、マッピングは削除されます。 再マップ関数自体が(unchecked)例外をスローすると、例外が再スローされ、現在のマッピングは変更されません。

      再マップ関数は、計算中にこのマップを変更すべきではありません。

      このメソッドは、リマップ関数が計算中にこのマップを変更することが検出された場合、ベスト・エフォート・ベースでConcurrentModificationExceptionをスローします。

      定義:
      インタフェースMap<K,V>内のmerge
      パラメータ:
      key - 結果値が関連付けられるキー
      value - キーに関連付けられた既存の値にマージされるnull以外の値。既存の値がない場合、またはキーにnull値が関連付けられている場合は、キーに関連付けられるnull以外の値
      remappingFunction - 存在する場合に値を再計算するための再マッピング関数
      戻り値:
      指定されたキーに関連付けられた新しい値。キーに値が関連付けられなかった場合はnull
      例外:
      ConcurrentModificationException - リマッピング機能がこのマップを変更したことが検出された場合

    • clone

      public Object clone()
      このHashMapインスタンスのシャロー・コピーを返します。キーおよび値自体は複製されません。
      オーバーライド:
      クラスAbstractMap<K,V>のclone
      戻り値:
      このマップのシャロー・コピー
      関連項目:

    • newHashMap

      public static <K, V> HashMap<K,V> newHashMap(int numMappings)
      必要なマッピング数に適した新しい空のHashMapを作成します。 返されるマップではデフォルトのロード係数0.75が使用され、初期容量は通常十分に大きいため、マップのサイズを変更せずに必要な数のマッピングを追加できます。
      型パラメータ:
      K - 新しいマップによって保持されるキーのタイプ
      V - マップされる値の型
      パラメータ:
      numMappings - マッピングの予想数
      戻り値:
      新しく作成されたマップ
      例外:
      IllegalArgumentException - numMappingsが負の場合
      導入されたバージョン:
      19