Skip to content

Maps

A map associates keys with values. Each key appears once and has exactly one value. Map(keys, values) builds a map from two lists of the same length, the key at each position paired with the value at the same position:

Map(["Dune", "Emma"], [412, 474])
Map {"Dune": 412, "Emma": 474}
Map(["Dune", "Emma"], [412, 474])
Map<String, Int>

All the keys have one type, K, and all the values another, V. A map is not a Data record: a record's fields may each hold a different type, and the program does not know which fields there are.

A repeated key is an error, and so are lists of different lengths. Both are found when the map is built:

Map(["Dune", "Dune"], [412, 474])
execute failure[invalid-argument]: duplicate map key Dune
 --> <expression>:1:1
  |
1 | Map(["Dune", "Dune"], [412, 474])
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A map is usually built from a list of records, one list for the keys and one for the values:

type BookData : DataContract = {
    title: String
    pages: Int
}

raw : List<Data> = [{title: "Dune", pages: 412}, {title: "Emma", pages: 474}]
books = raw | BookData
Map(books | map(b => b.title), books | map(b => b.pages))
Map {"Dune": 412, "Emma": 474}

Some steps return a map. count_by counts the elements with each key:

["sf", "novel", "sf", "essay", "sf"] | count_by(g => g)
Map {"sf": 3, "novel": 1, "essay": 1}

Looking up a key

get returns the value for a key. The key may be missing, so get returns an Option<V>:

pages = Map(["Dune", "Emma"], [412, 474])
[pages.get("Dune"), pages.get("Ubik")]
[412, none]

unwrap_or supplies a value for a missing key:

pages = Map(["Dune", "Emma"], [412, 474])
pages.get("Ubik").unwrap_or(0)
0

A map is not indexed with []. xs[i] reads a position, and a map has keys, not positions.

Keys, values and entries

.keys is the set of keys. values returns the values as a list, and entries returns the key and value of each entry as a Pair:

pages = Map(["Dune", "Emma"], [412, 474])
pages.keys
{"Dune", "Emma"}
pages = Map(["Dune", "Emma"], [412, 474])
pages | values | sum
886
pages = Map(["Dune", "Emma"], [412, 474])
pages | entries | filter(e => e.second > 420) | map(e => e.first)
["Emma"]

A map is not a Collection, so size, map and filter do not take a map directly. Apply them to its keys, its values or its entries:

pages = Map(["Dune", "Emma"], [412, 474])
pages.keys | size
2

Merging

merge combines two maps. A key in both takes the value from the second:

ratings = Map(["Dune", "Emma"], [4, 3])
merge(ratings, Map(["Emma", "Ubik"], [5, 4]))
Map {"Dune": 4, "Emma": 5, "Ubik": 4}

merge_all merges a whole collection of maps in order.

Ordered and sorted maps

A Map makes no promise about the order of its keys, so its keys are a Set. Two more map types add an order:

  • An OrderedMap keeps its keys in the order they were given.
  • A SortedMap keeps its keys in the order of the key type. Its keys must be Orderable.

d2 diagram

OrderedMap(["Emma", "Dune", "Ubik"], [474, 412, 202])
OrderedMap {"Emma": 474, "Dune": 412, "Ubik": 202}
SortedMap(["Emma", "Dune", "Ubik"], [474, 412, 202])
SortedMap {"Dune": 412, "Emma": 474, "Ubik": 202}

The difference is visible in the type of .keys. For a Map it is a Set<K>; for the other two it is a Seq<K>, which has positions:

SortedMap(["Emma", "Dune", "Ubik"], [474, 412, 202]).keys
Seq<String>

Order also changes equality. Two Maps with the same entries are equal whatever order their keys were given in; two OrderedMaps are equal only if their keys are in the same order:

[
    Map(["b", "a"], [1, 2]) == Map(["a", "b"], [2, 1]),
    OrderedMap(["b", "a"], [1, 2]) == OrderedMap(["a", "b"], [2, 1]),
]
[true, false]

An OrderedMap and a SortedMap are both Maps, so they can be passed wherever a Map is expected. histogram returns a SortedMap, so its buckets come out in order:

[412, 280, 310, 145, 474] | histogram(100)
SortedMap {100: 1, 200: 1, 300: 1, 400: 2}

The empty map

{:} with a declared map type is an empty map of that type:

counts : Map<String, Int> = {:}
counts
Map {}

Without a declared type, {:} is the empty Data record. Sets, Data and maps covers the rule.