std::maps
A Map<K, V> holds values under keys, written
{"ann" => 31, "bo" => 12}. It is immutable: Map.put and Map.remove
return a new map. A map keeps its entries in the order their keys were
first added, and every function here keeps that order. Two maps are ==
when they hold the same entries, in any order.
Map.get reads a key and returns a Maybe, since the key may be
missing. a + b is Map.merge(a, b): the right-hand map wins on a
shared key.
Import with import std::maps.
Exports
Section titled “Exports”Types
Map and Iter
Section titled “Map and Iter”A map iterates as its (key, value) pairs, so every
Iter function works on one. A function passed to
it takes one pair: Iter.each(ages, fn (name, age) -> ...).
Iter.filter and Iter.map give an Iter of pairs, and
Iter.to_map() collects it into a map. Map.map_values and
Map.map_keys change one half of each pair and keep the other.
Map.size is the number of entries, which the map keeps; Iter.count
returns the same.
type Map
Section titled “type Map”type Map<K, V>
An immutable map from keys of type K to values of type V, in the
order the keys were first added. a + b is Map.merge(a, b).
ages = {"ann" => 31, "bo" => 12, "cy" => 19}
// Iter.filter gives an Iter<(K, V)>; Iter.to_map collects it into a Map.
adults =
ages
|> Iter.filter(fn (_, age) -> age > 18)
|> Iter.to_map()
assert adults == {"ann" => 31, "cy" => 19}
assert Map.keys(adults) == ["ann", "cy"]
Map.get
Section titled “Map.get”fn get<K, V>(m: Map<K, V>, key: K) -> Maybe<V>
type function on Map
Gets a value by key. Returns Some(value) if the key is present, None
otherwise. When the program guarantees the key is there, as it does
for a key it took from the map itself, Map.get(m, key)! returns the
value and traps on a missing key.
assert Map.get({"a" => 1, "b" => 2}, "a") == Some(1)
assert Map.get({"a" => 1, "b" => 2}, "z") == None
assert Map.get({"a" => 1, "b" => 2}, "b")! == 2
Map.put
Section titled “Map.put”fn put<K, V>(m: Map<K, V>, key: K, value: V) -> Map<K, V>
type function on Map
Returns a new map with value under key. A new key goes at the
end; a key the map already holds keeps its place.
assert Map.put({"a" => 1}, "b", 2) == {"a" => 1, "b" => 2}
assert Map.put({"a" => 1}, "a", 9) == {"a" => 9}
Map.remove
Section titled “Map.remove”fn remove<K, V>(m: Map<K, V>, key: K) -> Map<K, V>
type function on Map
Returns a new map with the key removed, or the same map if the key is absent.
assert Map.remove({"a" => 1, "b" => 2}, "a") == {"b" => 2}
assert Map.remove({"a" => 1}, "z") == {"a" => 1}
Map.merge
Section titled “Map.merge”fn merge<K, V>(a: Map<K, V>, b: Map<K, V>) -> Map<K, V>
type function on Map
Merges two maps: a’s keys, then the keys only b holds. On a key
both hold, b’s value wins. a + b is the same call.
assert Map.merge({"a" => 1}, {"a" => 9, "b" => 2}) == {"a" => 9, "b" => 2}
Map.merge_with
Section titled “Map.merge_with”fn merge_with<K, V>(a: Map<K, V>, b: Map<K, V>, combine: (V, V) -> V) -> Map<K, V>
type function on Map
Merges two maps, combining the values of a key both hold:
combine(a_value, b_value) is its value in the result. A key only
one map holds keeps its value. The order is Map.merge’s: a’s
keys, then the keys only b holds, in b’s order.
assert Map.merge_with({"a" => 1, "b" => 2}, {"b" => 10, "c" => 3}, Int.add) == {
"a" => 1,
"b" => 12,
"c" => 3,
}
assert Map.merge_with({"x" => [1]}, {"x" => [2]}, fn a, b -> a + b) == {"x" => [1, 2]}
Map.update
Section titled “Map.update”fn update<K, V>(m: Map<K, V>, key: K, default: V, f: (V) -> V) -> Map<K, V>
type function on Map
Changes the value under key to f of it. When key is missing,
f is applied to default, and the key is added at the end. So
default is the value a missing key is taken to have, and counting
one more is Map.update(counts, word, 0, &(&1 + 1)); counting every
value of an iteration is Iter.frequencies. Elixir’s Map.update
differs: it stores a missing key’s default unchanged.
assert Map.update({"a" => 1}, "a", 0, &(&1 + 1)) == {"a" => 2}
assert Map.update({"a" => 1}, "b", 0, &(&1 + 1)) == {"a" => 1, "b" => 1}
Map.map_next
Section titled “Map.map_next”fn map_next<K, V>(m: Map<K, V>) -> Maybe<((K, V), Map<K, V>)>
type function on Map
Returns the first key-value pair and the map without it, or None if the map is empty.
assert Map.map_next({"a" => 1}) == Some((("a", 1), {}))
Map.size
Section titled “Map.size”fn size<K, V>(m: Map<K, V>) -> NonNegativeInt
type function on Map
Returns the number of entries in the map. O(1): a Map keeps its size.
assert Map.size({"a" => 1, "b" => 2}) == 2
m: Map<String, Int> = {}
assert Map.size(m) == 0
Map.keys
Section titled “Map.keys”fn keys<K, V>(m: Map<K, V>) -> List<K>
type function on Map
Returns all keys as a list, in insertion order.
assert Map.keys({"a" => 1, "b" => 2}) == ["a", "b"]
Map.values
Section titled “Map.values”fn values<K, V>(m: Map<K, V>) -> List<V>
type function on Map
Returns all values as a list, in insertion order of the keys.
assert Map.values({"a" => 1, "b" => 2}) == [1, 2]
Map.map_values
Section titled “Map.map_values”fn map_values<K, V, U>(m: Map<K, V>, f: (V) -> U) -> Map<K, U>
type function on Map
Applies f to each value. Keys are unchanged.
assert Map.map_values({"a" => 1, "b" => 2}, &(&1 * 10)) == {"a" => 10, "b" => 20}
Map.map_keys
Section titled “Map.map_keys”fn map_keys<K, V, J>(m: Map<K, V>, f: (K) -> J) -> Map<J, V>
type function on Map
Applies f to each key. When two keys become the same key, the later
entry’s value is kept.
assert Map.map_keys({"a" => 1, "b" => 2}, &(&1 + "!")) == {"a!" => 1, "b!" => 2}
assert Map.map_keys({"a" => 1, "b" => 2}, fn _ -> "k") == {"k" => 2}
Map.contains
Section titled “Map.contains”impl Contains for Map<K, V>
fn contains(c: Map<K, V>, x: K) -> Bool
impl Contains.contains
True if x is a key of the map: a hash lookup. A value is not a key.
assert Map.contains({"a" => 1}, "a")
refute Map.contains({"a" => 1}, "z")
refute Map.contains({"a" => "b"}, "b")
empty: Map<String, Int> = {}
refute Map.contains(empty, "a")
Map.each_while
Section titled “Map.each_while”impl Iter for Map<K, V>
fn each_while(m: Map<K, V>, yield: ((K, V)) -> Bool) -> Bool
impl Iter.each_while
Map.known_count
Section titled “Map.known_count”impl Iter for Map<K, V>
fn known_count(m: Map<K, V>) -> Maybe<Int>
impl Iter.known_count
Map.to_string
Section titled “Map.to_string”impl Display for Map<K, V>
fn to_string(value: Map<K, V>) -> String
impl Display.to_string
Map.inspect
Section titled “Map.inspect”impl Debug for Map<K, V>
fn inspect(value: Map<K, V>) -> String
impl Debug.inspect
Map.equal
Section titled “Map.equal”impl Equatable for Map<K, V>
fn equal(a: Map<K, V>, b: Map<K, V>) -> Bool
impl Equatable.equal
Map.hash
Section titled “Map.hash”impl Hashable for Map<K, V>
fn hash(m: Map<K, V>) -> Int
impl Hashable.hash
Map.add
Section titled “Map.add”impl Add<Map<K, V>, Map<K, V>> for Map<K, V>
fn add(a: Map<K, V>, rhs: Map<K, V>) -> Map<K, V>
impl Add.add
a + b is Map.merge(a, b): the right-hand map wins on a shared key.
assert {"a" => 1} + {"a" => 9, "b" => 2} == {"a" => 9, "b" => 2}
empty: Map<String, Int> = {}
assert empty + {"a" => 1} == {"a" => 1}
Map.empty_sum
Section titled “Map.empty_sum”impl Summable for Map<K, V>
fn empty_sum() -> Map<K, V>
impl Summable.empty_sum
The sum of no Maps: the empty Map. Summing Maps merges them in order
with +, so on a shared key the later map’s value wins.
empty: Map<String, Int> = Map.empty_sum()
assert Map.size(empty) == 0
assert {"a" => 1} + Map.empty_sum() == {"a" => 1}
assert Iter.sum([{"a" => 1}, {"a" => 9, "b" => 2}]) == {"a" => 9, "b" => 2}
type NonEmptyMap
Section titled “type NonEmptyMap”subtype NonEmptyMap<K, V> Map<K, V> when fn m -> Map.size(m) > 0
A Map with at least one entry. A literal is checked when the program is
compiled, so {} where a NonEmptyMap is expected is an error before the
program runs; NonEmptyMap.try_from(m) checks a Map computed at run
time, and NonEmptyMap.put(m, key, value) builds one from any Map.
Its keys and values are NonEmptyLists, and its first and last entries
are plain values, not Maybes. A NonEmptyMap is a Map and passes
wherever one is expected. It is in the prelude.
subtype: NonEmptyMap is a subtype of Map<K, V>. A literal where a NonEmptyMap is expected is checked when the program is compiled; NonEmptyMap.try_from(...) checks a value when it runs.
ages: NonEmptyMap<String, Int> = {"ann" => 31, "bo" => 12}
assert NonEmptyMap.first_entry(ages) == ("ann", 31)
assert NonEmptyList.max(NonEmptyMap.values(ages)) == 31
assert Map.get(ages, "bo") == Some(12)
none: Map<String, Int> = {}
assert NonEmptyMap.try_from(none) == None
NonEmptyMap.of
Section titled “NonEmptyMap.of”fn of<K, V>(key: K, value: V, rest: Map<K, V>) -> NonEmptyMap<K, V>
type function on NonEmptyMap
A NonEmptyMap of key mapped to value, then the entries of
rest, which may be empty; rest’s value wins if it holds key.
assert NonEmptyMap.of("a", 1, {"b" => 2}) == {"a" => 1, "b" => 2}
NonEmptyMap.size
Section titled “NonEmptyMap.size”fn size<K, V>(m: NonEmptyMap<K, V>) -> PositiveInt
type function on NonEmptyMap
The number of entries, at least one. O(1).
assert NonEmptyMap.size({"a" => 1}) == 1
NonEmptyMap.first_entry
Section titled “NonEmptyMap.first_entry”fn first_entry<K, V>(m: NonEmptyMap<K, V>) -> (K, V)
type function on NonEmptyMap
The entry inserted first.
assert NonEmptyMap.first_entry({"a" => 1, "b" => 2}) == ("a", 1)
NonEmptyMap.last_entry
Section titled “NonEmptyMap.last_entry”fn last_entry<K, V>(m: NonEmptyMap<K, V>) -> (K, V)
type function on NonEmptyMap
The entry inserted last.
assert NonEmptyMap.last_entry({"a" => 1, "b" => 2}) == ("b", 2)
NonEmptyMap.max_by
Section titled “NonEmptyMap.max_by”fn max_by<K, V, C>(m: NonEmptyMap<K, V>, key: ((K, V)) -> C) -> (K, V) where C: Comparable
type function on NonEmptyMap
The entry key ranks largest; the first of several equal ones.
assert NonEmptyMap.max_by({"a" => 3, "b" => 9}, fn (_, v) -> v) == ("b", 9)
NonEmptyMap.min_by
Section titled “NonEmptyMap.min_by”fn min_by<K, V, C>(m: NonEmptyMap<K, V>, key: ((K, V)) -> C) -> (K, V) where C: Comparable
type function on NonEmptyMap
The entry key ranks smallest; the first of several equal ones.
assert NonEmptyMap.min_by({"a" => 3, "b" => 9}, fn (_, v) -> v) == ("a", 3)
NonEmptyMap.keys
Section titled “NonEmptyMap.keys”fn keys<K, V>(m: NonEmptyMap<K, V>) -> NonEmptyList<K>
type function on NonEmptyMap
The keys, in insertion order.
assert NonEmptyMap.keys({"a" => 1, "b" => 2}) == ["a", "b"]
NonEmptyMap.values
Section titled “NonEmptyMap.values”fn values<K, V>(m: NonEmptyMap<K, V>) -> NonEmptyList<V>
type function on NonEmptyMap
The values, in insertion order.
assert NonEmptyMap.values({"a" => 1, "b" => 2}) == [1, 2]
NonEmptyMap.map_values
Section titled “NonEmptyMap.map_values”fn map_values<K, V, U>(m: NonEmptyMap<K, V>, f: (V) -> U) -> NonEmptyMap<K, U>
type function on NonEmptyMap
Applies f to each value, keeping the keys.
assert NonEmptyMap.map_values({"a" => 1}, fn n -> n * 2) == {"a" => 2}
NonEmptyMap.put
Section titled “NonEmptyMap.put”fn put<K, V>(m: Map<K, V>, key: K, value: V) -> NonEmptyMap<K, V>
type function on NonEmptyMap
m, which may be empty, with key mapped to value.
assert NonEmptyMap.put({"a" => 1}, "b", 2) == {"a" => 1, "b" => 2}
empty: Map<String, Int> = {}
assert NonEmptyMap.put(empty, "a", 1) == {"a" => 1}
NonEmptyMap.merge
Section titled “NonEmptyMap.merge”fn merge<K, V>(a: NonEmptyMap<K, V>, b: Map<K, V>) -> NonEmptyMap<K, V>
type function on NonEmptyMap
The entries of a, then those of b, which may be empty; b’s
value wins on a shared key.
assert NonEmptyMap.merge({"a" => 1}, {"a" => 5, "b" => 2}) == {"a" => 5, "b" => 2}
NonEmptyMap.try_from
Section titled “NonEmptyMap.try_from”fn try_from<K, V>(value: Map<K, V>) -> Maybe<NonEmptyMap<K, V>>
type function on NonEmptyMap
Some of the value when it satisfies NonEmptyMap’s rules, None when it does not.