dict
Key-Value Dictionary
Dict
implements a Key
- Value
dictionary.
The representation of a dictionary is not defined.
This module provides exactly the same interface as the module
orddict
. 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 (==
).
Types
dict(Key, Value)
Dictionary as returned by new/0
.
dict()
dict()
is equivalent to dict(term(), term())
.
Functions
append(Key, Value, Dict1) -> Dict2
Dict1 = Dict2 = dict(Key, Value)
This function appends a new
to the current list
of values associated with
.
append_list(Key, ValList, Dict1) -> Dict2
Dict1 = Dict2 = dict(Key, Value)
ValList = [Value]
This function appends a list of values
to
the current list of values associated with
. An
exception is generated if the initial value associated with
is not a list of values.
erase(Key, Dict1) -> Dict2
Dict1 = Dict2 = dict(Key, Value)
This function erases all items with a given key from a dictionary.
fetch(Key, Dict) -> Value
Dict = dict(Key, Value)
This function returns the value associated with
in the dictionary
. fetch
assumes that
the
is present in the dictionary and an exception
is generated if
is not in the dictionary.
fetch_keys(Dict) -> Keys
Dict = dict(Key, Value :: term())
Keys = [Key]
This function returns a list of all keys in the dictionary.
filter(Pred, Dict1) -> Dict2
Pred = fun((Key, Value) -> boolean())
Dict1 = Dict2 = dict(Key, Value)
is a dictionary of all keys and values in
for which
is true
.
find(Key, Dict) -> {ok, Value} | error
Dict = dict(Key, Value)
This function searches for a key in a dictionary. Returns
{ok,
where
is the value associated
with
, or error
if the key is not present in
the dictionary.
fold(Fun, Acc0, Dict) -> Acc1
Fun = fun((Key, Value, AccIn) -> AccOut)
Dict = dict(Key, Value)
Acc0 = Acc1 = AccIn = AccOut = Acc
Calls
on successive keys and values of
together with an extra argument Acc
(short for accumulator).
must return a new
accumulator which is passed to the next call.
is
returned if the list is empty. The evaluation order is
undefined.
from_list(List) -> Dict
Dict = dict(Key, Value)
List = [{Key, Value}]
This function converts the
-
list
to a dictionary.
is_key(Key, Dict) -> boolean()
Dict = dict(Key, Value :: term())
This function tests if
is contained in
the dictionary
.
map(Fun, Dict1) -> Dict2
map
calls
on successive keys and values
of
to return a new value for each key.
The evaluation order is undefined.
merge(Fun, Dict1, Dict2) -> Dict3
Fun = fun((Key, Value1, Value2) -> Value)
Dict1 = dict(Key, Value1)
Dict2 = dict(Key, Value2)
Dict3 = dict(Key, Value)
merge
merges two dictionaries,
and
, to create a new dictionary. All the
-
pairs from both dictionaries are included in
the new dictionary. If a key occurs in both dictionaries then
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() -> dict()
This function creates a new dictionary.
store(Key, Value, Dict1) -> Dict2
Dict1 = Dict2 = dict(Key, Value)
This function stores a
-
pair in a
dictionary. If the
already exists in
,
the associated value is replaced by
.
to_list(Dict) -> List
Dict = dict(Key, Value)
List = [{Key, Value}]
This function converts the dictionary to a list representation.
update(Key, Fun, Dict1) -> Dict2
Dict1 = Dict2 = dict(Key, Value)
Fun = fun((Value1 :: Value) -> Value2 :: Value)
Update a value in a dictionary by calling
on
the value to get a new value. An exception is generated if
is not present in the dictionary.
update(Key, Fun, Initial, Dict1) -> Dict2
Dict1 = Dict2 = dict(Key, Value)
Fun = fun((Value1 :: Value) -> Value2 :: Value)
Initial = Value
Update a value in a dictionary by calling
on
the value to get a new value. If
is not present
in the dictionary then
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
Dict1 = Dict2 = dict(Key, Value)
Increment = number()
Add
to the value associated with
and store this value. If
is not present in
the dictionary then
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
.