Search documentation of stdlib

# dict (stdlib v8.0.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 (`==`).

#### Note

For new code, prefer `maps` over this module.

### See Also

`gb_trees`, `orddict`, `maps`

## 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`.

erase(Key, Dict1)

Erases an item with a given key from a dictionary.

fetch(Key, Dict)

Returns the value associated with `Key` in dictionary `Dict`.

fetch_keys(Dict)

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

filter(Pred, Dict1)

Returns 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`.

fold(Fun, Acc0, Dict)

Calls `Fun` on successive keys and values of dictionary `Dict` together with an extra argument `Acc` (short for accumulator).

from_list(List)

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

is_empty(Dict)

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

is_key(Key, Dict)

Tests whether `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.

merge(Fun, Dict1, Dict2)

Merges two dictionaries, `Dict1` and `Dict2`, to create a new dictionary.

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 a dictionary.

take(Key, Dict)

This function returns a value from a dictionary and a new dictionary without this value.

to_list(Dict)

Converts a dictionary 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.

update(Key, Fun, Initial, Dict1)

Updates a value in a dictionary by calling `Fun` on the value to get a new value.

update_counter(Key, Increment, Dict1)

Adds `Increment` to the value associated with `Key` and stores this 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`.

## Examples

    1> Dict0 = dict:from_list([{a,[]}]).
    2> Dict1 = dict:append(a, 1, Dict0).
    3> dict:to_list(Dict1).
    [{a,[1]}]
    4> Dict2 = dict:append(a, 10, Dict1).
    5> dict:to_list(Dict2).
    [{a,[1,10]}]

# 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.

## Examples

    1> Dict0 = dict:from_list([{a,[]}]).
    2> Dict1 = dict:append_list(a, [1,2,3], Dict0).
    3> dict:to_list(Dict1).
    [{a,[1,2,3]}]

# erase(Key, Dict1)

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

Erases an item with a given key from a dictionary.

## Examples

    1> Dict0 = dict:from_list([{2,b},{1,a}]).
    2> Dict1 = dict:erase(2, Dict0).
    3> dict:to_list(Dict1).
    [{1,a}]
    4> Dict2 = dict:erase(99, Dict0).

# 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.

## Examples

    1> Dict = dict:from_list([{2,b},{1,a}]).
    2> dict:fetch(1, Dict).
    a

# 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`.

## Examples

    1> Dict = dict:from_list([{2,b},{1,a}]).
    2> lists:sort(dict:fetch_keys(Dict)).
    [1,2]

# filter(Pred, Dict1)

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

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

## Examples

    1> Dict0 = dict:from_list([{a,1},{b,2},{c,3}]).
    2> Dict1 = dict:filter(fun(_, V) -> V rem 2 =:= 1 end, Dict0).
    3> lists:sort(dict:to_list(Dict1)).
    [{a,1},{c,3}]

# 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.

## Examples

    1> Dict = dict:from_list([{2,b},{1,a}]).
    2> dict:find(1, Dict).
    {ok,a}
    3> dict:find(99, Dict).
    error

# 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.

## Examples

    1> Dict0 = dict:from_list([{a,1},{b,2},{c,3}]).
    2> dict:fold(fun(_, N, Acc) -> Acc + N end, 0, Dict0).
    6

# from_list(List)

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

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

## Examples

    1> Dict = dict:from_list([{2,b},{1,a}]).
    2> lists:sort(dict:to_list(Dict)).
    [{1,a},{2,b}]

# is_empty(Dict)

(since OTP 17.0)

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

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

## Examples

    1> Dict = dict:new().
    2> dict:is_empty(Dict).
    true

# is_key(Key, Dict)

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

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

## Examples

    1> Dict = dict:from_list([{count,0}]).
    2> dict:is_key(count, Dict).
    true
    3> dict:is_key(table, Dict).
    false

# 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.

## Examples

    1> Dict0 = dict:from_list([{a,1},{b,2},{c,3}]).
    2> Dict1 = dict:map(fun(_, V) -> 2 * V end, Dict0).
    3> lists:sort(dict:to_list(Dict1)).
    [{a,2},{b,4},{c,6}]

# 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.

## Examples

    1> Dict0 = dict:from_list([{a,1},{b,2}]).
    2> Dict1 = dict:from_list([{b,7},{c,99}]).
    3> Dict2 = dict:merge(fun(_, V1, V2) -> V1 + V2 end, Dict0, Dict1).
    4> lists:sort(dict:to_list(Dict2)).
    [{a,1},{b,9},{c,99}]

# new()

    -spec new() -> dict().

Creates a new dictionary.

## Examples

    1> dict:new().

# size(Dict)

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

Returns the number of elements in dictionary `Dict`.

## Examples

    1> Dict = dict:from_list([{2,b},{1,a}]).
    2> dict:size(Dict).
    2

# 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 a dictionary.

If `Key` already exists in `Dict1`, the associated value is replaced by `Value`.

## Examples

    1> Dict0 = dict:new().
    2> Dict1 = dict:store(name, arne, Dict0).
    3> dict:to_list(Dict1).
    [{name,arne}]
    4> Dict2 = dict:store(name, kalle, Dict1).
    5> dict:to_list(Dict2).
    [{name,kalle}]

# 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 a value from a dictionary and a new dictionary without this value.

Returns `error` if the key is not present in the dictionary.

## Examples

    1> Dict0 = dict:from_list([{2,b},{1,a}]).
    2> {V, Dict2} = dict:take(1, Dict0).
    3> V.
    a
    4> dict:to_list(Dict2).
    [{2,b}]

# to_list(Dict)

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

Converts a dictionary to a list representation.

## Examples

    1> Dict = dict:from_list([{2,b},{1,a}]).
    2> lists:sort(dict:to_list(Dict)).
    [{1,a},{2,b}]

# 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.

## Examples

    1> Dict0 = dict:from_list([{a,10}]).
    2> Dict1 = dict:update(a, fun(N) -> N + 1 end, Dict0).
    3> dict:to_list(Dict1).
    [{a,11}]

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.

## Examples

    1> Dict0 = dict:new().
    2> Inc = fun(N) -> N + 1 end.
    3> Dict1 = dict:update(a, Inc, 0, Dict0).
    4> dict:to_list(Dict1).
    [{a,0}]
    5> Dict2 = dict:update(a, Inc, 0, Dict1).
    6> dict:to_list(Dict2).
    [{a,1}]

# 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.

## Examples

    1> Dict0 = dict:new().
    2> Dict1 = dict:update_counter(a, 10, Dict0).
    3> dict:to_list(Dict1).
    [{a,10}]
    4> Dict2 = dict:update_counter(a, 10, Dict1).
    5> dict:to_list(Dict2).
    [{a,20}]