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. The Efficiency
10       Guide contains a chapter that describes how to use maps efficiently.
11

DATA TYPES

13       iterator(Key, Value)
14
15              An iterator representing the associations in a map with keys  of
16              type Key and values of type Value.
17
18              Created using maps:iterator/1.
19
20              Consumed   by   maps:next/1,   maps:filter/2,   maps:fold/3  and
21              maps:map/2.
22
23       iterator() = iterator(term(), term())
24

EXPORTS

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