HashMap<K, V> constructor

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.

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 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 it does change, the result is unpredictable.

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 hashcode 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.