Package org.apache.commons.collections4.map

# Class AbstractHashedMap<K,V>

java.lang.Object
java.util.AbstractMap<K,V>
org.apache.commons.collections4.map.AbstractHashedMap<K,V>

Type Parameters:
  `K` - the type of the keys in this map
  `V` - the type of the values in this map

All Implemented Interfaces:
  `Map<K,V>`, `Get<K,V>`, `IterableGet<K,V>`, `IterableMap<K,V>`, `Put<K,V>`

Direct Known Subclasses:
  `AbstractLinkedMap`, `AbstractReferenceMap`, `CaseInsensitiveMap`, `HashedMap`

public class AbstractHashedMap<K,V> extends AbstractMap<K,V> implements IterableMap<K,V>
An abstract implementation of a hash-based map which provides numerous points for subclasses to override.

This class implements all the features necessary for a subclass hash-based map. Key-value entries are stored in instances of the `HashEntry` class, which can be overridden and replaced. The iterators can similarly be replaced, without the need to replace the KeySet, EntrySet and Values view classes.

Overridable methods are provided to change the default hashing behavior, and to change how entries are added to and removed from the map. Hopefully, all you need for unusual subclasses is here.

NOTE: From Commons Collections 3.1 this class extends AbstractMap. This is to provide backwards compatibility for ReferenceMap between v3.0 and v3.1. This extends clause will be removed in v5.0.

Since:
  3.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `AbstractHashedMap.EntrySet<K,V>`
  EntrySet implementation.
  `protected static class`
  `AbstractHashedMap.EntrySetIterator<K,V>`
  EntrySet iterator.
  `protected static class`
  `AbstractHashedMap.HashEntry<K,V>`
  HashEntry used to store the data.
  `protected static class`
  `AbstractHashedMap.HashIterator<K,V>`
  Base Iterator.
  `protected static class`
  `AbstractHashedMap.HashMapIterator<K,V>`
  MapIterator implementation.
  `protected static class`
  `AbstractHashedMap.KeySet<K>`
  KeySet implementation.
  `protected static class`
  `AbstractHashedMap.KeySetIterator<K>`
  KeySet iterator.
  `protected static class`
  `AbstractHashedMap.Values<V>`
  Values implementation.
  `protected static class`
  `AbstractHashedMap.ValuesIterator<V>`
  Values iterator.

  ## Nested classes/interfaces inherited from class java.util.AbstractMap

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

  ## Nested classes/interfaces inherited from interface java.util.Map

  `Map.Entry<K,V>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final int`
  `DEFAULT_CAPACITY`
  The default capacity to use
  `protected static final float`
  `DEFAULT_LOAD_FACTOR`
  The default load factor to use
  `protected static final int`
  `DEFAULT_THRESHOLD`
  The default threshold to use
  `protected static final String`
  `GETKEY_INVALID`
  Exception message.
  `protected static final String`
  `GETVALUE_INVALID`
  Exception message.
  `protected static final int`
  `MAXIMUM_CAPACITY`
  The maximum capacity allowed
  `protected static final String`
  `NO_NEXT_ENTRY`
  Exception message.
  `protected static final String`
  `NO_PREVIOUS_ENTRY`
  Exception message.
  `protected static final Object`
  `NULL`
  An object for masking null
  `protected static final String`
  `REMOVE_INVALID`
  Exception message.
  `protected static final String`
  `SETVALUE_INVALID`
  Exception message.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractHashedMap()`
  Constructor only used in deserialization, do not use otherwise.
  `protected`
  `AbstractHashedMap(int initialCapacity)`
  Constructs a new, empty map with the specified initial capacity and default load factor.
  `protected`
  `AbstractHashedMap(int initialCapacity, float loadFactor)`
  Constructs a new, empty map with the specified initial capacity and load factor.
  `protected`
  `AbstractHashedMap(int initialCapacity, float loadFactor, int threshold)`
  Constructor which performs no validation on the passed in parameters.
  `protected`
  `AbstractHashedMap(Map<? extends K,? extends V> map)`
  Constructor copying elements from another map.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addEntry(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex)`
  Adds an entry into this map.
  `protected void`
  `addMapping(int hashIndex, int hashCode, K key, V value)`
  Adds a new key-value mapping into this map.
  `protected int`
  `calculateNewCapacity(int proposedCapacity)`
  Calculates the new capacity of the map.
  `protected int`
  `calculateThreshold(int newCapacity, float factor)`
  Calculates the new threshold of the map, where it will be resized.
  `protected void`
  `checkCapacity()`
  Checks the capacity of the map and enlarges it if necessary.
  `void`
  `clear()`
  Clears the map, resetting the size to zero and nullifying references to avoid garbage collection issues.
  `protected AbstractHashedMap<K,V>`
  `clone()`
  Clones the map without cloning the keys or values.
  `boolean`
  `containsKey(Object key)`
  Checks whether the map contains the specified key.
  `boolean`
  `containsValue(Object value)`
  Checks whether the map contains the specified value.
  `protected Object`
  `convertKey(Object key)`
  Converts input keys to another object for storage in the map.
  `protected AbstractHashedMap.HashEntry<K,V>`
  `createEntry(AbstractHashedMap.HashEntry<K,V> next, int hashCode, K key, V value)`
  Creates an entry to store the key-value data.
  `protected Iterator<Map.Entry<K,V>>`
  `createEntrySetIterator()`
  Creates an entry set iterator.
  `protected Iterator<K>`
  `createKeySetIterator()`
  Creates a key set iterator.
  `protected Iterator<V>`
  `createValuesIterator()`
  Creates a values iterator.
  `protected void`
  `destroyEntry(AbstractHashedMap.HashEntry<K,V> entry)`
  Kills an entry ready for the garbage collector.
  `protected void`
  `doReadObject(ObjectInputStream in)`
  Reads the map data from the stream.
  `protected void`
  `doWriteObject(ObjectOutputStream out)`
  Writes the map data to the stream.
  `protected void`
  `ensureCapacity(int newCapacity)`
  Changes the size of the data structure to the capacity proposed.
  `protected int`
  `entryHashCode(AbstractHashedMap.HashEntry<K,V> entry)`
  Gets the `hashCode` field from a `HashEntry`.
  `protected K`
  `entryKey(AbstractHashedMap.HashEntry<K,V> entry)`
  Gets the `key` field from a `HashEntry`.
  `protected AbstractHashedMap.HashEntry<K,V>`
  `entryNext(AbstractHashedMap.HashEntry<K,V> entry)`
  Gets the `next` field from a `HashEntry`.
  `Set<Map.Entry<K,V>>`
  `entrySet()`
  Gets the entrySet view of the map.
  `protected V`
  `entryValue(AbstractHashedMap.HashEntry<K,V> entry)`
  Gets the `value` field from a `HashEntry`.
  `boolean`
  `equals(Object obj)`
  Compares this map with another.
  `V`
  `get(Object key)`
  Gets the value mapped to the key specified.
  `protected AbstractHashedMap.HashEntry<K,V>`
  `getEntry(Object key)`
  Gets the entry mapped to the key specified.
  `protected int`
  `hash(Object key)`
  Gets the hash code for the key specified.
  `int`
  `hashCode()`
  Gets the standard Map hashCode.
  `protected int`
  `hashIndex(int hashCode, int dataSize)`
  Gets the index into the data storage for the hashCode specified.
  `protected void`
  `init()`
  Initialize subclasses during construction, cloning or deserialization.
  `boolean`
  `isEmpty()`
  Checks whether the map is currently empty.
  `protected boolean`
  `isEqualKey(Object key1, Object key2)`
  Compares two keys, in internal converted form, to see if they are equal.
  `protected boolean`
  `isEqualValue(Object value1, Object value2)`
  Compares two values, in external form, to see if they are equal.
  `Set<K>`
  `keySet()`
  Gets the keySet view of the map.
  `MapIterator<K,V>`
  `mapIterator()`
  Gets an iterator over the map.
  `V`
  `put(K key, V value)`
  Puts a key-value mapping into this map.
  `void`
  `putAll(Map<? extends K,? extends V> map)`
  Puts all the values from the specified map into this map.
  `V`
  `remove(Object key)`
  Removes the specified mapping from this map.
  `protected void`
  `removeEntry(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex, AbstractHashedMap.HashEntry<K,V> previous)`
  Removes an entry from the chain stored in a particular index.
  `protected void`
  `removeMapping(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex, AbstractHashedMap.HashEntry<K,V> previous)`
  Removes a mapping from the map.
  `protected void`
  `reuseEntry(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex, int hashCode, K key, V value)`
  Reuses an existing key-value mapping, storing completely new data.
  `int`
  `size()`
  Gets the size of the map.
  `String`
  `toString()`
  Gets the map as a String.
  `protected void`
  `updateEntry(AbstractHashedMap.HashEntry<K,V> entry, V newValue)`
  Updates an existing key-value mapping to change the value.
  `Collection<V>`
  `values()`
  Gets the values view of the map.

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- ## Field Details

  - ### NO_NEXT_ENTRY

    protected static final String NO_NEXT_ENTRY
    Exception message.
    See Also:
      - Constant Field Values

  - ### NO_PREVIOUS_ENTRY

    protected static final String NO_PREVIOUS_ENTRY
    Exception message.
    See Also:
      - Constant Field Values

  - ### REMOVE_INVALID

    protected static final String REMOVE_INVALID
    Exception message.
    See Also:
      - Constant Field Values

  - ### GETKEY_INVALID

    protected static final String GETKEY_INVALID
    Exception message.
    See Also:
      - Constant Field Values

  - ### GETVALUE_INVALID

    protected static final String GETVALUE_INVALID
    Exception message.
    See Also:
      - Constant Field Values

  - ### SETVALUE_INVALID

    protected static final String SETVALUE_INVALID
    Exception message.
    See Also:
      - Constant Field Values

  - ### DEFAULT_CAPACITY

    protected static final int DEFAULT_CAPACITY
    The default capacity to use
    See Also:
      - Constant Field Values

  - ### DEFAULT_THRESHOLD

    protected static final int DEFAULT_THRESHOLD
    The default threshold to use
    See Also:
      - Constant Field Values

  - ### DEFAULT_LOAD_FACTOR

    protected static final float DEFAULT_LOAD_FACTOR
    The default load factor to use
    See Also:
      - Constant Field Values

  - ### MAXIMUM_CAPACITY

    protected static final int MAXIMUM_CAPACITY
    The maximum capacity allowed
    See Also:
      - Constant Field Values

  - ### NULL

    protected static final Object NULL
    An object for masking null

- ## Constructor Details

  - ### AbstractHashedMap

    protected AbstractHashedMap()
    Constructor only used in deserialization, do not use otherwise.

  - ### AbstractHashedMap

    protected AbstractHashedMap(int initialCapacity)
    Constructs a new, empty map with the specified initial capacity and default load factor.
    Parameters:
      `initialCapacity` - the initial capacity
    Throws:
      `IllegalArgumentException` - if the initial capacity is negative

  - ### AbstractHashedMap

    protected AbstractHashedMap(int initialCapacity, float loadFactor)
    Constructs a new, empty map with the specified initial capacity and load factor.
    Parameters:
      `initialCapacity` - the initial capacity
      `loadFactor` - the load factor
    Throws:
      `IllegalArgumentException` - if the initial capacity is negative
      `IllegalArgumentException` - if the load factor is less than or equal to zero

  - ### AbstractHashedMap

    protected AbstractHashedMap(int initialCapacity, float loadFactor, int threshold)
    Constructor which performs no validation on the passed in parameters.
    Parameters:
      `initialCapacity` - the initial capacity, must be a power of two
      `loadFactor` - the load factor, must be > 0.0f and generally < 1.0f
      `threshold` - the threshold, must be sensible

  - ### AbstractHashedMap

    protected AbstractHashedMap(Map<? extends K,? extends V> map)
    Constructor copying elements from another map.
    Parameters:
      `map` - the map to copy
    Throws:
      `NullPointerException` - if the map is null

- ## Method Details

  - ### addEntry

    protected void addEntry(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex)
    Adds an entry into this map.

    This implementation adds the entry to the data storage table. Subclasses could override to handle changes to the map.

    Parameters:
      `entry` - the entry to add
      `hashIndex` - the index into the data array to store at

  - ### addMapping

    protected void addMapping(int hashIndex, int hashCode, K key, V value)
    Adds a new key-value mapping into this map.

    This implementation calls `createEntry()`, `addEntry()` and `checkCapacity()`. It also handles changes to `modCount` and `size`. Subclasses could override to fully control adds to the map.

    Parameters:
      `hashIndex` - the index into the data array to store at
      `hashCode` - the hash code of the key to add
      `key` - the key to add
      `value` - the value to add

  - ### calculateNewCapacity

    protected int calculateNewCapacity(int proposedCapacity)
    Calculates the new capacity of the map. This implementation normalizes the capacity to a power of two.
    Parameters:
      `proposedCapacity` - the proposed capacity
    Returns:
      the normalized new capacity

  - ### calculateThreshold

    protected int calculateThreshold(int newCapacity, float factor)
    Calculates the new threshold of the map, where it will be resized. This implementation uses the load factor.
    Parameters:
      `newCapacity` - the new capacity
      `factor` - the load factor
    Returns:
      the new resize threshold

  - ### checkCapacity

    protected void checkCapacity()
    Checks the capacity of the map and enlarges it if necessary.

    This implementation uses the threshold to check if the map needs enlarging

  - ### clear

    public void clear()
    Clears the map, resetting the size to zero and nullifying references to avoid garbage collection issues.
    Specified by:
      `clear` in interface `Map<K,V>`
    Specified by:
      `clear` in interface `Put<K,V>`
    Overrides:
      `clear` in class `AbstractMap<K,V>`
    See Also:
      - `Map.clear()`

  - ### clone

    protected AbstractHashedMap<K,V> clone()
    Clones the map without cloning the keys or values.

    To implement `clone()`, a subclass must implement the `Cloneable` interface and make this method public.

    Overrides:
      `clone` in class `AbstractMap<K,V>`
    Returns:
      a shallow clone
    Throws:
      `InternalError` - if `AbstractMap.clone()` failed

  - ### containsKey

    public boolean containsKey(Object key)
    Checks whether the map contains the specified key.
    Specified by:
      `containsKey` in interface `Get<K,V>`
    Specified by:
      `containsKey` in interface `Map<K,V>`
    Overrides:
      `containsKey` in class `AbstractMap<K,V>`
    Parameters:
      `key` - the key to search for
    Returns:
      true if the map contains the key
    See Also:
      - `Map.containsKey(Object)`

  - ### containsValue

    public boolean containsValue(Object value)
    Checks whether the map contains the specified value.
    Specified by:
      `containsValue` in interface `Get<K,V>`
    Specified by:
      `containsValue` in interface `Map<K,V>`
    Overrides:
      `containsValue` in class `AbstractMap<K,V>`
    Parameters:
      `value` - the value to search for
    Returns:
      true if the map contains the value
    See Also:
      - `Map.containsValue(Object)`

  - ### convertKey

    protected Object convertKey(Object key)
    Converts input keys to another object for storage in the map. This implementation masks nulls. Subclasses can override this to perform alternate key conversions.

    The reverse conversion can be changed, if required, by overriding the getKey() method in the hash entry.

    Parameters:
      `key` - the key convert
    Returns:
      the converted key

  - ### createEntry

    protected AbstractHashedMap.HashEntry<K,V> createEntry(AbstractHashedMap.HashEntry<K,V> next, int hashCode, K key, V value)
    Creates an entry to store the key-value data.

    This implementation creates a new HashEntry instance. Subclasses can override this to return a different storage class, or implement caching.

    Parameters:
      `next` - the next entry in sequence
      `hashCode` - the hash code to use
      `key` - the key to store
      `value` - the value to store
    Returns:
      the newly created entry

  - ### createEntrySetIterator

    protected Iterator<Map.Entry<K,V>> createEntrySetIterator()
    Creates an entry set iterator. Subclasses can override this to return iterators with different properties.
    Returns:
      the entrySet iterator

  - ### createKeySetIterator

    protected Iterator<K> createKeySetIterator()
    Creates a key set iterator. Subclasses can override this to return iterators with different properties.
    Returns:
      the keySet iterator

  - ### createValuesIterator

    protected Iterator<V> createValuesIterator()
    Creates a values iterator. Subclasses can override this to return iterators with different properties.
    Returns:
      the values iterator

  - ### destroyEntry

    protected void destroyEntry(AbstractHashedMap.HashEntry<K,V> entry)
    Kills an entry ready for the garbage collector.

    This implementation prepares the HashEntry for garbage collection. Subclasses can override this to implement caching (override clear as well).

    Parameters:
      `entry` - the entry to destroy

  - ### doReadObject

    protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException
    Reads the map data from the stream. This method must be overridden if a subclass must be setup before `put()` is used.

    Serialization is not one of the JDK's nicest topics. Normal serialization will initialize the superclass before the subclass. Sometimes however, this isn't what you want, as in this case the `put()` method on read can be affected by subclass state.

    The solution adopted here is to deserialize the state data of this class in this protected method. This method must be called by the `readObject()` of the first serializable subclass.

    Subclasses may override if the subclass has a specific field that must be present before `put()` or `calculateThreshold()` will work correctly.

    Parameters:
      `in` - the input stream
    Throws:
      `IOException` - if an error occurs while reading from the stream
      `ClassNotFoundException` - if an object read from the stream cannot be loaded

  - ### doWriteObject

    protected void doWriteObject(ObjectOutputStream out) throws IOException
    Writes the map data to the stream. This method must be overridden if a subclass must be setup before `put()` is used.

    Serialization is not one of the JDK's nicest topics. Normal serialization will initialize the superclass before the subclass. Sometimes however, this isn't what you want, as in this case the `put()` method on read can be affected by subclass state.

    The solution adopted here is to serialize the state data of this class in this protected method. This method must be called by the `writeObject()` of the first serializable subclass.

    Subclasses may override if they have a specific field that must be present on read before this implementation will work. Generally, the read determines what must be serialized here, if anything.

    Parameters:
      `out` - the output stream
    Throws:
      `IOException` - if an error occurs while writing to the stream

  - ### ensureCapacity

    protected void ensureCapacity(int newCapacity)
    Changes the size of the data structure to the capacity proposed.
    Parameters:
      `newCapacity` - the new capacity of the array (a power of two, less or equal to max)

  - ### entryHashCode

    protected int entryHashCode(AbstractHashedMap.HashEntry<K,V> entry)
    Gets the `hashCode` field from a `HashEntry`. Used in subclasses that have no visibility of the field.
    Parameters:
      `entry` - the entry to query, must not be null
    Returns:
      the `hashCode` field of the entry
    Throws:
      `NullPointerException` - if the entry is null
    Since:
      3.1

  - ### entryKey

    protected K entryKey(AbstractHashedMap.HashEntry<K,V> entry)
    Gets the `key` field from a `HashEntry`. Used in subclasses that have no visibility of the field.
    Parameters:
      `entry` - the entry to query, must not be null
    Returns:
      the `key` field of the entry
    Throws:
      `NullPointerException` - if the entry is null
    Since:
      3.1

  - ### entryNext

    protected AbstractHashedMap.HashEntry<K,V> entryNext(AbstractHashedMap.HashEntry<K,V> entry)
    Gets the `next` field from a `HashEntry`. Used in subclasses that have no visibility of the field.
    Parameters:
      `entry` - the entry to query, must not be null
    Returns:
      the `next` field of the entry
    Throws:
      `NullPointerException` - if the entry is null
    Since:
      3.1

  - ### entrySet

    public Set<Map.Entry<K,V>> entrySet()
    Gets the entrySet view of the map. Changes made to the view affect this map. To simply iterate through the entries, use `mapIterator()`.
    Specified by:
      `entrySet` in interface `Get<K,V>`
    Specified by:
      `entrySet` in interface `Map<K,V>`
    Specified by:
      `entrySet` in class `AbstractMap<K,V>`
    Returns:
      the entrySet view
    See Also:
      - `Map.entrySet()`

  - ### entryValue

    protected V entryValue(AbstractHashedMap.HashEntry<K,V> entry)
    Gets the `value` field from a `HashEntry`. Used in subclasses that have no visibility of the field.
    Parameters:
      `entry` - the entry to query, must not be null
    Returns:
      the `value` field of the entry
    Throws:
      `NullPointerException` - if the entry is null
    Since:
      3.1

  - ### equals

    public boolean equals(Object obj)
    Compares this map with another.
    Specified by:
      `equals` in interface `Map<K,V>`
    Overrides:
      `equals` in class `AbstractMap<K,V>`
    Parameters:
      `obj` - the object to compare to
    Returns:
      true if equal

  - ### get

    public V get(Object key)
    Gets the value mapped to the key specified.
    Specified by:
      `get` in interface `Get<K,V>`
    Specified by:
      `get` in interface `Map<K,V>`
    Overrides:
      `get` in class `AbstractMap<K,V>`
    Parameters:
      `key` - the key
    Returns:
      the mapped value, null if no match
    See Also:
      - `Map.get(Object)`

  - ### getEntry

    protected AbstractHashedMap.HashEntry<K,V> getEntry(Object key)
    Gets the entry mapped to the key specified.

    This method exists for subclasses that may need to perform a multi-step process accessing the entry. The public methods in this class don't use this method to gain a small performance boost.

    Parameters:
      `key` - the key
    Returns:
      the entry, null if no match

  - ### hash

    protected int hash(Object key)
    Gets the hash code for the key specified. This implementation uses the additional hashing routine from JDK1.4. Subclasses can override this to return alternate hash codes.
    Parameters:
      `key` - the key to get a hash code for
    Returns:
      the hash code

  - ### hashCode

    public int hashCode()
    Gets the standard Map hashCode.
    Specified by:
      `hashCode` in interface `Map<K,V>`
    Overrides:
      `hashCode` in class `AbstractMap<K,V>`
    Returns:
      the hash code defined in the Map interface

  - ### hashIndex

    protected int hashIndex(int hashCode, int dataSize)
    Gets the index into the data storage for the hashCode specified. This implementation uses the least significant bits of the hashCode. Subclasses can override this to return alternate bucketing.
    Parameters:
      `hashCode` - the hash code to use
      `dataSize` - the size of the data to pick a bucket from
    Returns:
      the bucket index

  - ### init

    protected void init()
    Initialize subclasses during construction, cloning or deserialization.

  - ### isEmpty

    public boolean isEmpty()
    Checks whether the map is currently empty.
    Specified by:
      `isEmpty` in interface `Get<K,V>`
    Specified by:
      `isEmpty` in interface `Map<K,V>`
    Overrides:
      `isEmpty` in class `AbstractMap<K,V>`
    Returns:
      true if the map is currently size zero
    See Also:
      - `Map.isEmpty()`

  - ### isEqualKey

    protected boolean isEqualKey(Object key1, Object key2)
    Compares two keys, in internal converted form, to see if they are equal. This implementation uses the equals method and assumes neither key is null. Subclasses can override this to match differently.
    Parameters:
      `key1` - the first key to compare passed in from outside
      `key2` - the second key extracted from the entry via `entry.key`
    Returns:
      true if equal

  - ### isEqualValue

    protected boolean isEqualValue(Object value1, Object value2)
    Compares two values, in external form, to see if they are equal. This implementation uses the equals method and assumes neither value is null. Subclasses can override this to match differently.
    Parameters:
      `value1` - the first value to compare passed in from outside
      `value2` - the second value extracted from the entry via `getValue()`
    Returns:
      true if equal

  - ### keySet

    public Set<K> keySet()
    Gets the keySet view of the map. Changes made to the view affect this map. To simply iterate through the keys, use `mapIterator()`.
    Specified by:
      `keySet` in interface `Get<K,V>`
    Specified by:
      `keySet` in interface `Map<K,V>`
    Overrides:
      `keySet` in class `AbstractMap<K,V>`
    Returns:
      the keySet view
    See Also:
      - `Map.keySet()`

  - ### mapIterator

    public MapIterator<K,V> mapIterator()
    Gets an iterator over the map. Changes made to the iterator affect this map.

    A MapIterator returns the keys in the map. It also provides convenient methods to get the key and value, and set the value. It avoids the need to create an entrySet/keySet/values object. It also avoids creating the Map.Entry object.

    Specified by:
      `mapIterator` in interface `IterableGet<K,V>`
    Returns:
      the map iterator

  - ### put

    public V put(K key, V value)
    Puts a key-value mapping into this map.
    Specified by:
      `put` in interface `Map<K,V>`
    Specified by:
      `put` in interface `Put<K,V>`
    Overrides:
      `put` in class `AbstractMap<K,V>`
    Parameters:
      `key` - the key to add
      `value` - the value to add
    Returns:
      the value previously mapped to this key, null if none
    See Also:
      - `Map.put(Object, Object)`

  - ### putAll

    public void putAll(Map<? extends K,? extends V> map)
    Puts all the values from the specified map into this map.

    This implementation iterates around the specified map and uses `put(Object, Object)`.

    Specified by:
      `putAll` in interface `Map<K,V>`
    Specified by:
      `putAll` in interface `Put<K,V>`
    Overrides:
      `putAll` in class `AbstractMap<K,V>`
    Parameters:
      `map` - the map to add
    Throws:
      `NullPointerException` - if the map is null
    See Also:
      - `Map.putAll(Map)`

  - ### remove

    public V remove(Object key)
    Removes the specified mapping from this map.
    Specified by:
      `remove` in interface `Get<K,V>`
    Specified by:
      `remove` in interface `Map<K,V>`
    Overrides:
      `remove` in class `AbstractMap<K,V>`
    Parameters:
      `key` - the mapping to remove
    Returns:
      the value mapped to the removed key, null if key not in map
    See Also:
      - `Map.remove(Object)`

  - ### removeEntry

    protected void removeEntry(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex, AbstractHashedMap.HashEntry<K,V> previous)
    Removes an entry from the chain stored in a particular index.

    This implementation removes the entry from the data storage table. The size is not updated. Subclasses could override to handle changes to the map.

    Parameters:
      `entry` - the entry to remove
      `hashIndex` - the index into the data structure
      `previous` - the previous entry in the chain

  - ### removeMapping

    protected void removeMapping(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex, AbstractHashedMap.HashEntry<K,V> previous)
    Removes a mapping from the map.

    This implementation calls `removeEntry()` and `destroyEntry()`. It also handles changes to `modCount` and `size`. Subclasses could override to fully control removals from the map.

    Parameters:
      `entry` - the entry to remove
      `hashIndex` - the index into the data structure
      `previous` - the previous entry in the chain

  - ### reuseEntry

    protected void reuseEntry(AbstractHashedMap.HashEntry<K,V> entry, int hashIndex, int hashCode, K key, V value)
    Reuses an existing key-value mapping, storing completely new data.

    This implementation sets all the data fields on the entry. Subclasses could populate additional entry fields.

    Parameters:
      `entry` - the entry to update, not null
      `hashIndex` - the index in the data array
      `hashCode` - the hash code of the key to add
      `key` - the key to add
      `value` - the value to add

  - ### size

    public int size()
    Gets the size of the map.
    Specified by:
      `size` in interface `Get<K,V>`
    Specified by:
      `size` in interface `Map<K,V>`
    Overrides:
      `size` in class `AbstractMap<K,V>`
    Returns:
      the size
    See Also:
      - `Map.size()`

  - ### toString

    public String toString()
    Gets the map as a String.
    Overrides:
      `toString` in class `AbstractMap<K,V>`
    Returns:
      a string version of the map

  - ### updateEntry

    protected void updateEntry(AbstractHashedMap.HashEntry<K,V> entry, V newValue)
    Updates an existing key-value mapping to change the value.

    This implementation calls `setValue()` on the entry. Subclasses could override to handle changes to the map.

    Parameters:
      `entry` - the entry to update
      `newValue` - the new value to store

  - ### values

    public Collection<V> values()
    Gets the values view of the map. Changes made to the view affect this map. To simply iterate through the values, use `mapIterator()`.
    Specified by:
      `values` in interface `Get<K,V>`
    Specified by:
      `values` in interface `Map<K,V>`
    Overrides:
      `values` in class `AbstractMap<K,V>`
    Returns:
      the values view
    See Also:
      - `Map.values()`