diff --git a/crates/compiler/builtins/roc/Dict.roc b/crates/compiler/builtins/roc/Dict.roc index d9230eede3..b9021677d1 100644 --- a/crates/compiler/builtins/roc/Dict.roc +++ b/crates/compiler/builtins/roc/Dict.roc @@ -27,15 +27,15 @@ interface Dict ] ## A [dictionary](https://en.wikipedia.org/wiki/Associative_array) that lets you -## can associate keys with values. +## associate keys with values. ## ## ### Inserting ## ## The most basic way to use a dictionary is to start with an empty one and ## then: -## 1. Call `Dict.insert` passing a key and a value, to associate that key with +## 1. Call [Dict.insert] passing a key and a value, to associate that key with ## that value in the dictionary. -## 2. Later, call `Dict.get` passing the same key as before, and it will return +## 2. Later, call [Dict.get] passing the same key as before, and it will return ## the value you stored. ## ## Here's an example of a dictionary which uses a city's name as the key, and @@ -51,12 +51,12 @@ interface Dict ## ## ### Accessing keys or values ## -## We can use `Dict.keys` and `Dict.values` functions to get only the keys or +## We can use [Dict.keys] and [Dict.values] functions to get only the keys or ## only the values. ## ## You may notice that these lists have the same order as the original insertion -## order. This will be true if all you ever do is `Dict.insert` and `Dict.get` operations -## on the dictionary, but `Dict.remove` operations can change this order. +## order. This will be true if all you ever do is [Dict.insert] and [Dict.get] operations +## on the dictionary, but [Dict.remove] operations can change this order. ## ## ### Removing ## @@ -70,17 +70,17 @@ interface Dict ## ## Notice that the order has changed. Philadelphia was not only removed from the ## list, but Amsterdam - the last entry we inserted - has been moved into the -## spot where Philadelphia was previously. This is exactly what `Dict.remove` +## spot where Philadelphia was previously. This is exactly what [Dict.remove] ## does. It removes an element and moves the most recent insertion into the ## vacated spot. ## -## This move is done as a performance optimization, and it lets `Dict.remove` +## This move is done as a performance optimization, and it lets [Dict.remove] ## have [constant time complexity](https://en.wikipedia.org/wiki/Time_complexity#Constant_time). ## ## ### Equality ## ## Two dictionaries are equal when their contents and orderings match. This -## means that when `dict1 == dict2` the expression `fn dict1 == fn dict2` will +## means that when `dict1 == dict2`, the expression `fn dict1 == fn dict2` will ## also evaluate to `Bool.true`. The function `fn` can count on the ordering of ## values in the dictionary to also match. Dict k v := List [Pair k v] has [Eq] @@ -95,7 +95,7 @@ empty = @Dict [] withCapacity : Nat -> Dict k v withCapacity = \n -> @Dict (List.withCapacity n) -## Get the value at a given key. If there is a value for the specified key it +## Get the value for a given key. If there is a value for the specified key it ## will return [Ok value], otherwise return [Err KeyNotFound]. ## ## expect @@ -114,9 +114,9 @@ get = \@Dict list, needle -> Err NotFound -> Err KeyNotFound -## Iterate through the keys and values in the dictionary and call the function -## `state, k, v -> state` for each value with an initial `state` value provided -## for the first call. +## Iterate through the keys and values in the dictionary and call the provided +## function with signature `state, k, v -> state` for each value, with an +## initial `state` value provided for the first call. ## ## expect ## Dict.empty @@ -272,10 +272,10 @@ values = \@Dict list -> List.map list (\Pair _ v -> v) ## Combine two dictionaries by keeping the [union](https://en.wikipedia.org/wiki/Union_(set_theory)) -## of all the values. This means that all of the values in both dictionaries -## will be combined. Note that where there are values with the same key, the -## value contained in the first input will be retained, and the value in -## the second input will be removed. +## of all the key-value pairs. This means that all the key-value pairs in +## both dictionaries will be combined. Note that where there are pairs +## with the same key, the value contained in the first input will be +## retained, and the value in the second input will be removed. ## ## first = ## Dict.single 1 "Keep Me" @@ -299,10 +299,10 @@ insertAll = \xs, @Dict ys -> List.walk ys xs (\state, Pair k v -> Dict.insertIfVacant state k v) ## Combine two dictionaries by keeping the [intersection](https://en.wikipedia.org/wiki/Intersection_(set_theory)) -## of all the values. This means that we keep only those values that are in both -## dictionaries. Note that where there are values with the same key, the -## value contained in the first input will be retained, and the value in -## the second input will be removed. +## of all the key-value pairs. This means that we keep only those pairs +## that are in both dictionaries. Note that where there are pairs with +## the same key, the value contained in the first input will be retained, +## and the value in the second input will be removed. ## ## first = ## Dict.single 1 "Keep Me" @@ -320,10 +320,10 @@ keepShared = \@Dict xs, ys -> List.keepIf xs (\Pair k _ -> Dict.contains ys k) |> @Dict -## Remove the values in the first input that are also in the second using the -## [set difference](https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement) -## of the values. This means that we will be left with only those values that -## are in the first dictionary if they are not in the second. +## Remove the key-value pairs in the first input that are also in the second +## using the [set difference](https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement) +## of the values. This means that we will be left with only those pairs that +## are in the first dictionary and whose keys are not in the second. ## ## first = ## Dict.single 1 "Keep Me"