Класс 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.

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, связывает его с заданным ненулевым значением.
`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 с указанной начальной ёмкостью и коэффициентом загрузки.

Параметры:: initialCapacity - начальная ёмкость; loadFactor - коэффициент загрузки
Исключения:: IllegalArgumentException - если начальная ёмкость отрицательная или коэффициент загрузки неположительный

HashMap

public HashMap(int initialCapacity)

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

Параметры:: 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 если в этой карте нет отображения для ключа

См. также:

put(Object, Object)

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()

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

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

values

public Collection<V> values()

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

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

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, если будет обнаружено, что функция отображения изменяет это отображение во время вычисления.

Specified by:: computeIfAbsent в интерфейсе Map<K,V>
Parameters:: key - ключ, с которым должно быть связано указанное значение; mappingFunction - функция отображения для вычисления значения
Returns:: текущее (существующее или вычисленное) значение, связанное с указанным ключом, или null, если вычисленное значение равно null
Throws:: ConcurrentModificationException - если будет обнаружено, что функция отображения изменила это отображение

computeIfPresent

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

Если значение для указанного ключа присутствует и не равно null, пытается вычислить новое сопоставление, учитывая ключ и его текущее сопоставленное значение.

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

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

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

Specified by:: computeIfPresent в интерфейсе Map<K,V>
Parameters:: key - ключ, с которым должно быть связано указанное значение; remappingFunction - функция перепривязки для вычисления значения
Returns:: новое значение, связанное с указанным ключом, или null, если такого нет
Throws:: 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, сопоставление удаляется (или остается отсутствующим, если оно изначально отсутствовало). Если сама функция перепривязки вызывает (непроверенное) исключение, исключение перебрасывается, и текущее сопоставление остается неизменным.

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

Specified by:: compute в интерфейсе Map<K,V>
Parameters:: key - ключ, с которым должно быть связано указанное значение; remappingFunction - функция перепривязки для вычисления значения
Returns:: новое значение, связанное с указанным ключом, или null, если такого нет
Throws:: 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)

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

Specified by:: merge в интерфейсе Map<K,V>
Parameters:: key - ключ, с которым должно быть связано результирующее значение; value - ненулевое значение, которое должно быть объединено с существующим значением, связанным с ключом, или, если нет существующего значения или связанного нулевого значения, которое должно быть связано с ключом; remappingFunction - функция перепривязки для повторного вычисления значения, если оно присутствует
Returns:: новое значение, связанное с указанным ключом, или null, если значение не связано с ключом
Throws:: HashMap - если будет обнаружено, что функция перепривязки изменила это отображение

clone

public Object clone()

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

Overrides:

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

Returns:

неглубокая копия этого отображения

See Also:

Cloneable

© 1993, 2021, 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/17/docs/api/java.base/java/util/HashMap.html