description

# HashMap<K, V> constructor

HashMap<K, V>({

1. bool equals(
   1. K,
   2. K
   )?,
2. int hashCode(
   1. K
   )?,
3. bool isValidKey(
   1. dynamic
   )?,

})

Creates an unordered hash-table based Map.

The created map is not ordered in any way. When iterating the keys or values, the iteration order is unspecified except that it will stay the same as long as the map isn't changed.

If `equals` is provided, it is used to compare the keys in the map with new keys. If `equals` is omitted, the key's own Object.== is used instead. The `equals` function must not change the map it's used as an equality for. If it does, the resulting behavior is unspecified.

Similarly, if `hashCode` is provided, it is used to produce a hash value for keys in order to place them in the map. If `hashCode` is omitted, the key's own Object.hashCode is used. The `hashCode` function must not change the map it's used as a hash code for. If it does, the resulting behavior is unspecified.

The used `equals` and `hashCode` method should always be consistent, so that if `equals(a, b)`, then `hashCode(a) == hashCode(b)`. The hash of an object, or what it compares equal to, should not change while the object is a key in the map. If the hash code or equality of an object does change, the resulting behavior is unspecified.

If you supply one of `equals` and `hashCode`, you should generally also supply the other.

Some `equals` or `hashCode` functions might not work for all objects. If `isValidKey` is supplied, it's used to check a potential key which is not necessarily an instance of `K`, like the arguments to operator [], remove and containsKey, which are typed as `Object?`. If `isValidKey` returns `false`, for an object, the `equals` and `hashCode` functions are not called, and no key equal to that object is assumed to be in the map. The `isValidKey` function defaults to just testing if the object is an instance of `K`.

Example:

    HashMap<int,int>(equals: (int a, int b) => (b - a) % 5 == 0,
                     hashCode: (int e) => e % 5)

This example map does not need an `isValidKey` function to be passed. The default function accepts precisely `int` values, which can safely be passed to both the `equals` and `hashCode` functions.

If neither `equals`, `hashCode`, nor `isValidKey` is provided, the default `isValidKey` instead accepts all keys. The default equality and hash code operations are known to work on all objects.

Likewise, if `equals` is identical, `hashCode` is identityHashCode and `isValidKey` is omitted, the resulting map is identity based, and the `isValidKey` defaults to accepting all keys. Such a map can be created directly using HashMap.identity.

## Implementation

    external factory HashMap({
      bool Function(K, K)? equals,
      int Function(K)? hashCode,
      bool Function(dynamic)? isValidKey,
    });