orddict
Key-Value Dictionary as Ordered List
Orddict
implements a Key
- Value
dictionary.
An orddict
is a representation of a dictionary, where a
list of pairs is used to store the keys and values. The list is
ordered after the keys.
This module provides exactly the same interface as the module
dict
but with a defined representation. One difference is
that while dict
considers two keys as different if they
do not match (=:=
), this module considers two keys as
different if and only if they do not compare equal
(==
).
Functions
append(Key, Value, Orddict1) -> Orddict2
Key = Value = term()
Orddict1 = Orddict2 = orddict()
This function appends a new
to the current list
of values associated with
. An exception is
generated if the initial value associated with
is
not a list of values.
append_list(Key, ValList, Orddict1) -> Orddict2
Key = term()
ValList = [Value :: term()]
Orddict1 = Orddict2 = orddict()
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, Orddict1) -> Orddict2
Key = term()
Orddict1 = Orddict2 = orddict()
This function erases all items with a given key from a dictionary.
fetch(Key, Orddict) -> Value
Key = Value = term()
Orddict = orddict()
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(Orddict) -> Keys
Orddict = orddict()
Keys = [term()]
This function returns a list of all keys in the dictionary.
filter(Pred, Orddict1) -> Orddict2
Pred = fun((Key :: term(), Value :: term()) -> boolean())
Orddict1 = Orddict2 = orddict()
is a dictionary of all keys and values in
for which
is true
.
find(Key, Orddict) -> {ok, Value} | error
Key = term()
Orddict = orddict()
Value = term()
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, Orddict) -> Acc1
Fun =
fun((Key :: term(), Value :: term(), AccIn :: term()) ->
AccOut :: term())Acc0 = Acc1 = term()
Orddict = orddict()
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) -> Orddict
List = [{Key :: term(), Value :: term()}]
Orddict = orddict()
This function converts the
-
list
to a dictionary.
is_key(Key, Orddict) -> boolean()
Key = term()
Orddict = orddict()
This function tests if
is contained in
the dictionary
.
map(Fun, Orddict1) -> Orddict2
Fun =
fun((Key :: term(), Value1 :: term()) -> Value2 :: term())Orddict1 = Orddict2 = orddict()
map
calls
on successive keys and values
of
to return a new value for each key.
The evaluation order is undefined.
merge(Fun, Orddict1, Orddict2) -> Orddict3
Fun =
fun((Key :: term(), Value1 :: term(), Value2 :: term()) ->
Value :: term())Orddict1 = Orddict2 = Orddict3 = orddict()
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() -> orddict()
This function creates a new dictionary.
store(Key, Value, Orddict1) -> Orddict2
Key = Value = term()
Orddict1 = Orddict2 = orddict()
This function stores a
-
pair in a
dictionary. If the
already exists in
,
the associated value is replaced by
.
to_list(Orddict) -> List
Orddict = orddict()
List = [{Key :: term(), Value :: term()}]
This function converts the dictionary to a list representation.
update(Key, Fun, Orddict1) -> Orddict2
Key = term()
Fun = fun((Value1 :: term()) -> Value2 :: term())
Orddict1 = Orddict2 = orddict()
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, Orddict1) -> Orddict2
Key = Initial = term()
Fun = fun((Value1 :: term()) -> Value2 :: term())
Orddict1 = Orddict2 = orddict()
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, Orddict1) -> Orddict2
Key = term()
Increment = number()
Orddict1 = Orddict2 = orddict()
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 = orddict:new(), D1 = orddict:store(files, [], D0), D2 = orddict:append(files, f1, D1), D3 = orddict:append(files, f2, D2), D4 = orddict:append(files, f3, D3), orddict: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
.