orddict(3erl)

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              Example 1:
40
41              1> OrdDict1 = orddict:from_list([{x, []}]).
42              [{x,[]}]
43              2> OrdDict2 = orddict:append(x, 1, OrdDict1).
44              [{x,[1]}]
45              3> OrdDict3 = orddict:append(x, 2, OrdDict2).
46              [{x,[1,2]}]
47              4> orddict:append(y, 3, OrdDict3).
48              [{x,[1,2]},{y,[3]}]
49
50              Example 2:
51
52              1> OrdDict1 = orddict:from_list([{a, no_list}]).
53              [{a,no_list}]
54              2> orddict:append(a, 1, OrdDict1).
55              ** exception error: bad argument
56                   in operator  ++/2
57                      called as no_list ++ [1]
58
59       append_list(Key, ValList, Orddict1) -> Orddict2
60
61              Types:
62
63                 ValList = [Value]
64                 Orddict1 = Orddict2 = orddict(Key, Value)
65
66              Appends  a  list of values ValList to the current list of values
67              associated with Key. An exception is generated  if  the  initial
68              value associated with Key is not a list of values.
69
70              See also section Notes.
71
72              Example:
73
74              1> OrdDict1 = orddict:from_list([{x, []}]).
75              [{x,[]}]
76              2> OrdDict2 = orddict:append_list(x, [1,2], OrdDict1).
77              [{x,[1,2]}]
78              3> OrdDict3 = orddict:append_list(y, [3,4], OrdDict2).
79              [{x,[1,2]},{y,[3,4]}]
80
81       erase(Key, Orddict1) -> Orddict2
82
83              Types:
84
85                 Orddict1 = Orddict2 = orddict(Key, Value)
86
87              Erases all items with a specified key from a dictionary.
88
89              Example:
90
91              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
92              [{a,1},{b,2}]
93              2> orddict:erase(a, OrdDict1).
94              [{b,2}]
95
96       fetch(Key, Orddict) -> Value
97
98              Types:
99
100                 Orddict = orddict(Key, Value)
101
102              Returns  the  value  associated  with Key in dictionary Orddict.
103              This function assumes that the Key is present in the dictionary.
104              An exception is generated if Key is not in the dictionary.
105
106              See also section Notes.
107
108              Example:
109
110              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
111              [{a,1},{b,2}]
112              2> orddict:fetch(a, OrdDict1).
113              1
114              3> orddict:fetch(missing, OrdDict1).
115              ** exception error: no function clause matching orddict:fetch(missing,[])
116
117       fetch_keys(Orddict) -> Keys
118
119              Types:
120
121                 Orddict = orddict(Key, Value :: term())
122                 Keys = [Key]
123
124              Returns a list of all keys in a dictionary.
125
126              Example:
127
128              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
129              [{a,1},{b,2}]
130              2> orddict:fetch_keys(OrdDict1).
131              [a,b]
132
133       take(Key, Orddict) -> {Value, Orddict1} | error
134
135              Types:
136
137                 Orddict = Orddict1 = orddict(Key, Value)
138                 Key = Value = term()
139
140              This  function  returns value from dictionary and new dictionary
141              without this value. Returns error if the key is not  present  in
142              the dictionary.
143
144              Example:
145
146              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
147              [{a,1},{b,2}]
148              2> orddict:take(a, OrdDict1).
149              {1, [{b,2}]}
150              3> orddict:take(missing, OrdDict1).
151              error
152
153       filter(Pred, Orddict1) -> Orddict2
154
155              Types:
156
157                 Pred = fun((Key, Value) -> boolean())
158                 Orddict1 = Orddict2 = orddict(Key, Value)
159
160              Orddict2  is a dictionary of all keys and values in Orddict1 for
161              which Pred(Key, Value) is true.
162
163              Example:
164
165              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
166              [{a,1},{b,2}]
167              2> orddict:filter(fun (K, V) -> V > 1 end, OrdDict1).
168              [{b,2}]
169
170       find(Key, Orddict) -> {ok, Value} | error
171
172              Types:
173
174                 Orddict = orddict(Key, Value)
175
176              Searches for a key in a dictionary. Returns {ok,  Value},  where
177              Value  is  the value associated with Key, or error if the key is
178              not present in the dictionary.
179
180              See also section Notes.
181
182              Example:
183
184              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
185              [{a,1},{b,2}]
186              2> orddict:find(a, OrdDict1).
187              {ok,1}
188              3> orddict:find(c, OrdDict1).
189              error
190
191       fold(Fun, Acc0, Orddict) -> Acc1
192
193              Types:
194
195                 Fun = fun((Key, Value, AccIn) -> AccOut)
196                 Orddict = orddict(Key, Value)
197                 Acc0 = Acc1 = AccIn = AccOut = Acc
198
199              Calls Fun on successive keys and values of Orddict together with
200              an extra argument Acc (short for accumulator). Fun must return a
201              new accumulator that is passed to the next  call.  Acc0  is  re‐
202              turned if the list is empty.
203
204              Example:
205
206              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
207              [{a,1},{b,2}]
208              2> orddict:fold(fun (K, V, Acc) -> [{K, V+100} | Acc] end, [], OrdDict1).
209              [{b,102},{a,101}]
210
211       from_list(List) -> Orddict
212
213              Types:
214
215                 List = [{Key, Value}]
216                 Orddict = orddict(Key, Value)
217
218              Converts the Key-Value list List to a dictionary.
219
220       is_empty(Orddict) -> boolean()
221
222              Types:
223
224                 Orddict = orddict()
225
226              Returns true if Orddict has no elements, otherwise false.
227
228       is_key(Key, Orddict) -> boolean()
229
230              Types:
231
232                 Orddict = orddict(Key, Value :: term())
233
234              Tests if Key is contained in dictionary Orddict.
235
236       map(Fun, Orddict1) -> Orddict2
237
238              Types:
239
240                 Fun = fun((Key, Value1) -> Value2)
241                 Orddict1 = orddict(Key, Value1)
242                 Orddict2 = orddict(Key, Value2)
243
244              Calls  Fun on successive keys and values of Orddict1 to return a
245              new value for each key.
246
247              Example:
248
249              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
250              [{a,1},{b,2}]
251              2> orddict:map(fun (_K, V) -> V + 100 end, OrdDict1).
252              [{a,101},{b,102}]
253
254       merge(Fun, Orddict1, Orddict2) -> Orddict3
255
256              Types:
257
258                 Fun = fun((Key, Value1, Value2) -> Value)
259                 Orddict1 = orddict(Key, Value1)
260                 Orddict2 = orddict(Key, Value2)
261                 Orddict3 = orddict(Key, Value)
262
263              Merges two dictionaries, Orddict1 and Orddict2, to create a  new
264              dictionary.  All  the Key-Value pairs from both dictionaries are
265              included in the new dictionary. If a key occurs in both  dictio‐
266              naries,  Fun  is called with the key and both values to return a
267              new value. merge/3 can be defined as follows, but is faster:
268
269              merge(Fun, D1, D2) ->
270                  fold(fun (K, V1, D) ->
271                               update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
272                       end, D2, D1).
273
274              Example:
275
276              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
277              [{a,1},{b,2}]
278              2> OrdDict2 = orddict:from_list([{b, 7}, {c, 8}]).
279              [{b,7},{c,8}]
280              3> orddict:merge(fun (K, V1, V2) -> V1 * V2 end, OrdDict1, OrdDict2).
281              [{a, 1},{b, 14},{c,8}]
282
283       new() -> orddict(none(), none())
284
285              Creates a new dictionary.
286
287       size(Orddict) -> integer() >= 0
288
289              Types:
290
291                 Orddict = orddict()
292
293              Returns the number of elements in an Orddict.
294
295       store(Key, Value, Orddict1) -> Orddict2
296
297              Types:
298
299                 Orddict1 = Orddict2 = orddict(Key, Value)
300
301              Stores a Key-Value pair in a dictionary. If the Key already  ex‐
302              ists in Orddict1, the associated value is replaced by Value.
303
304              Example:
305
306              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
307              [{a,1},{b,2}]
308              2> orddict:store(a, 99, OrdDict1).
309              [{a,99},{b,2}]
310              3> orddict:store(c, 100, OrdDict1).
311              [{a,1},{b,2},{c,100}]
312
313       to_list(Orddict) -> List
314
315              Types:
316
317                 Orddict = orddict(Key, Value)
318                 List = [{Key, Value}]
319
320              Converts a dictionary to a list representation.
321
322       update(Key, Fun, Orddict1) -> Orddict2
323
324              Types:
325
326                 Fun = fun((Value1 :: Value) -> Value2 :: Value)
327                 Orddict1 = Orddict2 = orddict(Key, Value)
328
329              Updates  a  value in a dictionary by calling Fun on the value to
330              get a new value. An exception is generated if Key is not present
331              in the dictionary.
332
333              Example:
334
335              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
336              [{a,1},{b,2}]
337              2> orddict:update(a, fun (V) -> V1 + 100 end, OrdDict1).
338              [{a, 101}, {b, 102}]
339
340       update(Key, Fun, Initial, Orddict1) -> Orddict2
341
342              Types:
343
344                 Initial = Value
345                 Fun = fun((Value1 :: Value) -> Value2 :: Value)
346                 Orddict1 = Orddict2 = orddict(Key, Value)
347
348              Updates  a  value in a dictionary by calling Fun on the value to
349              get a new value. If Key is not present in the  dictionary,  Ini‐
350              tial  is stored as the first value. For example, append/3 can be
351              defined as follows:
352
353              append(Key, Val, D) ->
354                  update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).
355
356              Example 1:
357
358              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
359              [{a,1},{b,2}]
360              2> orddict:update(c, fun (V) -> V1 + 100 end, 99, OrdDict1).
361              [{a,1},{b,2},{c,99}]
362
363              Example 2:
364
365              1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
366              [{a,1},{b,2}]
367              2> orddict:update(a, fun (V) -> V1 + 100 end, 99, OrdDict1).
368              [{a,101},{b,2}]
369
370       update_counter(Key, Increment, Orddict1) -> Orddict2
371
372              Types:
373
374                 Orddict1 = Orddict2 = orddict(Key, Value)
375                 Increment = number()
376
377              Adds Increment to the value associated with Key and  store  this
378              value.  If  Key  is  not present in the dictionary, Increment is
379              stored as the first value.
380
381              This can be defined as follows, but is faster:
382
383              update_counter(Key, Incr, D) ->
384                  update(Key, fun (Old) -> Old + Incr end, Incr, D).
385

NOTES

387       Functions append/3 and append_list/3 are included so that keyed  values
388       can be stored in a list accumulator, for example:
389
390       > D0 = orddict:new(),
391         D1 = orddict:store(files, [], D0),
392         D2 = orddict:append(files, f1, D1),
393         D3 = orddict:append(files, f2, D2),
394         D4 = orddict:append(files, f3, D3),
395         orddict:fetch(files, D4).
396       [f1,f2,f3]
397
398       This saves the trouble of first fetching a keyed value, appending a new
399       value to the list of stored values, and storing the result.
400
401       Function fetch/2 is to be used if the key is known to be in the dictio‐
402       nary, otherwise function find/2.
403

NAME

DESCRIPTION

DATA TYPES

EXPORTS

NOTES

SEE ALSO