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

DATA TYPES

12       iterator()
13
14              An iterator representing the key value associations in a map.
15
16              Created using maps:iterator/1.
17
18              Consumed   by   maps:next/1,   maps:filter/2,   maps:fold/3  and
19              maps:map/2.
20

EXPORTS

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