# orddict

### MODULE

orddict

### MODULE SUMMARY

Key-Value Dictionary as Ordered List

### DESCRIPTION

`Orddict` implements a `Key` - `Value` dictionary. An `orddict` is a representation of a dictionary, where a list of pairs is used to store the keys and values. The list is ordered after the keys.

This module provides exactly the same interface as the module `dict` but with a defined representation. One difference is that while `dict` considers two keys as different if they do not match (`=:=`), this module considers two keys as different if and only if they do not compare equal (`==`).

### DATA TYPES

    ordered_dictionary()
      as returned by new/0

### EXPORTS

`append(Key, Value, Orddict1) -> Orddict2`

Types:

`Key = Value = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

This function appends a new `Value` to the current list of values associated with `Key`. An exception is generated if the initial value associated with `Key` is not a list of values.

`append_list(Key, ValList, Orddict1) -> Orddict2`

Types:

`ValList = [Value]`
`Key = Value = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

This function appends a list of values `ValList` to the current list of values associated with `Key`. An exception is generated if the initial value associated with `Key` is not a list of values.

`erase(Key, Orddict1) -> Orddict2`

Types:

`Key = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

This function erases all items with a given key from a dictionary.

`fetch(Key, Orddict) -> Value`

Types:

`Key = Value = term()`
`Orddict = ordered_dictionary()`

This function returns the value associated with `Key` in the dictionary `Orddict`. `fetch` assumes that the `Key` is present in the dictionary and an exception is generated if `Key` is not in the dictionary.

`fetch_keys(Orddict) -> Keys`

Types:

`Orddict = ordered_dictionary()`
`Keys = [term()]`

This function returns a list of all keys in the dictionary.

`filter(Pred, Orddict1) -> Orddict2`

Types:

`Pred = fun(Key, Value) -> bool()`
`Key = Value = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

`Orddict2` is a dictionary of all keys and values in `Orddict1` for which `Pred(Key, Value)` is `true`.

`find(Key, Orddict) -> {ok, Value} | error`

Types:

`Key = Value = term()`
`Orddict = ordered_dictionary()`

This function searches for a key in a dictionary. Returns `{ok, Value}` where `Value` is the value associated with `Key`, or `error` if the key is not present in the dictionary.

`fold(Fun, Acc0, Orddict) -> Acc1`

Types:

`Fun = fun(Key, Value, AccIn) -> AccOut`
`Key = Value = term()`
`Acc0 = Acc1 = AccIn = AccOut = term()`
`Orddict = ordered_dictionary()`

Calls `Fun` on successive keys and values of `Orddict` together with an extra argument `Acc` (short for accumulator). `Fun` must return a new accumulator which is passed to the next call. `Acc0` is returned if the list is empty. The evaluation order is undefined.

`from_list(List) -> Orddict`

Types:

`List = [{Key, Value}]`
`Orddict = ordered_dictionary()`

This function converts the key/value list `List` to a dictionary.

`is_key(Key, Orddict) -> bool()`

Types:

`Key = term()`
`Orddict = ordered_dictionary()`

This function tests if `Key` is contained in the dictionary `Orddict`.

`map(Fun, Orddict1) -> Orddict2`

Types:

`Fun = fun(Key, Value1) -> Value2`
`Key = Value1 = Value2 = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

`map` calls `Func` on successive keys and values of `Orddict` to return a new value for each key. The evaluation order is undefined.

`merge(Fun, Orddict1, Orddict2) -> Orddict3`

Types:

`Fun = fun(Key, Value1, Value2) -> Value`
`Key = Value1 = Value2 = Value3 = term()`
`Orddict1 = Orddict2 = Orddict3 = ordered_dictionary()`

`merge` merges two dictionaries, `Orddict1` and `Orddict2`, to create a new dictionary. All the `Key` - `Value` pairs from both dictionaries are included in the new dictionary. If a key occurs in both dictionaries then `Fun` is called with the key and both values to return a new value. `merge` could be defined as:

    merge(Fun, D1, D2) ->
        fold(fun (K, V1, D) ->
                     update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
             end, D2, D1).

but is faster.

`new() -> ordered_dictionary()`

This function creates a new dictionary.

`store(Key, Value, Orddict1) -> Orddict2`

Types:

`Key = Value = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

This function stores a `Key` - `Value` pair in a dictionary. If the `Key` already exists in `Orddict1`, the associated value is replaced by `Value`.

`to_list(Orddict) -> List`

Types:

`Orddict = ordered_dictionary()`
`List = [{Key, Value}]`

This function converts the dictionary to a list representation.

`update(Key, Fun, Orddict1) -> Orddict2`

Types:

`Key = term()`
`Fun = fun(Value1) -> Value2`
`Value1 = Value2 = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

Update the a value in a dictionary by calling `Fun` on the value to get a new value. An exception is generated if `Key` is not present in the dictionary.

`update(Key, Fun, Initial, Orddict1) -> Orddict2`

Types:

`Key = Initial = term()`
`Fun = fun(Value1) -> Value2`
`Value1 = Value2 = term()`
`Orddict1 = Orddict2 = ordered_dictionary()`

Update the a value in a dictionary by calling `Fun` on the value to get a new value. If `Key` is not present in the dictionary then `Initial` will be stored as the first value. For example `append/3` could be defined as:

    append(Key, Val, D) ->
        update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).

`update_counter(Key, Increment, Orddict1) -> Orddict2`

Types:

`Key = term()`
`Increment = number()`
`Orddict1 = Orddict2 = ordered_dictionary()`

Add `Increment` to the value associated with `Key` and store this value. If `Key` is not present in the dictionary then `Increment` will be stored as the first value.

This could be defined as:

    update_counter(Key, Incr, D) ->
        update(Key, fun (Old) -> Old + Incr end, Incr, D).

but is faster.

### Notes

The functions `append` and `append_list` are included so we can store keyed values in a list accumulator. For example:

    > D0 = orddict:new(),
      D1 = orddict:store(files, [], D0),
      D2 = orddict:append(files, f1, D1),
      D3 = orddict:append(files, f2, D2),
      D4 = orddict:append(files, f3, D3),
      orddict:fetch(files, D4).
    [f1,f2,f3]

This saves the trouble of first fetching a keyed value, appending a new value to the list of stored values, and storing the result.

The function `fetch` should be used if the key is known to be in the dictionary, otherwise `find`.

### See Also

dict(3), gb_trees(3)

### AUTHORS

Robert Virding - support@erlang.ericsson.se

stdlib 1.14.5
Copyright © 1991-2007 Ericsson AB