Класс HashMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

java.util.HashMap<K,V>

Type Parameters:: 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.

Since:

1.2

См. также:

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

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

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

Вложенные классы/интерфейсы, объявленные в интерфейсе java.util.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)`	Если значение для указанного ключа присутствует и не равно null, пытается вычислить новое отображение, учитывая ключ и его текущее сопоставленное значение (необязательная операция).
`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` представление значений, содержащихся в этой карте.

Методы, объявленные в классе 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)

Создаёт пустой 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>
Возвращает:: вид множества ключей, содержащихся в этой карте

значения

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, пытается вычислить новое отображение, учитывая ключ и его текущее сопоставленное значение (необязательная операция).

Если функция переопределения возвращает 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 сообщение к отображению значения:

 
 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 - ненулевое значение, которое нужно объединить с существующим значением, связанным с ключом, или, если нет существующего значения или связанного нулевого значения, которое нужно связать с ключом; remappingFunction - функция переопределения для повторного вычисления значения, если оно есть
Возвращает:: новое значение, связанное с указанным ключом, или null, если ключ не связан ни с каким значением
Исключение:: ConcurrentModificationException - если обнаружится, что функция переопределения изменила эту карту

клонировать

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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/HashMap.html