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

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

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 сопоставлений, содержащихся в этой карте. Множество поддерживается картой, поэтому изменения в карте отражаются в множестве и наоборот. Если карта изменяется во время итерации по множеству (кроме операций самого итератора, или операций на элементе карты, возвращённом итератором), результаты итерации не определены. Множество поддерживает удаление элементов, что удаляет соответствующее сопоставление из карты, посредством операций 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 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, 2023, 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/21/docs/api/java.base/java/util/HashMap.html