1orddict(3) Erlang Module Definition orddict(3)
2
3
4
6 orddict - Key-value dictionary as ordered list.
7
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
20 orddict(Key, Value) = [{Key, Value}]
21
22 Dictionary as returned by new/0.
23
24 orddict() = orddict(term(), term())
25
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
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
405 dict(3), gb_trees(3)
406
407
408
409Ericsson AB stdlib 5.1.1 orddict(3)