j-maas / elm-ordered-containers / OrderedDict

A dictionary mapping unique keys to values while remembering their insertion order. The keys can be any comparable type. This includes Int, Float, Time, Char, String, and tuples or lists of comparable types.

The insertion order is reflected in the functions under "Conversions" and "Transform". The order in the lists and the iteration order will be the order of insertion.

The API mirrors the core Dict's API, with exception for the functions listed there under "Combine", because these functions do not have an obvious way to handle the order between the combined dictionaries.

Dictionaries


type OrderedDict comparable v

A dictionary of keys and values that remembers the order of insertion.

Build

empty : OrderedDict comparable v

Create an empty dictionary.

singleton : comparable -> v -> OrderedDict comparable v

Create a dictionary with one key-value pair.

insert : comparable -> v -> OrderedDict comparable v -> OrderedDict comparable v

Insert a key-value pair into a dictionary. If the key already exists, the old value will be forgotten and the new value will be inserted at the end.

import OrderedDict

OrderedDict.empty
    |> OrderedDict.insert 1 "one"
    |> OrderedDict.insert 2 "two"
    |> OrderedDict.insert 1 "three"
    |> OrderedDict.toList
--> [ (2, "two"), (1, "three") ]

update : comparable -> (Maybe v -> Maybe v) -> OrderedDict comparable v -> OrderedDict comparable v

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

If a value exists for the key and the passed function returns a Just v, the value will be replaced, keeping its order. If it did not exist, the new value will be added to the end.

When the function returns a Nothing, the key is removed.

import OrderedDict

OrderedDict.empty
    |> OrderedDict.insert 1 "one"
    |> OrderedDict.insert 2 "two"
    |> OrderedDict.update 1 (\_ -> Just "three")
    |> OrderedDict.toList
--> [ (1, "three"), (2, "two") ]

OrderedDict.singleton 1 "one"
    |> OrderedDict.update 2 (\_ -> Just "two")
    |> OrderedDict.toList
--> [ (1, "one"), (2, "two") ]

OrderedDict.singleton 1 "one"
    |> OrderedDict.update 1 (\_ -> Nothing)
    |> OrderedDict.toList
--> []

remove : comparable -> OrderedDict comparable v -> OrderedDict comparable v

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

Query

isEmpty : OrderedDict comparable v -> Basics.Bool

Determine if a dictionary is empty.

member : comparable -> OrderedDict comparable v -> Basics.Bool

Determine if a key is in a dictionary.

get : comparable -> OrderedDict comparable v -> Maybe v

Get the value associated with a key. If the key is not found, return Nothing.

size : OrderedDict comparable v -> Basics.Int

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

Conversions

keys : OrderedDict comparable v -> List comparable

Get all of the keys in a dictionary, in insertion order.

values : OrderedDict comparable v -> List v

Get all of the values in a dictionary, in insertion order.

toList : OrderedDict comparable v -> List ( comparable, v )

Convert a dictionary into an association list of key-value pairs, in insertion order.

fromList : List ( comparable, v ) -> OrderedDict comparable v

Convert an association list into a dictionary.

If a key appears multiple times in the list, only the last occurrence is kept.

toDict : OrderedDict comparable v -> Dict comparable v

Convert an ordered dictionary into a regular Dict.

Transform

map : (comparable -> a -> b) -> OrderedDict comparable a -> OrderedDict comparable b

Apply a function to all values in a dictionary.

foldl : (comparable -> v -> b -> b) -> b -> OrderedDict comparable v -> b

Fold over the key-value pairs in a dictionary in insertion order.

foldr : (comparable -> v -> b -> b) -> b -> OrderedDict comparable v -> b

Fold over the key-value pairs in a dictionary in reverse insertion order.

filter : (comparable -> v -> Basics.Bool) -> OrderedDict comparable v -> OrderedDict comparable v

Keep only the key-value pairs that pass the given test.

partition : (comparable -> v -> Basics.Bool) -> OrderedDict comparable v -> ( OrderedDict comparable v, OrderedDict 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.

The order will be preserved in these new dictionaries in the sense that elements that are inserted after each other will remain ordered after each other.