.TH orddict 3 "stdlib  1.15.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
orddict \- Key-Value Dictionary as Ordered List
.SH DESCRIPTION
.LP
\fIOrddict\fR implements a \fIKey\fR - \fIValue\fR dictionary\&. An \fIorddict\fR 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\&.
.LP
This module provides exactly the same interface as the module \fIdict\fR but with a defined representation\&. One difference is that while \fIdict\fR considers two keys as different if they do not match (\fI=:=\fR), this module considers two keys as different if and only if they do not compare equal (\fI==\fR)\&.

.SH DATA TYPES

.nf
ordered_dictionary()
  as returned by new/0
.fi
.SH EXPORTS
.LP
.B
append(Key, Value, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Key = Value = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
This function appends a new \fIValue\fR to the current list of values associated with \fIKey\fR\&. An exception is generated if the initial value associated with \fIKey\fR is not a list of values\&.
.RE
.LP
.B
append_list(Key, ValList, Orddict1) -> Orddict2
.br
.RS
.TP
Types
ValList = [Value]
.br
Key = Value = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
This function appends a list of values \fIValList\fR to the current list of values associated with \fIKey\fR\&. An exception is generated if the initial value associated with \fIKey\fR is not a list of values\&.
.RE
.LP
.B
erase(Key, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Key = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
This function erases all items with a given key from a dictionary\&.
.RE
.LP
.B
fetch(Key, Orddict) -> Value
.br
.RS
.TP
Types
Key = Value = term()
.br
Orddict = ordered_dictionary()
.br
.RE
.RS
.LP
This function returns the value associated with \fIKey\fR in the dictionary \fIOrddict\fR\&. \fIfetch\fR assumes that the \fIKey\fR is present in the dictionary and an exception is generated if \fIKey\fR is not in the dictionary\&.
.RE
.LP
.B
fetch_keys(Orddict) -> Keys
.br
.RS
.TP
Types
Orddict = ordered_dictionary()
.br
Keys = [term()]
.br
.RE
.RS
.LP
This function returns a list of all keys in the dictionary\&.
.RE
.LP
.B
filter(Pred, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Pred = fun(Key, Value) -> bool()
.br
Key = Value = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
\fIOrddict2\fR is a dictionary of all keys and values in \fIOrddict1\fR for which \fIPred(Key, Value)\fR is \fItrue\fR\&.
.RE
.LP
.B
find(Key, Orddict) -> {ok, Value} | error
.br
.RS
.TP
Types
Key = Value = term()
.br
Orddict = ordered_dictionary()
.br
.RE
.RS
.LP
This function searches for a key in a dictionary\&. Returns \fI{ok, Value}\fR where \fIValue\fR is the value associated with \fIKey\fR, or \fIerror\fR if the key is not present in the dictionary\&.
.RE
.LP
.B
fold(Fun, Acc0, Orddict) -> Acc1
.br
.RS
.TP
Types
Fun = fun(Key, Value, AccIn) -> AccOut
.br
Key = Value = term()
.br
Acc0 = Acc1 = AccIn = AccOut = term()
.br
Orddict = ordered_dictionary()
.br
.RE
.RS
.LP
Calls \fIFun\fR on successive keys and values of \fIOrddict\fR together with an extra argument \fIAcc\fR (short for accumulator)\&. \fIFun\fR must return a new accumulator which is passed to the next call\&. \fIAcc0\fR is returned if the list is empty\&. The evaluation order is undefined\&.
.RE
.LP
.B
from_list(List) -> Orddict
.br
.RS
.TP
Types
List = [{Key, Value}]
.br
Orddict = ordered_dictionary()
.br
.RE
.RS
.LP
This function converts the key/value list \fIList\fR to a dictionary\&.
.RE
.LP
.B
is_key(Key, Orddict) -> bool()
.br
.RS
.TP
Types
Key = term()
.br
Orddict = ordered_dictionary()
.br
.RE
.RS
.LP
This function tests if \fIKey\fR is contained in the dictionary \fIOrddict\fR\&.
.RE
.LP
.B
map(Fun, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Fun = fun(Key, Value1) -> Value2
.br
Key = Value1 = Value2 = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
\fImap\fR calls \fIFunc\fR on successive keys and values of \fIOrddict\fR to return a new value for each key\&. The evaluation order is undefined\&.
.RE
.LP
.B
merge(Fun, Orddict1, Orddict2) -> Orddict3
.br
.RS
.TP
Types
Fun = fun(Key, Value1, Value2) -> Value
.br
Key = Value1 = Value2 = Value3 = term()
.br
Orddict1 = Orddict2 = Orddict3 = ordered_dictionary()
.br
.RE
.RS
.LP
\fImerge\fR merges two dictionaries, \fIOrddict1\fR and \fIOrddict2\fR, to create a new dictionary\&. All the \fIKey\fR - \fIValue\fR pairs from both dictionaries are included in the new dictionary\&. If a key occurs in both dictionaries then \fIFun\fR is called with the key and both values to return a new value\&. \fImerge\fR could be defined as:

.nf
merge(Fun, D1, D2) ->
    fold(fun (K, V1, D) ->
                 update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
         end, D2, D1)\&.
.fi
.LP
but is faster\&.
.RE
.LP
.B
new() -> ordered_dictionary()
.br
.RS
.LP
This function creates a new dictionary\&.
.RE
.LP
.B
size(Orddict) -> int()
.br
.RS
.TP
Types
Orddict = ordered_dictionary()
.br
.RE
.RS
.LP
Returns the number of elements in an \fIOrddict\fR\&.
.RE
.LP
.B
store(Key, Value, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Key = Value = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
This function stores a \fIKey\fR - \fIValue\fR pair in a dictionary\&. If the \fIKey\fR already exists in \fIOrddict1\fR, the associated value is replaced by \fIValue\fR\&.
.RE
.LP
.B
to_list(Orddict) -> List
.br
.RS
.TP
Types
Orddict = ordered_dictionary()
.br
List = [{Key, Value}]
.br
.RE
.RS
.LP
This function converts the dictionary to a list representation\&.
.RE
.LP
.B
update(Key, Fun, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Key = term()
.br
Fun = fun(Value1) -> Value2
.br
Value1 = Value2 = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
Update the a value in a dictionary by calling \fIFun\fR on the value to get a new value\&. An exception is generated if \fIKey\fR is not present in the dictionary\&.
.RE
.LP
.B
update(Key, Fun, Initial, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Key = Initial = term()
.br
Fun = fun(Value1) -> Value2
.br
Value1 = Value2 = term()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
Update the a value in a dictionary by calling \fIFun\fR on the value to get a new value\&. If \fIKey\fR is not present in the dictionary then \fIInitial\fR will be stored as the first value\&. For example \fIappend/3\fR could be defined as:

.nf
append(Key, Val, D) ->
    update(Key, fun (Old) -> Old ++ [Val] end, [Val], D)\&.
.fi
.RE
.LP
.B
update_counter(Key, Increment, Orddict1) -> Orddict2
.br
.RS
.TP
Types
Key = term()
.br
Increment = number()
.br
Orddict1 = Orddict2 = ordered_dictionary()
.br
.RE
.RS
.LP
Add \fIIncrement\fR to the value associated with \fIKey\fR and store this value\&. If \fIKey\fR is not present in the dictionary then \fIIncrement\fR will be stored as the first value\&.
.LP
This could be defined as:

.nf
update_counter(Key, Incr, D) ->
    update(Key, fun (Old) -> Old + Incr end, Incr, D)\&.
.fi
.LP
but is faster\&.
.RE
.SH NOTES
.LP
The functions \fIappend\fR and \fIappend_list\fR are included so we can store keyed values in a list \fIaccumulator\fR\&. For example:

.nf
> 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]    
.fi
.LP
This saves the trouble of first fetching a keyed value, appending a new value to the list of stored values, and storing the result\&. 
.LP
The function \fIfetch\fR should be used if the key is known to be in the dictionary, otherwise \fIfind\fR\&.
.SH SEE ALSO
.LP
dict(3), gb_trees(3)