Dict

A dictionary mapping unique keys to values. The keys can be any comparable type. This includes Int, Float, Time, Char and String.

Set, remove, and query operations all take O(log n) time.

type Dict k v

A dictionary of keys and values. So a Dict String User is a dictionary that lets you look up a String (such as user names) and find the associated User.

import Dict exposing ( Dict )

users : Dict String User
users =
    Dict.empty
        |> Dict.set "Alice" (makeUser "Alice" 28 1.65)
        |> Dict.set "Bob" (makeUser "Bob" 19 1.82)
        |> Dict.set "Chuck" (makeUser "Chuck" 33 1.75)

type alias User =
    { name : String
    , age : Int
    , height : Float
    }

makeUser : String -> Int -> Float -> User
makeUser name age height =
    { name = name
    , age = age
    , height = height
    }
empty : Dict k v

Create an empty dictionary.
singleton : comparable -> v -> Dict comparable v

Create a dictionary with one key-value pair.
set : comparable -> v -> Dict comparable v -> Dict comparable v

Sets a value for a given key. Existing values will be replaced. If the key isn't already registered, the key-value pair will be inserted.
update :
comparable
-> (Maybe v -> Maybe v)
-> Dict comparable v
-> Dict comparable v

Update the value of a dictionary for a specific key with a given function.
updateWithDefault :
comparable
-> v
-> (v -> v)
-> Dict comparable v
-> Dict comparable v

Same as update but if the key doesn't exist in the dictionary, a default value is passed to the provided update function instead of a Maybe.
remove : comparable -> Dict comparable v -> Dict comparable v

Remove a key-value pair from a dictionary. If the key is not found, no changes are made.

Query

isEmpty : Dict k v -> Bool

Determine if a dictionary is empty.

isEmpty empty == True
count : Dict k v -> Int

Determine the number of key-value pairs in the dictionary.
get : comparable -> Dict comparable v -> Maybe v

Get the value associated with a key. If the key is not found, return Nothing. This is useful when you are not sure if a key will be in the dictionary.

animals = Dict.empty |> Dict.set "Tom" Cat |> Dict.set "Jerry" Mouse

get "Tom"   animals == Just Cat
get "Jerry" animals == Just Mouse
get "Spike" animals == Nothing
member : comparable -> Dict comparable v -> Bool

Determine if a key is in a dictionary.
first : Dict k v -> Maybe { key : k, value : v }

Retrieve the first, or lowest, key-value pair.
last : Dict k v -> Maybe { key : k, value : v }

Retrieve the last, or highest, key-value pair.
findFirst :
(k -> v -> Bool)
-> Dict k v
-> Maybe { key : k, value : v
}

Find the first key-value pair that passes the test.
findLast :
(k -> v -> Bool)
-> Dict k v
-> Maybe { key : k, value : v
}

Find the last key-value pair that passes the test.
any : (k -> v -> Bool) -> Dict k v -> Bool

Checks if any key-value pair in the dictionary passes the test.
all : (k -> v -> Bool) -> Dict k v -> Bool

Checks if all key-value pairs in the dictionary passes the test.

Arrays

keys : Dict k v -> Array k

Get all of the keys in a dictionary, sorted from lowest to highest.

keys (Dict.empty |> Dict.set 0 "Alice" |> Dict.set 1 "Bob") == [ 0, 1 ]
values : Dict k v -> Array v

Get all of the values in a dictionary, in the order of their keys.

values (Dict.empty |> Dict.set 0 "Alice" |> Dict.set 1 "Bob") == [ "Alice", "Bob" ]

Transform

map : (k -> a -> b) -> Dict k a -> Dict k b

Apply a function to all values in a dictionary.
foldl : (k -> v -> b -> b) -> b -> Dict k v -> b

Fold over the key-value pairs in a dictionary from lowest key to highest key.

import Dict exposing (Dict)

getAges : Dict String User -> Array String
getAges users =
    Dict.foldl addAge [] users

addAge : String -> User -> Array String -> Array String
addAge _ user ages =
    user.age :: ages

-- getAges users == [33,19,28]
foldr : (k -> v -> b -> b) -> b -> Dict k v -> b

Fold over the key-value pairs in a dictionary from highest key to lowest key.

import Dict exposing (Dict)

getAges : Dict String User -> Array String
getAges users =
    Dict.foldr addAge [] users

addAge : String -> User -> Array String -> Array String
addAge _ user ages =
    user.age :: ages

-- getAges users == [28,19,33]
keepIf :
(comparable -> v -> Bool)
-> Dict comparable v
-> Dict comparable v

Keep only the key-value pairs that pass the given test.
mapAndKeepJust :
(comparable -> v -> Maybe x)
-> Dict comparable v
-> Dict comparable x

Remove unwanted results of a map operation.
partition :
(comparable -> v -> Bool)
-> Dict comparable v
-> { trues : Dict comparable v, falses : Dict comparable v
}

Partition a dictionary according to some test. The first dictionary contains all key-value pairs which passed the test, and the second contains the pairs that did not.

Combine

union : Dict comparable v -> Dict comparable v -> Dict comparable v

Combine two dictionaries. If there is a collision, preference is given to the first dictionary.
intersect : Dict comparable v -> Dict comparable v -> Dict comparable v

Keep a key-value pair when its key appears in the second dictionary. Preference is given to values in the first dictionary.
diff : Dict comparable a -> Dict comparable b -> Dict comparable a

Keep a key-value pair when its key does not appear in the second dictionary.
merge :
(comparable -> a -> result -> result)
-> (comparable -> a -> b -> result -> result)
-> (comparable -> b -> result -> result)
-> Dict comparable a
-> Dict comparable b
-> result
-> result

The most general way of combining two dictionaries. You provide three accumulators for when a given key appears:

  1. Only in the left dictionary.
  2. In both dictionaries.
  3. Only in the right dictionary. You then traverse all the keys from lowest to highest, building up whatever you want.