1orddict(3)                 Erlang Module Definition                 orddict(3)
2
3
4

NAME

6       orddict - Key-value dictionary as ordered list.
7

DESCRIPTION

9       This  module provides a Key-Value dictionary. An orddict is a represen‐
10       tation of a dictionary, where a list of pairs is used to store the keys
11       and  values.  The list is ordered after the keys in the Erlang term or‐
12       der.
13
14       This module provides the same interface as the dict(3) module but  with
15       a  defined  representation. One difference is that while dict considers
16       two keys as different if they do not match (=:=), this module considers
17       two keys as different if and only if they do not compare equal (==).
18

DATA TYPES

20       orddict(Key, Value) = [{Key, Value}]
21
22              Dictionary as returned by new/0.
23
24       orddict() = orddict(term(), term())
25

EXPORTS

27       append(Key, Value, Orddict1) -> Orddict2
28
29              Types:
30
31                 Orddict1 = Orddict2 = orddict(Key, Value)
32
33              Appends  a  new  Value  to the current list of values associated
34              with Key. An exception is generated if the initial value associ‐
35              ated with Key is not a list of values.
36
37              See also section Notes.
38
39       append_list(Key, ValList, Orddict1) -> Orddict2
40
41              Types:
42
43                 ValList = [Value]
44                 Orddict1 = Orddict2 = orddict(Key, Value)
45
46              Appends  a  list of values ValList to the current list of values
47              associated with Key. An exception is generated  if  the  initial
48              value associated with Key is not a list of values.
49
50              See also section Notes.
51
52       erase(Key, Orddict1) -> Orddict2
53
54              Types:
55
56                 Orddict1 = Orddict2 = orddict(Key, Value)
57
58              Erases all items with a specified key from a dictionary.
59
60       fetch(Key, Orddict) -> Value
61
62              Types:
63
64                 Orddict = orddict(Key, Value)
65
66              Returns  the  value  associated  with Key in dictionary Orddict.
67              This function assumes that the Key is present in the dictionary.
68              An exception is generated if Key is not in the dictionary.
69
70              See also section Notes.
71
72       fetch_keys(Orddict) -> Keys
73
74              Types:
75
76                 Orddict = orddict(Key, Value :: term())
77                 Keys = [Key]
78
79              Returns a list of all keys in a dictionary.
80
81       take(Key, Orddict) -> {Value, Orddict1} | error
82
83              Types:
84
85                 Orddict = Orddict1 = orddict(Key, Value)
86                 Key = Value = term()
87
88              This  function  returns value from dictionary and new dictionary
89              without this value. Returns error if the key is not  present  in
90              the dictionary.
91
92       filter(Pred, Orddict1) -> Orddict2
93
94              Types:
95
96                 Pred = fun((Key, Value) -> boolean())
97                 Orddict1 = Orddict2 = orddict(Key, Value)
98
99              Orddict2  is a dictionary of all keys and values in Orddict1 for
100              which Pred(Key, Value) is true.
101
102       find(Key, Orddict) -> {ok, Value} | error
103
104              Types:
105
106                 Orddict = orddict(Key, Value)
107
108              Searches for a key in a dictionary. Returns {ok,  Value},  where
109              Value  is  the value associated with Key, or error if the key is
110              not present in the dictionary.
111
112              See also section Notes.
113
114       fold(Fun, Acc0, Orddict) -> Acc1
115
116              Types:
117
118                 Fun = fun((Key, Value, AccIn) -> AccOut)
119                 Orddict = orddict(Key, Value)
120                 Acc0 = Acc1 = AccIn = AccOut = Acc
121
122              Calls Fun on successive keys and values of Orddict together with
123              an extra argument Acc (short for accumulator). Fun must return a
124              new accumulator that is passed to the next  call.  Acc0  is  re‐
125              turned if the list is empty.
126
127       from_list(List) -> Orddict
128
129              Types:
130
131                 List = [{Key, Value}]
132                 Orddict = orddict(Key, Value)
133
134              Converts the Key-Value list List to a dictionary.
135
136       is_empty(Orddict) -> boolean()
137
138              Types:
139
140                 Orddict = orddict()
141
142              Returns true if Orddict has no elements, otherwise false.
143
144       is_key(Key, Orddict) -> boolean()
145
146              Types:
147
148                 Orddict = orddict(Key, Value :: term())
149
150              Tests if Key is contained in dictionary Orddict.
151
152       map(Fun, Orddict1) -> Orddict2
153
154              Types:
155
156                 Fun = fun((Key, Value1) -> Value2)
157                 Orddict1 = orddict(Key, Value1)
158                 Orddict2 = orddict(Key, Value2)
159
160              Calls Fun on successive keys and values of Orddict1 tvo return a
161              new value for each key.
162
163       merge(Fun, Orddict1, Orddict2) -> Orddict3
164
165              Types:
166
167                 Fun = fun((Key, Value1, Value2) -> Value)
168                 Orddict1 = orddict(Key, Value1)
169                 Orddict2 = orddict(Key, Value2)
170                 Orddict3 = orddict(Key, Value)
171
172              Merges two dictionaries, Orddict1 and Orddict2, to create a  new
173              dictionary.  All  the Key-Value pairs from both dictionaries are
174              included in the new dictionary. If a key occurs in both  dictio‐
175              naries,  Fun  is called with the key and both values to return a
176              new value. merge/3 can be defined as follows, but is faster:
177
178              merge(Fun, D1, D2) ->
179                  fold(fun (K, V1, D) ->
180                               update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
181                       end, D2, D1).
182
183       new() -> orddict()
184
185              Creates a new dictionary.
186
187       size(Orddict) -> integer() >= 0
188
189              Types:
190
191                 Orddict = orddict()
192
193              Returns the number of elements in an Orddict.
194
195       store(Key, Value, Orddict1) -> Orddict2
196
197              Types:
198
199                 Orddict1 = Orddict2 = orddict(Key, Value)
200
201              Stores a Key-Value pair in a dictionary. If the Key already  ex‐
202              ists in Orddict1, the associated value is replaced by Value.
203
204       to_list(Orddict) -> List
205
206              Types:
207
208                 Orddict = orddict(Key, Value)
209                 List = [{Key, Value}]
210
211              Converts a dictionary to a list representation.
212
213       update(Key, Fun, Orddict1) -> Orddict2
214
215              Types:
216
217                 Fun = fun((Value1 :: Value) -> Value2 :: Value)
218                 Orddict1 = Orddict2 = orddict(Key, Value)
219
220              Updates  a  value in a dictionary by calling Fun on the value to
221              get a new value. An exception is generated if Key is not present
222              in the dictionary.
223
224       update(Key, Fun, Initial, Orddict1) -> Orddict2
225
226              Types:
227
228                 Initial = Value
229                 Fun = fun((Value1 :: Value) -> Value2 :: Value)
230                 Orddict1 = Orddict2 = orddict(Key, Value)
231
232              Updates  a  value in a dictionary by calling Fun on the value to
233              get a new value. If Key is not present in the  dictionary,  Ini‐
234              tial  is stored as the first value. For example, append/3 can be
235              defined as follows:
236
237              append(Key, Val, D) ->
238                  update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).
239
240       update_counter(Key, Increment, Orddict1) -> Orddict2
241
242              Types:
243
244                 Orddict1 = Orddict2 = orddict(Key, Value)
245                 Increment = number()
246
247              Adds Increment to the value associated with Key and  store  this
248              value.  If  Key  is  not present in the dictionary, Increment is
249              stored as the first value.
250
251              This can be defined as follows, but is faster:
252
253              update_counter(Key, Incr, D) ->
254                  update(Key, fun (Old) -> Old + Incr end, Incr, D).
255

NOTES

257       Functions append/3 and append_list/3 are included so that keyed  values
258       can be stored in a list accumulator, for example:
259
260       > D0 = orddict:new(),
261         D1 = orddict:store(files, [], D0),
262         D2 = orddict:append(files, f1, D1),
263         D3 = orddict:append(files, f2, D2),
264         D4 = orddict:append(files, f3, D3),
265         orddict:fetch(files, D4).
266       [f1,f2,f3]
267
268       This saves the trouble of first fetching a keyed value, appending a new
269       value to the list of stored values, and storing the result.
270
271       Function fetch/2 is to be used if the key is known to be in the dictio‐
272       nary, otherwise function find/2.
273

SEE ALSO

275       dict(3), gb_trees(3)
276
277
278
279Ericsson AB                       stdlib 4.2                        orddict(3)