A dictionary mapping unique keys to values. The keys can be any comparable
type. This includes Int
, Float
, Time
, Char
, String
, and tuples or
lists of comparable types.
Insert, remove, and query operations all take O(log n) time.
Internal.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 FastDict as Dict exposing (Dict)
users : Dict String User
users =
Dict.fromList
[ ( "Alice", User "Alice" 28 1.65 )
, ( "Bob", User "Bob" 19 1.82 )
, ( "Chuck", User "Chuck" 33 1.75 )
]
type alias User =
{ name : String
, age : Int
, height : Float
}
empty : Dict k v
Create an empty dictionary.
singleton : comparable -> v -> Dict comparable v
Create a dictionary with one key-value pair.
insert : comparable -> v -> Dict comparable v -> Dict comparable v
Insert a key-value pair into a dictionary. Replaces value when there is a collision.
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.
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.
isEmpty : Dict k v -> Basics.Bool
Determine if a dictionary is empty.
isEmpty empty
--> True
member : comparable -> Dict comparable v -> Basics.Bool
Determine if a key is in a 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 String String
animals =
fromList [ ("Tom", "Cat"), ("Jerry", "Mouse") ]
get "Tom" animals
--> Just "Cat"
get "Jerry" animals
--> Just "Mouse"
get "Spike" animals
--> Nothing
size : Dict k v -> Basics.Int
Determine the number of key-value pairs in the dictionary.
equals : Dict comparable v -> Dict comparable v -> Basics.Bool
Determine if two dictionaries are equal. This is needed because the structure could be different depending on insertion order.
getMinKey : Dict k v -> Maybe k
Gets the smallest key in the dictionary.
[ ( 1, 'z' ), ( 2, 'a' ) ]
|> fromList
|> getMinKey
--> Just 1
empty
|> getMinKey
--> Nothing
getMin : Dict k v -> Maybe ( k, v )
Gets the key-value pair with the smallest key.
[ ( 1, 'z' ), ( 2, 'a' ) ]
|> fromList
|> getMin
--> Just ( 1, 'z' )
empty
|> getMin
--> Nothing
getMaxKey : Dict k v -> Maybe k
Gets the biggest key in the dictionary.
[ ( 1, 'z' ), ( 2, 'a' ) ]
|> fromList
|> getMaxKey
--> Just 2
empty
|> getMaxKey
--> Nothing
getMax : Dict k v -> Maybe ( k, v )
Gets the key-value pair with the biggest key.
[ ( 1, 'z' ), ( 2, 'a' ) ]
|> fromList
|> getMax
--> Just ( 2, 'a' )
empty
|> getMax
--> Nothing
popMin : Dict comparable v -> Maybe ( ( comparable, v ), Dict comparable v )
Removes the key-value pair with the smallest key from the dictionary, and returns it.
[ ( 1, 'z' ), ( 2, 'a' ) ]
|> fromList
|> popMin
--> Just ( ( 1, 'z' ), fromList [ ( 2, 'a' ) ] )
empty
|> popMin
--> Nothing
popMax : Dict comparable v -> Maybe ( ( comparable, v ), Dict comparable v )
Removes the key-value pair with the biggest key from the dictionary, and returns it.
[ ( 1, 'z' ), ( 2, 'a' ) ]
|> fromList
|> popMax
--> Just ( ( 2, 'a' ), fromList [ ( 1, 'z' ) ] )
empty
|> popMax
--> Nothing
keys : Dict k v -> List k
Get all of the keys in a dictionary, sorted from lowest to highest.
keys (fromList [ ( 0, "Alice" ), ( 1, "Bob" ) ])
--> [ 0, 1 ]
values : Dict k v -> List v
Get all of the values in a dictionary, in the order of their keys.
values (fromList [ ( 0, "Alice" ), ( 1, "Bob" ) ])
--> [ "Alice", "Bob" ]
toList : Dict k v -> List ( k, v )
Convert a dictionary into an association list of key-value pairs, sorted by keys.
fromList : List ( comparable, v ) -> Dict comparable v
Convert an association list into a dictionary.
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.
getAges : Dict String Int -> List Int
getAges usersDict =
FastDict.foldl addAge [] usersDict
addAge : String -> Int -> List Int -> List Int
addAge _ age ages =
age :: ages
users : Dict String Int
users =
FastDict.fromList
[ ( "Abe", 28 )
, ( "Beatrix", 19 )
, ( "Charlotte", 33 )
]
-- Note that the _fold_ is from lowest to highest,
-- but because we're adding items to the beginning of the list
-- the result will be from highest to lowest.
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.
getAges : Dict String Int -> List Int
getAges usersDict =
FastDict.foldr addAge [] usersDict
addAge : String -> Int -> List Int -> List Int
addAge _ age ages =
age :: ages
users : Dict String Int
users =
FastDict.fromList
[ ( "Abe", 28 )
, ( "Beatrix", 19 )
, ( "Charlotte", 33 )
]
-- Note that the _fold_ is from highest to lowest,
-- but because we're adding items to the beginning of the list
-- the result will be from lowest to highest.
getAges users
--> [ 28, 19, 33 ]
filter : (comparable -> v -> Basics.Bool) -> Dict comparable v -> Dict comparable v
Keep only the key-value pairs that pass the given test.
partition : (comparable -> v -> Basics.Bool) -> Dict comparable v -> ( Dict comparable v, 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.
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:
You then traverse all the keys from lowest to highest, building up whatever you want.
toCoreDict : Dict comparable v -> Dict comparable v
Convert the dictionary into an equivalent one from elm/core.
fromCoreDict : Dict comparable v -> Dict comparable v
Convert the dictionary from an equivalent one from elm/core.
A custom type used for stoppable folds.
stoppableFoldl : (k -> v -> acc -> Step acc) -> acc -> Dict k v -> acc
A foldl that can stop early instead of traversing the whole dictionary.
stoppableFoldl
(\k v acc ->
if k >= 10 then
Stop acc
else
Continue (v + acc)
)
0
(fromList <| List.indexedMap Tuple.pair <| List.range 1 10000)
--> 55
stoppableFoldr : (k -> v -> acc -> Step acc) -> acc -> Dict k v -> acc
A foldr that can stop early instead of traversing the whole dictionary.
stoppableFoldr
(\k v acc ->
if k <= 9990 then
Stop acc
else
Continue (v + acc)
)
0
(fromList <| List.indexedMap Tuple.pair <| List.range 1 10000)
--> 89964
restructure : acc -> ({ key : key, value : value, left : () -> acc, right : () -> acc } -> acc) -> Dict key value -> acc
This allows you to take advantage of the tree structure of the dictionary to do some operations more efficiently.
Calling left
will give the result of calling restructure
on the left subtree (lower keys), right
on the right one (higher keys).
If this is confusing you probably don't need this function!
any dict =
-- Notice how if `value` is `True` we don't call `left` nor `right`,
-- and if `value` is `False` but `left ()` is `True` we don't call right.
restructure False (\{ value, left, right } -> value || left () || right ())