Search documentation of stdlib

# dict (stdlib v7.3)

Copy Markdown View Source

A Key-value dictionary.

The representation of a dictionary is not defined.

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

## Notes

Functions `append` and `append_list` are included so that keyed values can be stored 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.

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

## See Also

`gb_trees`, `orddict`

## Summary

### Types

dict()
dict(Key, Value)

Dictionary as returned by `new/0`.

### Functions

append(Key, Value, Dict1)

Appends a new `Value` to the current list of values associated with `Key`.

append_list(Key, ValList, Dict1)

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)

Erases all items with a given key from a dictionary.

fetch(Key, Dict)

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

fetch_keys(Dict)

Returns a list of all keys in dictionary `Dict`.

filter(Pred, Dict1)

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

find(Key, Dict)

Searches for a key in dictionary `Dict`. 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)

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

from_list(List)

Converts the `Key`-`Value` list `List` to dictionary `Dict`.

is_empty(Dict)

Returns `true` if dictionary `Dict` has no elements, otherwise `false`.

is_key(Key, Dict)

Tests if `Key` is contained in dictionary `Dict`.

map(Fun, Dict1)

Calls `Fun` on successive keys and values of dictionary `Dict1` to return a new value for each key. The evaluation order is undefined.

merge(Fun, Dict1, Dict2)

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, `Fun` is called with the key and both values to return a new value. `merge` can be defined as follows, but is faster

new()

Creates a new dictionary.

size(Dict)

Returns the number of elements in dictionary `Dict`.

store(Key, Value, Dict1)

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

take(Key, Dict)

This function returns value from dictionary and a new dictionary without this value. Returns `error` if the key is not present in the dictionary.

to_list(Dict)

Converts dictionary `Dict` to a list representation.

update(Key, Fun, Dict1)

Updates 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)

Updates a value in a dictionary by calling `Fun` on the value to get a new value. If `Key` is not present in the dictionary, `Initial` is stored as the first value. For example, `append/3` can be defined as

update_counter(Key, Increment, Dict1)

Adds `Increment` to the value associated with `Key` and stores this value. If `Key` is not present in the dictionary, `Increment` is stored as the first value.

## Types

# dict()

    -type dict() :: dict(_, _).

# dict(Key, Value)

    -opaque dict(Key, Value)

Dictionary as returned by `new/0`.

## Functions

# append(Key, Value, Dict1)

    -spec append(Key, Value, Dict1) -> Dict2 when Dict1 :: dict(Key, Value), Dict2 :: dict(Key, Value).

Appends a new `Value` to the current list of values associated with `Key`.

See also section Notes.

# append_list(Key, ValList, Dict1)

    -spec append_list(Key, ValList, Dict1) -> Dict2
                         when Dict1 :: dict(Key, Value), Dict2 :: dict(Key, Value), ValList :: [Value].

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.

See also section Notes.

# erase(Key, Dict1)

    -spec erase(Key, Dict1) -> Dict2 when Dict1 :: dict(Key, Value), Dict2 :: dict(Key, Value).

Erases all items with a given key from a dictionary.

# fetch(Key, Dict)

    -spec fetch(Key, Dict) -> Value when Dict :: dict(Key, Value).

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

See also section Notes.

# fetch_keys(Dict)

    -spec fetch_keys(Dict) -> Keys when Dict :: dict(Key, Value :: term()), Keys :: [Key].

Returns a list of all keys in dictionary `Dict`.

# filter(Pred, Dict1)

    -spec filter(Pred, Dict1) -> Dict2
                    when
                        Pred :: fun((Key, Value) -> boolean()),
                        Dict1 :: dict(Key, Value),
                        Dict2 :: dict(Key, Value).

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

# find(Key, Dict)

    -spec find(Key, Dict) -> {ok, Value} | error when Dict :: dict(Key, Value).

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

See also section Notes.

# fold(Fun, Acc0, Dict)

    -spec fold(Fun, Acc0, Dict) -> Acc1
                  when
                      Fun :: fun((Key, Value, AccIn) -> AccOut),
                      Dict :: dict(Key, Value),
                      Acc0 :: Acc,
                      Acc1 :: Acc,
                      AccIn :: Acc,
                      AccOut :: Acc.

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

# from_list(List)

    -spec from_list(List) -> Dict when Dict :: dict(Key, Value), List :: [{Key, Value}].

Converts the `Key`-`Value` list `List` to dictionary `Dict`.

# is_empty(Dict)

(since OTP 17.0)

    -spec is_empty(Dict) -> boolean() when Dict :: dict().

Returns `true` if dictionary `Dict` has no elements, otherwise `false`.

# is_key(Key, Dict)

    -spec is_key(Key, Dict) -> boolean() when Dict :: dict(Key, Value :: term()).

Tests if `Key` is contained in dictionary `Dict`.

# map(Fun, Dict1)

    -spec map(Fun, Dict1) -> Dict2
                 when
                     Fun :: fun((Key, Value1) -> Value2),
                     Dict1 :: dict(Key, Value1),
                     Dict2 :: dict(Key, Value2).

Calls `Fun` on successive keys and values of dictionary `Dict1` to return a new value for each key. The evaluation order is undefined.

# merge(Fun, Dict1, Dict2)

    -spec merge(Fun, Dict1, Dict2) -> Dict3
                   when
                       Fun :: fun((Key, Value1, Value2) -> Value),
                       Dict1 :: dict(Key, Value1),
                       Dict2 :: dict(Key, Value2),
                       Dict3 :: dict(Key, Value).

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, `Fun` is called with the key and both values to return a new value. `merge` can be defined as follows, but is faster:

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

# new()

    -spec new() -> dict().

Creates a new dictionary.

# size(Dict)

    -spec size(Dict) -> non_neg_integer() when Dict :: dict().

Returns the number of elements in dictionary `Dict`.

# store(Key, Value, Dict1)

    -spec store(Key, Value, Dict1) -> Dict2 when Dict1 :: dict(Key, Value), Dict2 :: dict(Key, Value).

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

# take(Key, Dict)

(since OTP 20.0)

    -spec take(Key, Dict) -> {Value, Dict1} | error
                  when Dict :: dict(Key, Value), Dict1 :: dict(Key, Value), Key :: term(), Value :: term().

This function returns value from dictionary and a new dictionary without this value. Returns `error` if the key is not present in the dictionary.

# to_list(Dict)

    -spec to_list(Dict) -> List when Dict :: dict(Key, Value), List :: [{Key, Value}].

Converts dictionary `Dict` to a list representation.

# update(Key, Fun, Dict1)

    -spec update(Key, Fun, Dict1) -> Dict2
                    when
                        Dict1 :: dict(Key, Value),
                        Dict2 :: dict(Key, Value),
                        Fun :: fun((Value1 :: Value) -> Value2 :: Value).

Updates 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)

    -spec update(Key, Fun, Initial, Dict1) -> Dict2
                    when
                        Dict1 :: dict(Key, Value),
                        Dict2 :: dict(Key, Value),
                        Fun :: fun((Value1 :: Value) -> Value2 :: Value),
                        Initial :: Value.

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

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

# update_counter(Key, Increment, Dict1)

    -spec update_counter(Key, Increment, Dict1) -> Dict2
                            when Dict1 :: dict(Key, Value), Dict2 :: dict(Key, Value), Increment :: number().

Adds `Increment` to the value associated with `Key` and stores this value. If `Key` is not present in the dictionary, `Increment` is stored as the first value.

This can be defined as follows, but is faster:

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