.TH orddict 3erl "stdlib 4.3.1.4" "Ericsson AB" "Erlang Module Definition"
.SH NAME
orddict \- Key-value dictionary as ordered list.
.SH DESCRIPTION
.LP
This module provides 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 in the \fIErlang term order\fR\&\&.
.LP
This module provides the same interface as the \fIdict(3erl)\fR\& module 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

\fBorddict(Key, Value)\fR\& = [{Key, Value}]
.br
.fi
.RS
.LP
Dictionary as returned by \fInew/0\fR\&\&.
.RE

.nf

\fBorddict()\fR\& = orddict(term(), term())
.br
.fi
.SH EXPORTS
.LP
.nf

.B
append(Key, Value, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict1 = Orddict2 = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
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\&.
.LP
See also section Notes\&.
.RE

.LP
.nf

.B
append_list(Key, ValList, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
ValList = [Value]
.br
Orddict1 = Orddict2 = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
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\&.
.LP
See also section Notes\&.
.RE

.LP
.nf

.B
erase(Key, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict1 = Orddict2 = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
Erases all items with a specified key from a dictionary\&.
.RE

.LP
.nf

.B
fetch(Key, Orddict) -> Value
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
Returns the value associated with \fIKey\fR\& in dictionary \fIOrddict\fR\&\&. This function assumes that the \fIKey\fR\& is present in the dictionary\&. An exception is generated if \fIKey\fR\& is not in the dictionary\&.
.LP
See also section Notes\&.
.RE

.LP
.nf

.B
fetch_keys(Orddict) -> Keys
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = orddict(Key, Value :: term())
.br
Keys = [Key]
.br
.RE
.RE
.RS
.LP
Returns a list of all keys in a dictionary\&.
.RE

.LP
.nf

.B
take(Key, Orddict) -> {Value, Orddict1} | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = Orddict1 = orddict(Key, Value)
.br
Key = Value = term()
.br
.RE
.RE
.RS
.LP
This function returns value from dictionary and new dictionary without this value\&. Returns \fIerror\fR\& if the key is not present in the dictionary\&.
.RE

.LP
.nf

.B
filter(Pred, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Pred = fun((Key, Value) -> boolean())
.br
Orddict1 = Orddict2 = orddict(Key, Value)
.br
.RE
.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
.nf

.B
find(Key, Orddict) -> {ok, Value} | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
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\&.
.LP
See also section Notes\&.
.RE

.LP
.nf

.B
fold(Fun, Acc0, Orddict) -> Acc1
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Fun = fun((Key, Value, AccIn) -> AccOut)
.br
Orddict = orddict(Key, Value)
.br
Acc0 = Acc1 = AccIn = AccOut = Acc
.br
.RE
.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 that is passed to the next call\&. \fIAcc0\fR\& is returned if the list is empty\&.
.RE

.LP
.nf

.B
from_list(List) -> Orddict
.br
.fi
.br
.RS
.LP
Types:

.RS 3
List = [{Key, Value}]
.br
Orddict = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
Converts the \fIKey\fR\&-\fIValue\fR\& list \fIList\fR\& to a dictionary\&.
.RE

.LP
.nf

.B
is_empty(Orddict) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = orddict()
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fIOrddict\fR\& has no elements, otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
is_key(Key, Orddict) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = orddict(Key, Value :: term())
.br
.RE
.RE
.RS
.LP
Tests if \fIKey\fR\& is contained in dictionary \fIOrddict\fR\&\&.
.RE

.LP
.nf

.B
map(Fun, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Fun = fun((Key, Value1) -> Value2)
.br
Orddict1 = orddict(Key, Value1)
.br
Orddict2 = orddict(Key, Value2)
.br
.RE
.RE
.RS
.LP
Calls \fIFun\fR\& on successive keys and values of \fIOrddict1\fR\& tvo return a new value for each key\&.
.RE

.LP
.nf

.B
merge(Fun, Orddict1, Orddict2) -> Orddict3
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Fun = fun((Key, Value1, Value2) -> Value)
.br
Orddict1 = orddict(Key, Value1)
.br
Orddict2 = orddict(Key, Value2)
.br
Orddict3 = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
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, \fIFun\fR\& is called with the key and both values to return a new value\&. \fImerge/3\fR\& can be defined as follows, but is faster:
.LP
.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
.RE

.LP
.nf

.B
new() -> orddict()
.br
.fi
.br
.RS
.LP
Creates a new dictionary\&.
.RE

.LP
.nf

.B
size(Orddict) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = orddict()
.br
.RE
.RE
.RS
.LP
Returns the number of elements in an \fIOrddict\fR\&\&.
.RE

.LP
.nf

.B
store(Key, Value, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict1 = Orddict2 = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
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
.nf

.B
to_list(Orddict) -> List
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict = orddict(Key, Value)
.br
List = [{Key, Value}]
.br
.RE
.RE
.RS
.LP
Converts a dictionary to a list representation\&.
.RE

.LP
.nf

.B
update(Key, Fun, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Fun = fun((Value1 :: Value) -> Value2 :: Value)
.br
Orddict1 = Orddict2 = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
Updates 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
.nf

.B
update(Key, Fun, Initial, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Initial = Value
.br
Fun = fun((Value1 :: Value) -> Value2 :: Value)
.br
Orddict1 = Orddict2 = orddict(Key, Value)
.br
.RE
.RE
.RS
.LP
Updates 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, \fIInitial\fR\& is stored as the first value\&. For example, \fIappend/3\fR\& can be defined as follows:
.LP
.nf

append(Key, Val, D) ->
    update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).
.fi
.RE

.LP
.nf

.B
update_counter(Key, Increment, Orddict1) -> Orddict2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Orddict1 = Orddict2 = orddict(Key, Value)
.br
Increment = number()
.br
.RE
.RE
.RS
.LP
Adds \fIIncrement\fR\& to the value associated with \fIKey\fR\& and store this value\&. If \fIKey\fR\& is not present in the dictionary, \fIIncrement\fR\& is stored as the first value\&.
.LP
This can be defined as follows, but is faster:
.LP
.nf

update_counter(Key, Incr, D) ->
    update(Key, fun (Old) -> Old + Incr end, Incr, D).
.fi
.RE

.SH "NOTES"

.LP
Functions \fIappend/3\fR\& and \fIappend_list/3\fR\& are included so that keyed values can be stored in a list \fIaccumulator\fR\&, for example:
.LP
.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
Function \fIfetch/2\fR\& is to be used if the key is known to be in the dictionary, otherwise function \fIfind/2\fR\&\&.
.SH "SEE ALSO"

.LP
\fIdict(3erl)\fR\&, \fIgb_trees(3erl)\fR\&