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

EXPORTS

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