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

NAME

6       maps - Maps processing functions.
7

DESCRIPTION

9       This module contains functions for maps processing.
10

EXPORTS

12       filter(Pred, Map1) -> Map2
13
14              Types:
15
16                 Pred = fun((Key, Value) -> boolean())
17                 Key = Value = term()
18                 Map1 = Map2 = map()
19
20              Returns a map Map2 for which predicate Pred holds true in Map1.
21
22              The  call  fails  with a {badmap,Map} exception if Map1 is not a
23              map, or with badarg if Pred is not a function of arity 2.
24
25              Example:
26
27              > M = #{a => 2, b => 3, c=> 4, "a" => 1, "b" => 2, "c" => 4},
28                Pred = fun(K,V) -> is_atom(K) andalso (V rem 2) =:= 0 end,
29                maps:filter(Pred,M).
30              #{a => 2,c => 4}
31
32       find(Key, Map) -> {ok, Value} | error
33
34              Types:
35
36                 Key = term()
37                 Map = map()
38                 Value = term()
39
40              Returns a tuple {ok, Value}, where Value is the value associated
41              with Key, or error if no value is associated with Key in Map.
42
43              The  call  fails  with  a {badmap,Map} exception if Map is not a
44              map.
45
46              Example:
47
48              > Map = #{"hi" => 42},
49                Key = "hi",
50                maps:find(Key,Map).
51              {ok,42}
52
53       fold(Fun, Init, Map) -> Acc
54
55              Types:
56
57                 Fun = fun((K, V, AccIn) -> AccOut)
58                 Init = Acc = AccIn = AccOut = term()
59                 Map = map()
60                 K = V = term()
61
62              Calls F(K, V, AccIn) for every K to value V association  in  Map
63              in  any  order.  Function fun F/3 must return a new accumulator,
64              which is passed to  the  next  successive  call.  This  function
65              returns  the final value of the accumulator. The initial accumu‐
66              lator value Init is returned if the map is empty.
67
68              Example:
69
70              > Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end,
71                Map = #{"k1" => 1, "k2" => 2, "k3" => 3},
72                maps:fold(Fun,0,Map).
73              6
74
75       from_list(List) -> Map
76
77              Types:
78
79                 List = [{Key, Value}]
80                 Key = Value = term()
81                 Map = map()
82
83              Takes a list of key-value tuples elements and builds a map.  The
84              associations  can  be  in any order, and both keys and values in
85              the association can be of any term. If the same key appears more
86              than  once, the latter (right-most) value is used and the previ‐
87              ous values are ignored.
88
89              Example:
90
91              > List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}],
92                maps:from_list(List).
93              #{42 => value_three,1337 => "value two","a" => 1}
94
95       get(Key, Map) -> Value
96
97              Types:
98
99                 Key = term()
100                 Map = map()
101                 Value = term()
102
103              Returns value Value associated with Key if Map contains Key.
104
105              The call fails with a {badmap,Map} exception if  Map  is  not  a
106              map,  or with a {badkey,Key} exception if no value is associated
107              with Key.
108
109              Example:
110
111              > Key = 1337,
112                Map = #{42 => value_two,1337 => "value one","a" => 1},
113                maps:get(Key,Map).
114              "value one"
115
116       get(Key, Map, Default) -> Value | Default
117
118              Types:
119
120                 Key = term()
121                 Map = map()
122                 Value = Default = term()
123
124              Returns value Value associated with Key if Map contains Key.  If
125              no value is associated with Key, Default is returned.
126
127              The  call  fails  with  a {badmap,Map} exception if Map is not a
128              map.
129
130              Example:
131
132              > Map = #{ key1 => val1, key2 => val2 }.
133              #{key1 => val1,key2 => val2}
134              > maps:get(key1, Map, "Default value").
135              val1
136              > maps:get(key3, Map, "Default value").
137              "Default value"
138
139       is_key(Key, Map) -> boolean()
140
141              Types:
142
143                 Key = term()
144                 Map = map()
145
146              Returns true if map Map contains Key and  returns  false  if  it
147              does not contain the Key.
148
149              The  call  fails  with  a {badmap,Map} exception if Map is not a
150              map.
151
152              Example:
153
154              > Map = #{"42" => value}.
155              #{"42" => value}
156              > maps:is_key("42",Map).
157              true
158              > maps:is_key(value,Map).
159              false
160
161       keys(Map) -> Keys
162
163              Types:
164
165                 Map = map()
166                 Keys = [Key]
167                 Key = term()
168
169              Returns a complete list of keys, in  any  order,  which  resides
170              within Map.
171
172              The  call  fails  with  a {badmap,Map} exception if Map is not a
173              map.
174
175              Example:
176
177              > Map = #{42 => value_three,1337 => "value two","a" => 1},
178                maps:keys(Map).
179              [42,1337,"a"]
180
181       map(Fun, Map1) -> Map2
182
183              Types:
184
185                 Fun = fun((K, V1) -> V2)
186                 Map1 = Map2 = map()
187                 K = V1 = V2 = term()
188
189              Produces a new map Map2 by calling function  fun  F(K,  V1)  for
190              every  K  to value V1 association in Map1 in any order. Function
191              fun F/2 must return value V2 to be associated with key K for the
192              new map Map2.
193
194              Example:
195
196              > Fun = fun(K,V1) when is_list(K) -> V1*2 end,
197                Map = #{"k1" => 1, "k2" => 2, "k3" => 3},
198                maps:map(Fun,Map).
199              #{"k1" => 2,"k2" => 4,"k3" => 6}
200
201       merge(Map1, Map2) -> Map3
202
203              Types:
204
205                 Map1 = Map2 = Map3 = map()
206
207              Merges  two  maps  into  a single map Map3. If two keys exist in
208              both maps, the value in Map1 is superseded by the value in Map2.
209
210              The call fails with a {badmap,Map} exception if Map1 or Map2  is
211              not a map.
212
213              Example:
214
215              > Map1 = #{a => "value_one", b => "value_two"},
216                Map2 = #{a => 1, c => 2},
217                maps:merge(Map1,Map2).
218              #{a => 1,b => "value_two",c => 2}
219
220       new() -> Map
221
222              Types:
223
224                 Map = map()
225
226              Returns a new empty map.
227
228              Example:
229
230              > maps:new().
231              #{}
232
233       put(Key, Value, Map1) -> Map2
234
235              Types:
236
237                 Key = Value = term()
238                 Map1 = Map2 = map()
239
240              Associates Key with value Value and inserts the association into
241              map Map2. If key Key already exists in map Map1, the old associ‐
242              ated  value  is  replaced by value Value. The function returns a
243              new map Map2 containing the new association and the old associa‐
244              tions in Map1.
245
246              The  call  fails  with a {badmap,Map} exception if Map1 is not a
247              map.
248
249              Example:
250
251              > Map = #{"a" => 1}.
252              #{"a" => 1}
253              > maps:put("a", 42, Map).
254              #{"a" => 42}
255              > maps:put("b", 1337, Map).
256              #{"a" => 1,"b" => 1337}
257
258       remove(Key, Map1) -> Map2
259
260              Types:
261
262                 Key = term()
263                 Map1 = Map2 = map()
264
265              Removes the Key, if it exists, and  its  associated  value  from
266              Map1 and returns a new map Map2 without key Key.
267
268              The  call  fails  with a {badmap,Map} exception if Map1 is not a
269              map.
270
271              Example:
272
273              > Map = #{"a" => 1}.
274              #{"a" => 1}
275              > maps:remove("a",Map).
276              #{}
277              > maps:remove("b",Map).
278              #{"a" => 1}
279
280       size(Map) -> integer() >= 0
281
282              Types:
283
284                 Map = map()
285
286              Returns the number of key-value associations in Map. This opera‐
287              tion occurs in constant time.
288
289              Example:
290
291              > Map = #{42 => value_two,1337 => "value one","a" => 1},
292                maps:size(Map).
293              3
294
295       take(Key, Map1) -> {Value, Map2} | error
296
297              Types:
298
299                 Key = term()
300                 Map1 = map()
301                 Value = term()
302                 Map2 = map()
303
304              The  function  removes the Key, if it exists, and its associated
305              value from Map1 and returns a tuple with the removed  Value  and
306              the  new  map  Map2  without  key Key. If the key does not exist
307              error is returned.
308
309              The call will fail with a {badmap,Map} exception if Map1 is  not
310              a map.
311
312              Example:
313
314              > Map = #{"a" => "hello", "b" => "world"}.
315              #{"a" => "hello", "b" => "world"}
316              > maps:take("a",Map).
317              {"hello",#{"b" => "world"}}
318              > maps:take("does not exist",Map).
319              error
320
321       to_list(Map) -> [{Key, Value}]
322
323              Types:
324
325                 Map = map()
326                 Key = Value = term()
327
328              Returns  a list of pairs representing the key-value associations
329              of Map, where the pairs [{K1,V1}, ..., {Kn,Vn}] are returned  in
330              arbitrary order.
331
332              The  call  fails  with  a {badmap,Map} exception if Map is not a
333              map.
334
335              Example:
336
337              > Map = #{42 => value_three,1337 => "value two","a" => 1},
338                maps:to_list(Map).
339              [{42,value_three},{1337,"value two"},{"a",1}]
340
341       update(Key, Value, Map1) -> Map2
342
343              Types:
344
345                 Key = Value = term()
346                 Map1 = Map2 = map()
347
348              If Key exists in Map1, the old associated value is  replaced  by
349              value  Value. The function returns a new map Map2 containing the
350              new associated value.
351
352              The call fails with a {badmap,Map} exception if Map1  is  not  a
353              map,  or with a {badkey,Key} exception if no value is associated
354              with Key.
355
356              Example:
357
358              > Map = #{"a" => 1}.
359              #{"a" => 1}
360              > maps:update("a", 42, Map).
361              #{"a" => 42}
362
363       update_with(Key, Fun, Map1) -> Map2
364
365              Types:
366
367                 Key = term()
368                 Map1 = Map2 = map()
369                 Fun = fun((Value1 :: term()) -> Value2 :: term())
370
371              Update a value in a Map1 associated with Key by calling  Fun  on
372              the  old  value to get a new value. An exception {badkey,Key} is
373              generated if Key is not present in the map.
374
375              Example:
376
377              > Map = #{"counter" => 1},
378                Fun = fun(V) -> V + 1 end,
379                maps:update_with("counter",Fun,Map).
380              #{"counter" => 2}
381
382       update_with(Key, Fun, Init, Map1) -> Map2
383
384              Types:
385
386                 Key = term()
387                 Map1 = Map1
388                 Map2 = Map2
389                 Fun = fun((Value1 :: term()) -> Value2 :: term())
390                 Init = term()
391
392              Update a value in a Map1 associated with Key by calling  Fun  on
393              the  old value to get a new value. If Key is not present in Map1
394              then Init will be associated with Key.
395
396              Example:
397
398              > Map = #{"counter" => 1},
399                Fun = fun(V) -> V + 1 end,
400                maps:update_with("new counter",Fun,42,Map).
401              #{"counter" => 1,"new counter" => 42}
402
403       values(Map) -> Values
404
405              Types:
406
407                 Map = map()
408                 Values = [Value]
409                 Value = term()
410
411              Returns a complete list of values, in arbitrary order, contained
412              in map Map.
413
414              The  call  fails  with  a {badmap,Map} exception if Map is not a
415              map.
416
417              Example:
418
419              > Map = #{42 => value_three,1337 => "value two","a" => 1},
420                maps:values(Map).
421              [value_three,"value two",1]
422
423       with(Ks, Map1) -> Map2
424
425              Types:
426
427                 Ks = [K]
428                 Map1 = Map2 = map()
429                 K = term()
430
431              Returns a new map Map2 with the keys K1  through  Kn  and  their
432              associated  values  from  map  Map1. Any key in Ks that does not
433              exist in Map1 is ignored.
434
435              Example:
436
437              > Map = #{42 => value_three,1337 => "value two","a" => 1},
438                Ks = ["a",42,"other key"],
439                maps:with(Ks,Map).
440              #{42 => value_three,"a" => 1}
441
442       without(Ks, Map1) -> Map2
443
444              Types:
445
446                 Ks = [K]
447                 Map1 = Map2 = map()
448                 K = term()
449
450              Returns a new map Map2 without keys  K1  through  Kn  and  their
451              associated  values  from  map  Map1. Any key in Ks that does not
452              exist in Map1 is ignored
453
454              Example:
455
456              > Map = #{42 => value_three,1337 => "value two","a" => 1},
457                Ks = ["a",42,"other key"],
458                maps:without(Ks,Map).
459              #{1337 => "value two"}
460
461
462
463Ericsson AB                     stdlib 3.4.5.1                         maps(3)