Janiczek / elm-bidict / MultiDict

A dictionary mapping unique keys to multiple values, allowing for modelling one-to-many relationships.

Example usage:

oneToMany : MultiDict String Int
oneToMany =
    MultiDict.empty
        |> MultiDict.insert "A" 1
        |> MultiDict.insert "B" 2
        |> MultiDict.insert "C" 3
        |> MultiDict.insert "A" 2

MultiDict.get "A" oneToMany
--> Set.fromList [1, 2]

Dictionaries


type MultiDict comparable1 comparable2

The underlying data structure. Think about it as

 type alias MultiDict comparable1 comparable2 =
     Dict comparable1 (Set comparable2) -- just a normal Dict!

Differences from Dict

toDict : MultiDict comparable1 comparable2 -> Dict comparable1 (Set comparable2)

Convert MultiDict into a Dict. (Throw away the reverse mapping.)

fromDict : Dict comparable1 (Set comparable2) -> MultiDict comparable1 comparable2

Convert Dict into a MultiDict. (Compute the reverse mapping.)

Build

empty : MultiDict comparable1 comparable2

Create an empty dictionary.

singleton : comparable1 -> comparable2 -> MultiDict comparable1 comparable2

Create a dictionary with one key-value pair.

insert : comparable1 -> comparable2 -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

Insert a key-value pair into a dictionary. Replaces value when there is a collision.

update : comparable1 -> (Set comparable2 -> Set comparable2) -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

Update the value of a dictionary for a specific key with a given function.

remove : comparable1 -> comparable2 -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

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

removeAll : comparable1 -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

Remove all key-value pairs for the given key from a dictionary. If the key is not found, no changes are made.

Query

isEmpty : MultiDict comparable1 comparable2 -> Basics.Bool

Determine if a dictionary is empty.

isEmpty empty == True

member : comparable1 -> MultiDict comparable1 comparable2 -> Basics.Bool

Determine if a key is in a dictionary.

get : comparable1 -> MultiDict comparable1 comparable2 -> Set comparable2

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 = fromList [ ("Tom", Cat), ("Jerry", Mouse) ]

get "Tom"   animals == Just Cat
get "Jerry" animals == Just Mouse
get "Spike" animals == Nothing

size : MultiDict comparable1 comparable2 -> Basics.Int

Determine the number of key-value pairs in the dictionary.

Lists

keys : MultiDict comparable1 comparable2 -> List comparable1

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

keys (fromList [ ( 0, "Alice" ), ( 1, "Bob" ) ]) == [ 0, 1 ]

values : MultiDict comparable1 comparable2 -> List comparable2

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

values (fromList [ ( 0, "Alice" ), ( 1, "Bob" ) ]) == [ "Alice", "Bob" ]

toList : MultiDict comparable1 comparable2 -> List ( comparable1, Set comparable2 )

Convert a dictionary into an association list of key-value pairs, sorted by keys.

fromList : List ( comparable1, Set comparable2 ) -> MultiDict comparable1 comparable2

Convert an association list into a dictionary.

fromFlatList : List ( comparable1, comparable2 ) -> MultiDict comparable1 comparable2

Convert an association list into a dictionary.

fromFlatList
    [ ( "foo", 1 )
    , ( "bar", 2 )
    , ( "foo", 3 )
    ]

results in the same dict as

fromList
    [ ( "foo", Set.fromList [ 1, 3 ] )
    , ( "bar", Set.fromList [ 2 ] )
    ]

Transform

map : (comparable1 -> comparable21 -> comparable22) -> MultiDict comparable1 comparable21 -> MultiDict comparable1 comparable22

Apply a function to all values in a dictionary.

foldl : (comparable1 -> Set comparable2 -> acc -> acc) -> acc -> MultiDict comparable1 comparable2 -> acc

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

getAges users =
    Dict.foldl addAge [] users

addAge _ user ages =
    user.age :: ages

-- getAges users == [33,19,28]

foldr : (comparable1 -> Set comparable2 -> acc -> acc) -> acc -> MultiDict comparable1 comparable2 -> acc

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

getAges users =
    Dict.foldr addAge [] users

addAge _ user ages =
    user.age :: ages

-- getAges users == [28,19,33]

filter : (comparable1 -> comparable2 -> Basics.Bool) -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

Keep only the mappings that pass the given test.

partition : (comparable1 -> Set comparable2 -> Basics.Bool) -> MultiDict comparable1 comparable2 -> ( MultiDict comparable1 comparable2, MultiDict comparable1 comparable2 )

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 : MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

Combine two dictionaries. If there is a collision, preference is given to the first dictionary.

intersect : MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

Keep a key-value pair when its key appears in the second dictionary. Preference is given to values in the first dictionary.

diff : MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2 -> MultiDict comparable1 comparable2

Keep a key-value pair when its key does not appear in the second dictionary.

merge : (comparable1 -> Set comparable21 -> acc -> acc) -> (comparable1 -> Set comparable21 -> Set comparable22 -> acc -> acc) -> (comparable1 -> Set comparable22 -> acc -> acc) -> MultiDict comparable1 comparable21 -> MultiDict comparable1 comparable22 -> acc -> acc

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.