Class 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, за исключением того, что он не синхронизирован и допускает null.) Этот класс не дает никаких гарантий относительно порядка элементов карты; в частности, он не гарантирует, что порядок останется неизменным со временем.

Эта реализация обеспечивает постоянное время выполнения основных операций (get и put) при условии, что хеш-функция правильно распределяет элементы по корзинам. Итерация по представлениям коллекций требует времени, пропорционального «емкости» экземпляра HashMap (числу корзин) плюс его размеру (числу сопоставлений ключ-значение). Поэтому очень важно не задавать слишком большую начальную емкость (или слишком низкий коэффициент загрузки), если важна производительность итерации.

На производительность экземпляра HashMap влияют два параметра: начальная емкость и коэффициент загрузки. Емкость — это число корзин в хеш-таблице, а начальная емкость — это просто емкость на момент создания хеш-таблицы. Коэффициент загрузки определяет, насколько заполненной может стать хеш-таблица, прежде чем ее емкость будет автоматически увеличена. Когда число записей в хеш-таблице превышает произведение коэффициента загрузки на текущую емкость, выполняется перехеширование хеш-таблицы (то есть перестраиваются внутренние структуры данных), в результате чего число корзин в ней становится примерно вдвое больше.

Как правило, коэффициент загрузки по умолчанию (.75) обеспечивает хороший компромисс между затратами времени и памяти. Более высокие значения уменьшают накладные расходы на память, но увеличивают стоимость поиска (что отражается на большинстве операций класса HashMap, включая get и put). При задании начальной емкости следует учитывать ожидаемое число записей в карте и коэффициент загрузки, чтобы свести к минимуму число операций перехеширования. Если начальная емкость больше максимального числа записей, деленного на коэффициент загрузки, операции перехеширования не понадобятся.

Если в экземпляре HashMap предполагается хранить много сопоставлений, создание экземпляра с достаточно большой емкостью позволит хранить сопоставления эффективнее, чем автоматическое перехеширование по мере необходимости для увеличения таблицы. Обратите внимание: использование множества ключей с одинаковым значением hashCode() — надежный способ замедлить работу любой хеш-таблицы. Чтобы смягчить последствия, если ключи реализуют Comparable, этот класс может использовать порядок сравнения ключей для разрешения совпадений.

Обратите внимание, что эта реализация не синхронизирована. Если несколько потоков одновременно обращаются к хеш-карте и хотя бы один из них структурно изменяет карту, доступ должен синхронизироваться извне. (Структурным изменением считается любая операция, добавляющая или удаляющая одно или несколько сопоставлений; простое изменение значения, связанного с уже имеющимся в экземпляре ключом, не является структурным изменением.) Обычно для этого синхронизируют некоторый объект, который естественным образом инкапсулирует карту. Если такого объекта нет, карту следует «обернуть» с помощью метода Collections.synchronizedMap. Лучше всего сделать это при создании карты, чтобы предотвратить случайный несинхронизированный доступ к ней:

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

Итераторы, возвращаемые всеми «методами представления коллекций» этого класса, являются быстро отказывающими: если после создания итератора карта структурно изменяется любым способом, кроме вызова собственного метода remove итератора, итератор выбрасывает исключение ConcurrentModificationException. Таким образом, при конкурентном изменении итератор быстро и корректно завершается с ошибкой, вместо того чтобы допустить произвольное, недетерминированное поведение в неопределенный момент в будущем.

Обратите внимание, что гарантировать быстрое завершение итератора с ошибкой невозможно, поскольку, вообще говоря, при несинхронизированном конкурентном изменении невозможно дать какие-либо строгие гарантии. Итераторы выбрасывают ConcurrentModificationException по мере возможности. Поэтому было бы неправильно писать программу, корректность которой зависит от этого исключения: быстрое завершение итераторов с ошибкой следует использовать только для обнаружения ошибок.

Этот класс входит в Java Collections Framework.

Начиная с:

1.2

См. также:

Краткое описание вложенных классов

Вложенные классы/интерфейсы, объявленные в классе AbstractMap

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

Вложенные классы/интерфейсы, объявленные в интерфейсе Map

Map.Entry<K,V>

Краткое описание конструкторов

Конструктор	Описание
`HashMap()`	Создает пустой `HashMap` с начальной емкостью по умолчанию (16) и коэффициентом загрузки по умолчанию (0.75).
`HashMap(int initialCapacity)`	Создает пустой `HashMap` с указанной начальной емкостью и коэффициентом загрузки по умолчанию (0.75).
`HashMap(int initialCapacity, float loadFactor)`	Создает пустой `HashMap` с указанными начальной емкостью и коэффициентом загрузки.
`HashMap(Map<? extends K, ? extends V> m)`	Создает новый `HashMap` с теми же сопоставлениями, что и указанный `Map`.

Краткое описание методов

Модификатор и тип	Метод	Описание
`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)`	Если указанному ключу сопоставлено присутствующее ненулевое значение, пытается вычислить новое сопоставление на основе ключа и его текущего сопоставленного значения (необязательная операция).
`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`	`merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction)`	Если указанному ключу еще не сопоставлено значение или ему сопоставлено 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`.

Методы, объявленные в классе AbstractMap

equals, hashCode, toString

Методы, объявленные в классе Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Методы, объявленные в интерфейсе 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)

Создает пустое HashMap с заданной начальной емкостью и коэффициентом загрузки по умолчанию (0.75).

Примечание API:: Чтобы создать HashMap с начальной емкостью, достаточной для ожидаемого числа отображений, используйте newHashMap.
Параметры:: initialCapacity — начальная емкость.
Исключения:: IllegalArgumentException — если начальная емкость отрицательна.

HashMap

public HashMap()

Создает пустое HashMap с начальной емкостью по умолчанию (16) и коэффициентом загрузки по умолчанию (0.75).

HashMap

public HashMap(Map<? extends K, ? extends V> m)

Создает новое HashMap с теми же отображениями, что и заданное Map. HashMap создается с коэффициентом загрузки по умолчанию (0.75) и начальной емкостью, достаточной для хранения отображений из заданного Map.

Параметры:: m — отображение, отображения из которого следует поместить в это отображение
Исключения:: NullPointerException — если заданное отображение равно null

Подробное описание методов

size

public int size()

Возвращает количество отображений ключ-значение в этом отображении.

Указано в:: size в интерфейсе Map<K,V>
Переопределяет:: size в классе AbstractMap<K,V>
Возвращает:: количество отображений ключ-значение в этом отображении

isEmpty

public boolean isEmpty()

Возвращает true, если это отображение не содержит отображений ключ-значение.

Указано в:: isEmpty в интерфейсе Map<K,V>
Переопределяет:: isEmpty в классе AbstractMap<K,V>
Возвращает:: true, если это отображение не содержит отображений ключ-значение

get

public V get(Object key)

Возвращает значение, которому сопоставлен заданный ключ, или null, если в этом отображении нет соответствия для ключа.

Точнее, если это отображение содержит соответствие ключа k значению v, такое что (key==null ? k==null : key.equals(k)), этот метод возвращает v; в противном случае он возвращает null. (Такое соответствие может быть не более чем одно.)

Возвращаемое значение null не обязательно означает, что в отображении нет соответствия для ключа; возможно также, что отображение явно сопоставляет ключу значение null. Операцию containsKey можно использовать, чтобы различить эти два случая.

Указано в:

get в интерфейсе Map<K,V>

Переопределяет:

get в классе AbstractMap<K,V>

Параметры:

key — ключ, значение которого требуется вернуть

Возвращает:

значение, которому сопоставлен заданный ключ, или null, если в этом отображении нет соответствия для ключа

См. также:

containsKey

public boolean containsKey(Object key)

Возвращает true, если это отображение содержит соответствие для заданного ключа.

Указано в:: containsKey в интерфейсе Map<K,V>
Переопределяет:: containsKey в классе AbstractMap<K,V>
Параметры:: key — ключ, наличие которого в этом отображении требуется проверить
Возвращает:: true, если это отображение содержит соответствие для заданного ключа.

put

public V put(K key, V value)

Сопоставляет заданное значение заданному ключу в этом отображении. Если ранее в отображении было соответствие для этого ключа, старое значение заменяется.

Указано в:: put в интерфейсе Map<K,V>
Переопределяет:: put в классе AbstractMap<K,V>
Параметры:: key — ключ, которому требуется сопоставить заданное значение; value — значение, которое требуется сопоставить заданному ключу
Возвращает:: предыдущее значение, связанное с key, или null, если соответствия для key не было. (Возвращаемое значение null также может означать, что ранее отображение сопоставляло null значению key.)

putAll

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

Копирует все отображения из заданного отображения в это отображение. Эти отображения заменят любые отображения, которые имелись в этом отображении для ключей, присутствующих в заданном отображении.

Указано в:: putAll в интерфейсе Map<K,V>
Переопределяет:: putAll в классе AbstractMap<K,V>
Параметры:: m — отображения, которые требуется сохранить в этом отображении
Исключения:: NullPointerException — если заданное отображение равно null

remove

public V remove(Object key)

Удаляет из этого отображения соответствие для заданного ключа, если оно присутствует.

Указано в:: remove в интерфейсе Map<K,V>
Переопределяет:: remove в классе AbstractMap<K,V>
Параметры:: key — ключ, соответствие для которого требуется удалить из отображения
Возвращает:: предыдущее значение, связанное с key, или null, если соответствия для key не было. (Возвращаемое значение null также может означать, что ранее отображение сопоставляло null значению key.)

clear

public void clear()

Удаляет все отображения из этого отображения. После возврата этого вызова отображение будет пустым.

Указано в:: clear в интерфейсе Map<K,V>
Переопределяет:: clear в классе AbstractMap<K,V>

containsValue

public boolean containsValue(Object value)

Возвращает true, если в этом отображении один или несколько ключей сопоставлены заданному значению.

Указано в:: containsValue в интерфейсе Map<K,V>
Переопределяет:: containsValue в классе AbstractMap<K,V>
Параметры:: value — значение, наличие которого в этом отображении требуется проверить
Возвращает:: true, если в этом отображении один или несколько ключей сопоставлены заданному значению

keySet

public Set<K> keySet()

Возвращает представление ключей, содержащихся в этом отображении, в виде Set. Множество поддерживается отображением, поэтому изменения отображения отражаются в множестве, и наоборот. Если отображение изменяется во время итерации по множеству (за исключением операции remove, выполняемой самим итератором), результат итерации не определен. Множество поддерживает удаление элементов, которое удаляет соответствующее отображение из отображения, с помощью операций Iterator.remove, Set.remove, removeAll, retainAll и clear. Операции add и addAll не поддерживаются.

Указано в:: keySet в интерфейсе Map<K,V>
Переопределяет:: keySet в классе AbstractMap<K,V>
Возвращает:: представление ключей, содержащихся в этом отображении, в виде множества

values

public Collection<V> values()

Возвращает представление значений, содержащихся в этом отображении, в виде Collection. Коллекция поддерживается отображением, поэтому изменения отображения отражаются в коллекции, и наоборот. Если отображение изменяется во время итерации по коллекции (за исключением операции remove, выполняемой самим итератором), результат итерации не определен. Коллекция поддерживает удаление элементов, которое удаляет соответствующее отображение из отображения, с помощью операций Iterator.remove, Collection.remove, removeAll, retainAll и clear. Операции add и addAll не поддерживаются.

Указано в:: values в интерфейсе Map<K,V>
Переопределяет:: values в классе AbstractMap<K,V>
Возвращает:: представление значений, содержащихся в этом отображении

entrySet

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

Возвращает представление отображений, содержащихся в этом отображении, в виде Set. Множество поддерживается отображением, поэтому изменения отображения отражаются в множестве, и наоборот. Если отображение изменяется во время итерации по множеству (за исключением операции remove, выполняемой самим итератором, или операции setValue для записи отображения, возвращенной итератором), результат итерации не определен. Множество поддерживает удаление элементов, которое удаляет соответствующее отображение из отображения, с помощью операций Iterator.remove, Set.remove, removeAll, retainAll и clear. Операции add и addAll не поддерживаются.

Указано в:: entrySet в интерфейсе Map<K,V>
Возвращает:: представление отображений, содержащихся в этом отображении, в виде множества

computeIfAbsent

public V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)

Если заданному ключу еще не сопоставлено значение (или ему сопоставлено null), пытается вычислить его значение с помощью заданной функции сопоставления и добавляет его в это отображение, если результат не равен null (необязательная операция).

Если функция сопоставления возвращает null, соответствие не сохраняется. Если сама функция сопоставления выбрасывает (непроверяемое) исключение, исключение передается дальше, а соответствие не сохраняется. Наиболее распространенный вариант использования — создание нового объекта в качестве начального сопоставленного значения или мемоизированного результата, например:

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

Или реализация отображения с несколькими значениями, Map<K,Collection<V>>, поддерживающего несколько значений для каждого ключа:

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

Во время вычисления функция сопоставления не должна изменять это отображение.

В меру своих возможностей этот метод выбросит ConcurrentModificationException, если обнаружит, что функция сопоставления изменяет это отображение во время вычисления.

Указано в:: computeIfAbsent в интерфейсе Map<K,V>
Параметры:: key — ключ, которому требуется сопоставить заданное значение; mappingFunction — функция сопоставления для вычисления значения
Возвращает:: текущее значение (существующее или вычисленное), связанное с заданным ключом, или null, если вычисленное значение равно null
Исключения:: ConcurrentModificationException — если обнаружено, что функция сопоставления изменила это отображение

computeIfPresent

public V computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)

Если для заданного ключа имеется ненулевое значение, пытается вычислить новое отображение с учетом ключа и текущего сопоставленного ему значения (необязательная операция).

Если функция повторного сопоставления возвращает null, соответствие удаляется. Если сама функция повторного сопоставления выбрасывает (непроверяемое) исключение, исключение передается дальше, а текущее соответствие остается неизменным.

Во время вычисления функция повторного сопоставления не должна изменять это отображение.

В меру своих возможностей этот метод выбросит ConcurrentModificationException, если обнаружит, что функция повторного сопоставления изменяет это отображение во время вычисления.

Указано в:: computeIfPresent в интерфейсе Map<K,V>
Параметры:: 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, соответствие удаляется (или остается отсутствующим, если изначально его не было). Если сама функция повторного сопоставления выбрасывает (непроверяемое) исключение, исключение передается дальше, а текущее соответствие остается неизменным.

Во время вычисления функция повторного сопоставления не должна изменять это отображение.

Указано в:: compute в интерфейсе Map<K,V>
Параметры:: key — ключ, которому требуется сопоставить заданное значение; remappingFunction — функция повторного сопоставления для вычисления значения
Возвращает:: новое значение, связанное с заданным ключом, или null, если такого значения нет
Исключения:: ConcurrentModificationException — если обнаружено, что функция повторного сопоставления изменила это отображение

merge

public V merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction)

Если заданному ключу еще не сопоставлено значение или ему сопоставлено null, сопоставляет ему заданное ненулевое значение (необязательная операция). В противном случае заменяет сопоставленное значение результатом заданной функции повторного сопоставления или удаляет соответствие, если результат равен null. Этот метод может пригодиться при объединении нескольких сопоставленных значений для одного ключа. Например, чтобы создать или дополнить String msg в сопоставлении значения:

map.merge(key, msg, String::concat)

Во время вычисления функция повторного сопоставления не должна изменять это отображение.

Указано в:: merge в интерфейсе Map<K,V>
Параметры:: key — ключ, которому требуется сопоставить результирующее значение; value — ненулевое значение, которое требуется объединить с существующим значением, связанным с ключом, или сопоставить ключу, если для него нет существующего значения либо ему сопоставлено значение null; remappingFunction — функция повторного сопоставления для повторного вычисления значения, если оно имеется
Возвращает:: новое значение, связанное с заданным ключом, или null, если ключу не сопоставлено значение
Исключения:: ConcurrentModificationException — если обнаружено, что функция повторного сопоставления изменила это отображение

clone

public Object clone()

Возвращает поверхностную копию этого экземпляра HashMap: сами ключи и значения не клонируются.

Переопределяет:

clone в классе AbstractMap<K,V>

Возвращает:

поверхностную копию этого отображения

См. также:

newHashMap

public static <K,V> HashMap<K,V> newHashMap(int numMappings)

Создает новое пустое отображение HashMap, подходящее для ожидаемого числа отображений. Возвращаемое отображение использует коэффициент загрузки по умолчанию 0.75, а его начальная емкость обычно достаточна для добавления ожидаемого числа отображений без изменения размера отображения.

Параметры типа:: K — тип ключей нового отображения; V — тип сопоставленных значений
Параметры:: numMappings — ожидаемое число отображений
Возвращает:: созданное отображение
Исключения:: IllegalArgumentException — если numMappings отрицательно
С версии:: 19

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/HashMap.html