IndexMap<K, V> class abstract final Collections

A hash map where element iteration order is independent of their hash codes.

Iteration Order

The keys, K, have a consistent order that is determined by the sequence of operator[]= and remove calls (or similar operations):

final map = IndexMap<int, String>();
map[1] = 'a';
map[2] = 'b';
map[3] = 'c';
map.remove(2);
print(map); // {1: 'a', 3: 'c'}

Unlike LinkedHashMap, remove calls (and similar operations) shift the iteration order; a removed element is swapped with the last element in the map, and then removed:

final map = IndexMap<int, String>();
map[1] = 'a';
map[2] = 'b';
map[3] = 'c';
map.remove(1);
print(map); // {3: 'c', 2: 'b'}

Index Access

Like IndexSet, IndexMap provides an additional set of operators.

entryAt returns a specialized key-value pair type, IndexedMapEntry. A logical extension to MapEntry, IndexedMapEntry not only contains the key and value, but also the index of the element in the iteration sequence:

final map = IndexMap<String, bool>();
map['a'] = true;
map['b'] = false;

final entry = map.getEntryAt(1);
print(entry.key); // 'b'
print(entry.value); // false
print(entry.index); // 1

However, unlike even Map, IndexMap can return an IndexedMapEntry even if the key is not yet present in the map, giving a powerful and performant way to insert elements at a specific index, using entryOf and IndexedMapEntry.setOrUpdate.

final map = IndexMap<String, bool>();
map['a'] = true;

final a = map.tryGet('a');
print(a.isPresent); // true
print(a.key); // 'a'
print(a.value); // true
a.value = false;
a.setOrUpdate(false);
print(map); // {a: false}

final b = map.tryGet('b');
print(b.isAbsent); // false
print(b.key); // 'b'
print(b.value); // n

b.setOrUpdate(false);
print(map); // {a: false, b: false}

Performance

If you want the properties of IndexMap, or its strongest performance characteristics fit your workload, it might be the fastest pure Dart Map implementation available; for example package:sector uses it internally for its graph search algorithms.

IndexMap derives some performance facts from how it is constructed:

1. Iteration is as fast as a List (~2-3x faster than dart:collection).
2. Removals are nearly as fast as HashMap (~300-400x faster).
3. Creation is ~2x slower than HashMap, 5x faster than LinkedHashMap.