--- name: "orddict" section: "3erl" platform: "linux" package: "erlang-manpages" version: "1:25.2.3+dfsg-1+deb12u4" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/orddict" --- # orddict(3erl) Key-value dictionary as ordered list. ## NAME orddict - Key-value dictionary as ordered list. ## DESCRIPTION This module provides 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 in the *Erlang term order*. This module provides the same interface as the *[dict(3erl)](/dict/3erl.md)* module 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 (*==*). ## DATA TYPES ``` orddict(Key, Value) = [{Key, Value}] ``` Dictionary as returned by *new/0*. ``` orddict() = orddict(term(), term()) ``` ## EXPORTS ``` append(Key, Value, Orddict1) -> Orddict2 ``` Types: Orddict1 = Orddict2 = orddict(Key, Value)\ 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. See also section Notes. ``` append_list(Key, ValList, Orddict1) -> Orddict2 ``` Types: ValList = \[Value\]\ Orddict1 = Orddict2 = orddict(Key, Value)\ 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. See also section Notes. ``` erase(Key, Orddict1) -> Orddict2 ``` Types: Orddict1 = Orddict2 = orddict(Key, Value)\ Erases all items with a specified key from a dictionary. ``` fetch(Key, Orddict) -> Value ``` Types: Orddict = orddict(Key, Value)\ Returns the value associated with *Key* in dictionary *Orddict*. This function assumes that the *Key* is present in the dictionary. An exception is generated if *Key* is not in the dictionary. See also section Notes. ``` fetch_keys(Orddict) -> Keys ``` Types: Orddict = orddict(Key, Value :: term())\ Keys = \[Key\]\ Returns a list of all keys in a dictionary. ``` take(Key, Orddict) -> {Value, Orddict1} | error ``` Types: Orddict = Orddict1 = orddict(Key, Value)\ Key = Value = term()\ This function returns value from dictionary and new dictionary without this value. Returns *error* if the key is not present in the dictionary. ``` filter(Pred, Orddict1) -> Orddict2 ``` Types: Pred = fun((Key, Value) -\> boolean())\ Orddict1 = Orddict2 = orddict(Key, Value)\ *Orddict2* is a dictionary of all keys and values in *Orddict1* for which *Pred(Key, Value)* is *true*. ``` find(Key, Orddict) -> {ok, Value} | error ``` Types: Orddict = orddict(Key, Value)\ 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. See also section Notes. ``` fold(Fun, Acc0, Orddict) -> Acc1 ``` Types: Fun = fun((Key, Value, AccIn) -\> AccOut)\ Orddict = orddict(Key, Value)\ Acc0 = Acc1 = AccIn = AccOut = Acc\ Calls *Fun* on successive keys and values of *Orddict* together with an extra argument *Acc* (short for accumulator). *Fun* must return a new accumulator that is passed to the next call. *Acc0* is returned if the list is empty. ``` from_list(List) -> Orddict ``` Types: List = \[{Key, Value}\]\ Orddict = orddict(Key, Value)\ Converts the *Key*-*Value* list *List* to a dictionary. ``` is_empty(Orddict) -> boolean() ``` Types: Orddict = orddict()\ Returns *true* if *Orddict* has no elements, otherwise *false*. ``` is_key(Key, Orddict) -> boolean() ``` Types: Orddict = orddict(Key, Value :: term())\ Tests if *Key* is contained in dictionary *Orddict*. ``` map(Fun, Orddict1) -> Orddict2 ``` Types: Fun = fun((Key, Value1) -\> Value2)\ Orddict1 = orddict(Key, Value1)\ Orddict2 = orddict(Key, Value2)\ Calls *Fun* on successive keys and values of *Orddict1* tvo return a new value for each key. ``` merge(Fun, Orddict1, Orddict2) -> Orddict3 ``` Types: Fun = fun((Key, Value1, Value2) -\> Value)\ Orddict1 = orddict(Key, Value1)\ Orddict2 = orddict(Key, Value2)\ Orddict3 = orddict(Key, Value)\ Merges two dictionaries, *Orddict1* and *Orddict2*, 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, *Fun* is called with the key and both values to return a new value. *merge/3* can be defined as follows, but is faster: ``` merge(Fun, D1, D2) -> fold(fun (K, V1, D) -> update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D) end, D2, D1). ``` ``` new() -> orddict() ``` Creates a new dictionary. ``` size(Orddict) -> integer() >= 0 ``` Types: Orddict = orddict()\ Returns the number of elements in an *Orddict*. ``` store(Key, Value, Orddict1) -> Orddict2 ``` Types: Orddict1 = Orddict2 = orddict(Key, Value)\ Stores a *Key*-*Value* pair in a dictionary. If the *Key* already exists in *Orddict1*, the associated value is replaced by *Value*. ``` to_list(Orddict) -> List ``` Types: Orddict = orddict(Key, Value)\ List = \[{Key, Value}\]\ Converts a dictionary to a list representation. ``` update(Key, Fun, Orddict1) -> Orddict2 ``` Types: Fun = fun((Value1 :: Value) -\> Value2 :: Value)\ Orddict1 = Orddict2 = orddict(Key, Value)\ Updates 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, Orddict1) -> Orddict2 ``` Types: Initial = Value\ Fun = fun((Value1 :: Value) -\> Value2 :: Value)\ Orddict1 = Orddict2 = orddict(Key, Value)\ Updates a value in a dictionary by calling *Fun* on the value to get a new value. If *Key* is not present in the dictionary, *Initial* is stored as the first value. For example, *append/3* can be defined as follows: ``` append(Key, Val, D) -> update(Key, fun (Old) -> Old ++ [Val] end, [Val], D). ``` ``` update_counter(Key, Increment, Orddict1) -> Orddict2 ``` Types: Orddict1 = Orddict2 = orddict(Key, Value)\ Increment = number()\ Adds *Increment* to the value associated with *Key* and store this value. If *Key* is not present in the dictionary, *Increment* is stored as the first value. This can be defined as follows, but is faster: ``` update_counter(Key, Incr, D) -> update(Key, fun (Old) -> Old + Incr end, Incr, D). ``` ## NOTES Functions *append/3* and *append\_list/3* are included so that keyed values can be stored 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. Function *fetch/2* is to be used if the key is known to be in the dictionary, otherwise function *find/2*. ## SEE ALSO *[dict(3erl)](/dict/3erl.md)*, *[gb\_trees(3erl)](/gb_trees/3erl.md)*