PersistentMap<K, V> abstract class
An immutable map, binding keys of type K
to values of type V
. Null values
are supported but null keys are not.
In all the examples below {k1: v1, k2: v2, ...}
is a shorthand for
PersistentMap.fromMap({k1: v1, k2: v2, ...})
.
abstract class PersistentMap<K, V> { /** Creates an empty [PersistentMap] using its default implementation. */ factory PersistentMap() => new _EmptyMap<K, V>(); /** * Creates an immutable copy of [map] using the default implementation of * [PersistentMap]. */ factory PersistentMap.fromMap(Map<K, V> map) { PersistentMap<K, V> result = new _EmptyMap<K, V>(); map.forEach((K key, V value) { result = result.insert(key, value); }); return result; } /// True when [this] is empty. bool get isEmpty; /** * Returns a new map identical to [this] except that it binds [key] to * [value]. * * If [key] was bound to some [oldvalue] in [this], it is nevertheless bound * to [value] in the new map. If [key] was bound to some [oldvalue] in * [this] and if [combine] is provided then [key] it is bound to * [combine(oldvalue, value)] in the new map. * * {'a': 1}.insert('b', 2) == {'a': 1, 'b', 2} * {'a': 1, 'b': 2}.insert('b', 3) == {'a': 3, 'b', 3} * {'a': 1, 'b': 2}.insert('b', 3, (x,y) => x - y) == {'a': 3, 'b', -1} */ PersistentMap<K, V> insert(K key, V value, [V combine(V oldvalue, V newvalue)]); /** * Returns a new map identical to [this] except that it doesn't bind [key] * anymore. * * {'a': 1, 'b': 2}.delete('b') == {'a': 1} * {'a': 1}.delete('b') == {'a': 1} */ PersistentMap<K, V> delete(K key); /** * Looks up the value possibly bound to [key] in [this]. Returns * [Option.some(value)] if it exists, [Option.none()] otherwise. * * {'a': 1}.lookup('b') == Option.none() * {'a': 1, 'b': 2}.lookup('b') == Option.some(2) */ Option<V> lookup(K key); /** * Evaluates [f(key, value)] for each ([key], [value]) pair in [this]. */ void forEach(f(K key, V value)); /** * Returns a new map identical to [this] except that the value it possibly * binds to [key] has been adjusted by [update]. * * {'a': 1, 'b': 2}.adjust('b', (x) => x + 1) == {'a', 1, 'b', 3} * {'a': 1}.adjust('b', (x) => x + 1) == {'a', 1} */ PersistentMap<K, V> adjust(K key, V update(V value)); /** * Returns a new map identical to [this] where each value has been updated by * [f]. * * {'a': 1, 'b': 2}.map((x) => x + 1) == {'a', 2, 'b', 3} * {}.map((x) => x + 1) == {} */ PersistentMap mapValues(f(V value)); /** * The number of (key, value) pairs in [this]. * * {}.length == 0 * {'a': 1}.length == 1 * {'a': 1, 'b': 2}.length == 2 */ int get length; /** * Returns a new map whose (key, value) pairs are the union of those of [this] * and [other]. * * The union is right-biased: if a key is present in both [this] and [other], * the value from [other] is retained. If [combine] is provided, the retained * value for a [key] present in both [this] and [other] is then * [combine(leftvalue, rightvalue)] where [leftvalue] is the value bound to * [key] in [this] and [rightvalue] is the one bound to [key] in [other]. * * {'a': 1}.union({'b': 2}) == {'a': 1, 'b': 2} * {'a': 1}.union({'a': 3, 'b': 2}) == {'a': 3, 'b': 2} * {'a': 1}.union({'a': 3, 'b': 2}, (x,y) => x + y) == {'a': 4, 'b': 2} * * Note that [union] is commutative if and only if [combine] is provided and * if it is commutative. */ PersistentMap<K, V> union(PersistentMap<K, V> other, [V combine(V left, V right)]); /** * Returns a new map whose (key, value) pairs are the intersection of those of * [this] and [other]. * * The intersection is right-biased: values from [other] are retained. If * [combine] is provided, the retained value for a [key] present in both * [this] and [other] is then [combine(leftvalue, rightvalue)] where * [leftvalue] is the value bound to [key] in [this] and [rightvalue] is the * one bound to [key] in [other]. * * {'a': 1}.intersection({'b': 2}) == {} * {'a': 1}.intersection({'a': 3, 'b': 2}) == {'a': 3} * {'a': 1}.intersection({'a': 3, 'b': 2}, (x,y) => x + y) == {'a': 4} * * Note that [intersection] is commutative if and only if [combine] is * provided and if it is commutative. */ PersistentMap<K, V> intersection(PersistentMap<K, V> other, [V combine(V left, V right)]); /** * Returns a mutable copy of [this]. */ Map<K, V> toMap(); }
Subclasses
Constructors
factory PersistentMap() #
Creates an empty PersistentMap using its default implementation.
factory PersistentMap() => new _EmptyMap<K, V>();
factory PersistentMap.fromMap(Map<K, V> map) #
Creates an immutable copy of map using the default implementation of PersistentMap.
factory PersistentMap.fromMap(Map<K, V> map) { PersistentMap<K, V> result = new _EmptyMap<K, V>(); map.forEach((K key, V value) { result = result.insert(key, value); }); return result; }
Properties
final bool isEmpty #
True when this
is empty.
bool get isEmpty;
final int length #
The number of (key, value) pairs in this
.
{}.length == 0
{'a': 1}.length == 1
{'a': 1, 'b': 2}.length == 2
int get length;
Methods
abstract PersistentMap<K, V> adjust(K key, V update(V value)) #
Returns a new map identical to this
except that the value it possibly
binds to
key has been adjusted by
update.
{'a': 1, 'b': 2}.adjust('b', (x) => x + 1) == {'a', 1, 'b', 3}
{'a': 1}.adjust('b', (x) => x + 1) == {'a', 1}
abstract PersistentMap<K, V> delete(K key) #
Returns a new map identical to this
except that it doesn't bind
key
anymore.
{'a': 1, 'b': 2}.delete('b') == {'a': 1}
{'a': 1}.delete('b') == {'a': 1}
abstract void forEach(f(K key, V value)) #
Evaluates f(key, value)
for each (key
, value
) pair in this
.
abstract PersistentMap<K, V> insert(K key, V value, [V combine(V oldvalue, V newvalue)]) #
Returns a new map identical to this
except that it binds
key to
value.
If
key was bound to some oldvalue
in this
, it is nevertheless bound
to
value in the new map. If
key was bound to some oldvalue
in
this
and if
combine is provided then
key it is bound to
combine(oldvalue, value)
in the new map.
{'a': 1}.insert('b', 2) == {'a': 1, 'b', 2}
{'a': 1, 'b': 2}.insert('b', 3) == {'a': 3, 'b', 3}
{'a': 1, 'b': 2}.insert('b', 3, (x,y) => x - y) == {'a': 3, 'b', -1}
abstract PersistentMap<K, V> intersection(PersistentMap<K, V> other, [V combine(V left, V right)]) #
Returns a new map whose (key, value) pairs are the intersection of those of
this
and
other.
The intersection is right-biased: values from
other are retained. If
combine is provided, the retained value for a key
present in both
this
and
other is then combine(leftvalue, rightvalue)
where
leftvalue
is the value bound to key
in this
and rightvalue
is the
one bound to key
in
other.
{'a': 1}.intersection({'b': 2}) == {}
{'a': 1}.intersection({'a': 3, 'b': 2}) == {'a': 3}
{'a': 1}.intersection({'a': 3, 'b': 2}, (x,y) => x + y) == {'a': 4}
Note that intersection is commutative if and only if combine is provided and if it is commutative.
abstract Option<V> lookup(K key) #
Looks up the value possibly bound to
key in this
. Returns
Option.some(value)
if it exists, Option.none()
otherwise.
{'a': 1}.lookup('b') == Option.none()
{'a': 1, 'b': 2}.lookup('b') == Option.some(2)
abstract PersistentMap mapValues(f(V value)) #
Returns a new map identical to this
where each value has been updated by
f.
{'a': 1, 'b': 2}.map((x) => x + 1) == {'a', 2, 'b', 3}
{}.map((x) => x + 1) == {}
abstract PersistentMap<K, V> union(PersistentMap<K, V> other, [V combine(V left, V right)]) #
Returns a new map whose (key, value) pairs are the union of those of this
and
other.
The union is right-biased: if a key is present in both this
and
other,
the value from
other is retained. If
combine is provided, the retained
value for a key
present in both this
and
other is then
combine(leftvalue, rightvalue)
where leftvalue
is the value bound to
key
in this
and rightvalue
is the one bound to key
in
other.
{'a': 1}.union({'b': 2}) == {'a': 1, 'b': 2}
{'a': 1}.union({'a': 3, 'b': 2}) == {'a': 3, 'b': 2}
{'a': 1}.union({'a': 3, 'b': 2}, (x,y) => x + y) == {'a': 4, 'b': 2}
Note that union is commutative if and only if combine is provided and if it is commutative.