dict
(stdlib)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 (==
).
DATA TYPES
dictionary() as returned by new/0
Functions
append(Key, Value, Dict1) -> Dict2
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
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
Key = term()
Dict1 = Dict2 = dictionary()
This function erases all items with a given key from a dictionary.
fetch(Key, Dict) -> Value
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
Dict = dictionary()
Keys = [term()]
This function returns a list of all keys in the dictionary.
filter(Pred, Dict1) -> Dict2
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
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
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
List = [{Key, Value}]
Dict = dictionary()
This function converts the key/value list List
to a
dictionary.
is_key(Key, Dict) -> bool()
Key = term()
Dict = dictionary()
This function tests if Key
is contained in
the dictionary Dict
.
map(Fun, Dict1) -> Dict2
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
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.
size(Dict) -> int()
Dict = dictionary()
Returns the number of elements in a Dict
.
store(Key, Value, Dict1) -> Dict2
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
Dict = dictionary()
List = [{Key, Value}]
This function converts the dictionary to a list representation.
update(Key, Fun, Dict1) -> Dict2
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
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
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
.