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

NAME

6       dict - Key-value dictionary.
7

DESCRIPTION

9       This  module  provides  a Key-Value dictionary. The representation of a
10       dictionary is not defined.
11
12       This module provides the same interface as the orddict(3)  module.  One
13       difference is that while this module considers two keys as different if
14       they do not match (=:=), orddict considers two keys as different if and
15       only if they do not compare equal (==).
16

DATA TYPES

18       dict(Key, Value)
19
20              Dictionary as returned by new/0.
21
22       dict() = dict(term(), term())
23

EXPORTS

25       append(Key, Value, Dict1) -> Dict2
26
27              Types:
28
29                 Dict1 = Dict2 = dict(Key, Value)
30
31              Appends  a  new  Value  to the current list of values associated
32              with Key.
33
34              See also section Notes.
35
36       append_list(Key, ValList, Dict1) -> Dict2
37
38              Types:
39
40                 Dict1 = Dict2 = dict(Key, Value)
41                 ValList = [Value]
42
43              Appends a list of values ValList to the current list  of  values
44              associated  with  Key.  An exception is generated if the initial
45              value associated with Key is not a list of values.
46
47              See also section Notes.
48
49       erase(Key, Dict1) -> Dict2
50
51              Types:
52
53                 Dict1 = Dict2 = dict(Key, Value)
54
55              Erases all items with a given key from a dictionary.
56
57       fetch(Key, Dict) -> Value
58
59              Types:
60
61                 Dict = dict(Key, Value)
62
63              Returns the value associated with Key in dictionary  Dict.  This
64              function  assumes that Key is present in dictionary Dict, and an
65              exception is generated if Key is not in the dictionary.
66
67              See also section Notes.
68
69       fetch_keys(Dict) -> Keys
70
71              Types:
72
73                 Dict = dict(Key, Value :: term())
74                 Keys = [Key]
75
76              Returns a list of all keys in dictionary Dict.
77
78       take(Key, Dict) -> {Value, Dict1} | error
79
80              Types:
81
82                 Dict = Dict1 = dict(Key, Value)
83                 Key = Value = term()
84
85              This function returns value from dictionary and a new dictionary
86              without  this  value. Returns error if the key is not present in
87              the dictionary.
88
89       filter(Pred, Dict1) -> Dict2
90
91              Types:
92
93                 Pred = fun((Key, Value) -> boolean())
94                 Dict1 = Dict2 = dict(Key, Value)
95
96              Dict2 is a dictionary of all keys and values in Dict1 for  which
97              Pred(Key, Value) is true.
98
99       find(Key, Dict) -> {ok, Value} | error
100
101              Types:
102
103                 Dict = dict(Key, Value)
104
105              Searches  for  a  key  in  dictionary Dict. Returns {ok, Value},
106              where Value is the value associated with Key, or  error  if  the
107              key is not present in the dictionary.
108
109              See also section Notes.
110
111       fold(Fun, Acc0, Dict) -> Acc1
112
113              Types:
114
115                 Fun = fun((Key, Value, AccIn) -> AccOut)
116                 Dict = dict(Key, Value)
117                 Acc0 = Acc1 = AccIn = AccOut = Acc
118
119              Calls  Fun  on  successive  keys  and  values of dictionary Dict
120              together with an extra argument Acc (short for accumulator). Fun
121              must  return  a new accumulator that is passed to the next call.
122              Acc0 is returned if the  dictionary  is  empty.  The  evaluation
123              order is undefined.
124
125       from_list(List) -> Dict
126
127              Types:
128
129                 Dict = dict(Key, Value)
130                 List = [{Key, Value}]
131
132              Converts the Key-Value list List to dictionary Dict.
133
134       is_empty(Dict) -> boolean()
135
136              Types:
137
138                 Dict = dict()
139
140              Returns  true  if  dictionary  Dict  has  no elements, otherwise
141              false.
142
143       is_key(Key, Dict) -> boolean()
144
145              Types:
146
147                 Dict = dict(Key, Value :: term())
148
149              Tests if Key is contained in dictionary Dict.
150
151       map(Fun, Dict1) -> Dict2
152
153              Types:
154
155                 Fun = fun((Key, Value1) -> Value2)
156                 Dict1 = dict(Key, Value1)
157                 Dict2 = dict(Key, Value2)
158
159              Calls Fun on successive keys and values of dictionary  Dict1  to
160              return  a  new value for each key. The evaluation order is unde‐
161              fined.
162
163       merge(Fun, Dict1, Dict2) -> Dict3
164
165              Types:
166
167                 Fun = fun((Key, Value1, Value2) -> Value)
168                 Dict1 = dict(Key, Value1)
169                 Dict2 = dict(Key, Value2)
170                 Dict3 = dict(Key, Value)
171
172              Merges two dictionaries, Dict1 and Dict2, to create a  new  dic‐
173              tionary.  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 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() -> dict()
184
185              Creates a new dictionary.
186
187       size(Dict) -> integer() >= 0
188
189              Types:
190
191                 Dict = dict()
192
193              Returns the number of elements in dictionary Dict.
194
195       store(Key, Value, Dict1) -> Dict2
196
197              Types:
198
199                 Dict1 = Dict2 = dict(Key, Value)
200
201              Stores a Key-Value pair in  dictionary  Dict2.  If  Key  already
202              exists in Dict1, the associated value is replaced by Value.
203
204       to_list(Dict) -> List
205
206              Types:
207
208                 Dict = dict(Key, Value)
209                 List = [{Key, Value}]
210
211              Converts dictionary Dict to a list representation.
212
213       update(Key, Fun, Dict1) -> Dict2
214
215              Types:
216
217                 Dict1 = Dict2 = dict(Key, Value)
218                 Fun = fun((Value1 :: Value) -> Value2 :: 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, Dict1) -> Dict2
225
226              Types:
227
228                 Dict1 = Dict2 = dict(Key, Value)
229                 Fun = fun((Value1 :: Value) -> Value2 :: Value)
230                 Initial = 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:
236
237              append(Key, Val, D) ->
238                  update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).
239
240       update_counter(Key, Increment, Dict1) -> Dict2
241
242              Types:
243
244                 Dict1 = Dict2 = dict(Key, Value)
245                 Increment = number()
246
247              Adds Increment to the value associated with Key and stores  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 and append_list are included so that keyed values  can
258       be stored in a list accumulator, for example:
259
260       > D0 = dict:new(),
261         D1 = dict:store(files, [], D0),
262         D2 = dict:append(files, f1, D1),
263         D3 = dict:append(files, f2, D2),
264         D4 = dict:append(files, f3, D3),
265         dict: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 is to be used if the key is known to be in  the  dictio‐
272       nary, otherwise function find.
273

SEE ALSO

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