Skip to content

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.

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<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"]
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
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}
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}
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}
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]}
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}
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), {}))
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
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"]
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]
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}
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}

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")

impl Iter for Map<K, V>

fn each_while(m: Map<K, V>, yield: ((K, V)) -> Bool) -> Bool

impl Iter.each_while

impl Iter for Map<K, V>

fn known_count(m: Map<K, V>) -> Maybe<Int>

impl Iter.known_count

impl Display for Map<K, V>

fn to_string(value: Map<K, V>) -> String

impl Display.to_string

impl Debug for Map<K, V>

fn inspect(value: Map<K, V>) -> String

impl Debug.inspect

impl Equatable for Map<K, V>

fn equal(a: Map<K, V>, b: Map<K, V>) -> Bool

impl Equatable.equal

impl Hashable for Map<K, V>

fn hash(m: Map<K, V>) -> Int

impl Hashable.hash

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}

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}
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
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}
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
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)
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)
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)
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)
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"]
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]
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}
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}
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}
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.