# dict

### MODULE

dict

### MODULE SUMMARY

Key-Value Dictionary

### DESCRIPTION

`Dict` implements a `Key` - `Value` dictionary. The representation of a dictionary is not defined.

### DATA TYPES

    dictionary()
      as returned by new/0

### EXPORTS

`append(Key, Value, Dict1) -> Dict2`

Types:

`Key = Value = term()`
`Dict1 = Dict2 = 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, Dict1) -> Dict2`

Types:

`ValList = [Value]`
`Key = Value = term()`
`Dict1 = Dict2 = 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, Dict1) -> Dict2`

Types:

`Key = term()`
`Dict1 = Dict2 = dictionary()`

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

`fetch(Key, Dict) -> Value`

Types:

`Key = Value = term()`
`Dict = dictionary()`

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

`fetch_keys(Dict) -> Keys`

Types:

`Dict = dictionary()`
`Keys = [term()]`

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

`filter(Pred, Dict1) -> Dict2`

Types:

`Pred = fun(Key, Value) -> bool()`
`Key = Value = term()`
`Dict1 = Dict2 = dictionary()`

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

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

Types:

`Key = Value = term()`
`Dict = 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, Dict) -> Acc1`

Types:

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

Calls `Fun` on successive keys and values of `Dict` 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) -> Dict`

Types:

`List = [{Key, Value}]`
`Dict = dictionary()`

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

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

Types:

`Key = term()`
`Dict = dictionary()`

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

`map(Fun, Dict1) -> Dict2`

Types:

`Fun = fun(Key, Value1) -> Value2`
`Key = Value1 = Value2 = term()`
`Dict1 = Dict2 = dictionary()`

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

`merge(Fun, Dict1, Dict2) -> Dict3`

Types:

`Fun = fun(Key, Value1, Value2) -> Value`
`Key = Value1 = Value2 = Value3 = term()`
`Dict1 = Dict2 = Dict3 = dictionary()`

`merge` merges two dictionaries, `Dict1` and `Dict2`, 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() -> dictionary()`

This function creates a new dictionary.

`store(Key, Value, Dict1) -> Dict2`

Types:

`Key = Value = term()`
`Dict1 = Dict2 = dictionary()`

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

`to_list(Dict) -> List`

Types:

`Dict = dictionary()`
`List = [{Key, Value}]`

This function converts the dictionary to a list representation.

`update(Key, Fun, Dict1) -> Dict2`

Types:

`Key = term()`
`Fun = fun(Value1) -> Value2`
`Value1 = Value2 = term()`
`Dict1 = Dict2 = 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, Dict1) -> Dict2`

Types:

`Key = Initial = term()`
`Fun = fun(Value1) -> Value2`
`Value1 = Value2 = term()`
`Dict1 = Dict2 = 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, Dict1) -> Dict2`

Types:

`Key = term()`
`Increment = number()`
`Dict1 = Dict2 = 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 = dict:new(),
      D1 = dict:store(files, [], D0),
      D2 = dict:append(files, f1, D1),
      D3 = dict:append(files, f2, D2),
      D4 = dict:append(files, f3, D3),
      dict: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

gb_trees(3), orddict(3)

### AUTHORS

Robert Virding - support@erlang.ericsson.se

stdlib 1.14.3
Copyright © 1991-2007 Ericsson AB