ImmutableOrderedMap<K, V> class

An immutable ordered map that maintains insertion order with key-based access and copy-on-write semantics.

This class provides an immutable wrapper around an ordered map where all mutating operations create new immutable instances rather than modifying the existing collection. It requires a toKey function to automatically generate keys from values, ensuring consistent key generation and management.

// Define a key extraction function
String userToKey(User user) => user.id;

final map = ImmutableOrderedMap<String, User>(toKey: userToKey);
map.assignAllOrdered([
  User(id: 'user1', name: 'Alice'),
  User(id: 'user2', name: 'Bob'),
  User(id: 'user3', name: 'Charlie'),
]);

print(map.orderedValues.map((u) => u.name)); // ['Alice', 'Bob', 'Charlie']
print(map['user2']?.name); // 'Bob'

// Immutable updates create new instances
final newMap = map..upsert('user4', User(id: 'user4', name: 'David'), putFirst: true);
print(newMap.orderedValues.map((u) => u.name)); // ['David', 'Alice', 'Bob', 'Charlie']

@ai Use this class in reactive programming contexts where immutability is required. The toKey function ensures consistent key generation from values.

Mixed-in types
Implementers
Available extensions

Constructors

ImmutableOrderedMap({OrderedMapToKeyFunction<K, V>? toKey})
Creates an immutable ordered map with the specified key extraction function.

Properties

first → K
The first element.
no setterinherited
firstOrNull → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The first element of this iterator, or null if the iterable is empty.
no setter
hashCode → int
The hash code for this object.
no setterinherited
indexed → Iterable<(int, T)>

Available on Iterable<T>, provided by the IterableExtensions extension

Pairs of elements of the indices and elements of this iterable.
no setter
isEmpty → bool
Whether this collection has no elements.
no setterinherited
isNotEmpty → bool
Whether this collection has at least one element.
no setterinherited
iterator → Iterator<K>
A new Iterator that allows iterating the elements of this Iterable.
no setteroverride
keys → List<K>
Returns an unmodifiable list of all keys in insertion order.
no setter
last → K
The last element.
no setterinherited
lastOrNull → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The last element of this iterable, or null if the iterable is empty.
no setter
length → int
The number of elements in this Iterable.
no setterinherited
nonNulls → Iterable<T>

Available on Iterable<T?>, provided by the NullableIterableExtensions extension

The non-null elements of this iterable.
no setter
orderedValues → List<V>
Returns an unmodifiable list of all values in insertion order.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
single → K
Checks that this iterable has only one element, and returns that element.
no setterinherited
singleOrNull → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The single element of this iterator, or null.
no setter
toJSIterable → JSIterable<T>

Available on Iterable<T>, provided by the IterableToJSIterable extension

A JSIterable wrapper that proxies to the Dart iterable API.
no setter
toKey → OrderedMapToKeyFunction<K, V>?
A function that converts values to their corresponding keys.
final
wait → Future<List<T>>

Available on Iterable<Future<T>>, provided by the FutureIterable extension

Waits for futures in parallel.
no setter

Methods

any(bool test(K element)) → bool
Checks whether any element of this iterable satisfies test.
inherited
asNameMap() → Map<String, T>

Available on Iterable<T>, provided by the EnumByName extension

Creates a map from the names of enum values to the values.
assignAll(Map<K, V> map) → void
Replaces all items in this collection with the provided map.
assignAllOrdered(Iterable<V> items) → void
Replaces all items in this collection with values from the provided items list.
byName(String name) → T

Available on Iterable<T>, provided by the EnumByName extension

Finds the enum value in this list with name name.
cast<R>() → Iterable<R>
A view of this iterable as an iterable of R instances.
inherited
clear() → void
Removes all mappings from this map.
contains(Object? element) → bool
Whether the collection contains an element equal to element.
inherited
containsKey(K key) → bool
Whether this map contains the specified key.
elementAt(int index) → K
Returns the indexth element.
inherited
elementAtOrNull(int index) → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The element at position index of this iterable, or null.
every(bool test(K element)) → bool
Checks whether every element of this iterable satisfies test.
inherited
expand<T>(Iterable<T> toElements(K element)) → Iterable<T>
Expands each element of this Iterable into zero or more elements.
inherited
firstWhere(bool test(K element), {K orElse()?}) → K
The first element that satisfies the given predicate test.
inherited
fold<T>(T initialValue, T combine(T previousValue, K element)) → T
Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
inherited
followedBy(Iterable<K> other) → Iterable<K>
Creates the lazy concatenation of this iterable and other.
inherited
forEach(void action(K element)) → void
Invokes action on each element of this iterable in iteration order.
inherited
join([String separator = ""]) → String
Converts each element to a String and concatenates the strings.
inherited
lastWhere(bool test(K element), {K orElse()?}) → K
The last element that satisfies the given predicate test.
inherited
map<T>(T toElement(K e)) → Iterable<T>
The current elements of this iterable modified by toElement.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
reduce(K combine(K value, K element)) → K
Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
inherited
remove(K key) → void
Removes the mapping for the specified key if it exists.
singleWhere(bool test(K element), {K orElse()?}) → K
The single element that satisfies test.
inherited
skip(int count) → Iterable<K>
Creates an Iterable that provides all but the first count elements.
inherited
skipWhile(bool test(K element)) → Iterable<K>
Creates an Iterable that skips leading elements while test is satisfied.
inherited
take(int count) → Iterable<K>
Creates a lazy iterable of the count first elements of this iterable.
inherited
takeWhile(bool test(K element)) → Iterable<K>
Creates a lazy iterable of the leading elements satisfying test.
inherited
toList({bool growable = true}) → List<K>
Creates a List containing the elements of this Iterable.
inherited
toSet() → Set<K>
Creates a Set containing the same elements as this iterable.
inherited
toString() → String
Returns a string representation of (some of) the elements of this.
inherited
update(K key, V update(V), {V ifAbsent()?}) → V
Updates the value associated with the specified key using the provided update function.
upsert(V value, {bool putFirst = false, K? key}) → void
Inserts or updates the mapping for the specified key and value.
upsertAll(Iterable<V> values, {bool putFirst = false, K? toKey(V)?}) → void
Inserts or updates multiple mappings from the provided values iterable.
where(bool test(K element)) → Iterable<K>
Creates a new lazy Iterable with all elements that satisfy the predicate test.
inherited
whereType<T>() → Iterable<R>
Creates a new lazy Iterable with all elements that have type T.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited
operator [](K key) → V?
Retrieves the value associated with the specified key.
operator []=(K key, V value) → void
Inserts or updates the mapping for the specified key and value.