1maps(3) Erlang Module Definition maps(3)
2
6 maps - Maps processing functions.
7
9 This module contains functions for maps processing. The Efficiency
10 Guide contains a chapter that describes how to use maps efficiently.
11
13 iterator(Key, Value)
14 An iterator representing the associations in a map with keys of
16 type Key and values of type Value.
17 Created using maps:iterator/1.
19 Consumed by maps:next/1, maps:filter/2, maps:fold/3 and
21 maps:map/2.
22 iterator() = iterator(term(), term())
24
26 filter(Pred, MapOrIter) -> Map
27 Types:
29 Pred = fun((Key, Value) -> boolean())
31 MapOrIter = #{Key => Value} | iterator(Key, Value)
32 Map = #{Key => Value}
33 Returns a map Map for which predicate Pred holds true in MapOr‐
35 Iter.
36 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 Example:
42 > 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 filtermap(Fun, MapOrIter) -> Map
49 Types:
51 Fun = fun((Key, Value1) -> boolean() | {true, Value2})
53 MapOrIter = #{Key => Value1} | iterator(Key, Value1)
54 Map = #{Key => Value1 | Value2}
55 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 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 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 Example:
71 > 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 find(Key, Map) -> {ok, Value} | error
78 Types:
80 Map = #{Key => Value, term() => term()}
82 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 The call fails with a {badmap,Map} exception if Map is not a
87 map.
88 Example:
90 > Map = #{"hi" => 42},
92 Key = "hi",
93 maps:find(Key,Map).
94 {ok,42}
95 fold(Fun, Init, MapOrIter) -> Acc
97 Types:
99 Fun = fun((Key, Value, AccIn) -> AccOut)
101 Init = term()
102 Acc = AccOut
103 AccIn = Init | AccOut
104 MapOrIter = #{Key => Value} | iterator(Key, Value)
105 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 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 Example:
117 > 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 foreach(Fun, MapOrIter) -> ok
124 Types:
126 Fun = fun((Key, Value) -> term())
128 MapOrIter = #{Key => Value} | iterator(Key, Value)
129 Calls fun F(Key, Value) for every Key to value Value association
131 in MapOrIter in any order.
132 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 from_keys(Keys, Value) -> Map
138 Types:
140 Keys = list()
142 Value = term()
143 Map = map()
144 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 Example:
150 > Keys = ["a", "b", "c"], maps:from_keys(Keys, ok).
152 #{"a" => ok,"b" => ok,"c" => ok}
153 from_list(List) -> Map
155 Types:
157 List = [{Key, Value}]
159 Key = Value = term()
160 Map = map()
161 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 Example:
169 > 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 get(Key, Map) -> Value
175 Types:
177 Key = term()
179 Map = map()
180 Value = term()
181 Returns value Value associated with Key if Map contains Key.
183 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 Example:
189 > Key = 1337,
191 Map = #{42 => value_two,1337 => "value one","a" => 1},
192 maps:get(Key,Map).
193 "value one"
194 get(Key, Map, Default) -> Value | Default
196 Types:
198 Map = #{Key => Value, term() => term()}
200 Returns value Value associated with Key if Map contains Key. If
202 no value is associated with Key, Default is returned.
203 The call fails with a {badmap,Map} exception if Map is not a
205 map.
206 Example:
208 > 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 groups_from_list(Fun, List) -> MapOut
217 Types:
219 Fun = fun((Elem :: T) -> Selected)
221 MapOut = #{Selected => List}
222 Selected = term()
223 List = [T]
224 T = term()
225 The result is a map where each key is given by Fun and each
227 value is a list of elements. The order of elements within each
228 list is preserved from the list.
229 Examples:
231 > maps:groups_from_list(fun(X) -> X rem 2 end, [1,2,3]).
233 #{0 => [2], 1 => [1, 3]}
234 > maps:groups_from_list(fun erlang:length/1, ["ant", "buffalo", "cat", "dingo"]).
235 #{3 => ["ant", "cat"], 5 => ["dingo"], 7 => ["buffalo"]}
236 groups_from_list(Fun, ValueFun, List) -> MapOut
238 Types:
240 Fun = fun((Elem :: T) -> Key)
242 ValueFun = fun((Elem :: T) -> ValOut)
243 MapOut = #{Key := ListOut}
244 Key = ValOut = term()
245 List = [T]
246 ListOut = [ValOut]
247 T = term()
248 The result is a map where each key is given by Fun and each
250 value is a list of elements given by the ValueFun. The order of
251 elements within each list is preserved from the list.
252 Examples:
254 > maps:groups_from_list(fun(X) -> X rem 2 end, fun(X) -> X*X end, [1,2,3]).
256 #{0 => [4], 1 => [1, 9]}
257 > maps:groups_from_list(fun erlang:length/1, fun lists:reverse/1, ["ant", "buffalo", "cat", "dingo"]).
258 #{3 => ["tna","tac"],5 => ["ognid"],7 => ["olaffub"]}
259 intersect(Map1, Map2) -> Map3
261 Types:
263 Map1 = #{Key => term()}
265 Map2 = #{term() => Value2}
266 Map3 = #{Key => Value2}
267 Intersects two maps into a single map Map3. If a key exists in
269 both maps, the value in Map1 is superseded by the value in Map2.
270 The call fails with a {badmap,Map} exception if Map1 or Map2 is
272 not a map.
273 Example:
275 > Map1 = #{a => "value_one", b => "value_two"},
277 Map2 = #{a => 1, c => 2},
278 maps:intersect(Map1,Map2).
279 #{a => 1}
280 intersect_with(Combiner, Map1, Map2) -> Map3
282 Types:
284 Map1 = #{Key => Value1}
286 Map2 = #{term() => Value2}
287 Combiner = fun((Key, Value1, Value2) -> CombineResult)
288 Map3 = #{Key => CombineResult}
289 Intersects two maps into a single map Map3. If a key exists in
291 both maps, the value in Map1 is combined with the value in Map2
292 by the Combiner fun. When Combiner is applied the key that ex‐
293 ists in both maps is the first parameter, the value from Map1 is
294 the second parameter, and the value from Map2 is the third pa‐
295 rameter.
296 The call fails with a {badmap,Map} exception if Map1 or Map2 is
298 not a map. The call fails with a badarg exception if Combiner is
299 not a fun that takes three arguments.
300 Example:
302 > Map1 = #{a => "value_one", b => "value_two"},
304 Map2 = #{a => 1, c => 2},
305 maps:intersect_with(fun(_Key, Value1, Value2) -> {Value1, Value2} end, Map1, Map2).
306 #{a => {"value_one",1}}
307 is_key(Key, Map) -> boolean()
309 Types:
311 Key = term()
313 Map = map()
314 Returns true if map Map contains Key and returns false if it
316 does not contain the Key.
317 The call fails with a {badmap,Map} exception if Map is not a
319 map.
320 Example:
322 > Map = #{"42" => value}.
324 #{"42" => value}
325 > maps:is_key("42",Map).
326 true
327 > maps:is_key(value,Map).
328 false
329 iterator(Map) -> Iterator
331 Types:
333 Map = #{Key => Value}
335 Iterator = iterator(Key, Value)
336 Returns a map iterator Iterator that can be used by maps:next/1
338 to traverse the key-value associations in a map. When iterating
339 over a map, the memory usage is guaranteed to be bounded no mat‐
340 ter the size of the map.
341 The call fails with a {badmap,Map} exception if Map is not a
343 map.
344 Example:
346 > M = #{ a => 1, b => 2 }.
348 #{a => 1,b => 2}
349 > I = maps:iterator(M), ok.
350 ok
351 > {K1, V1, I2} = maps:next(I), {K1, V1}.
352 {a,1}
353 > {K2, V2, I3} = maps:next(I2),{K2, V2}.
354 {b,2}
355 > maps:next(I3).
356 none
357 keys(Map) -> Keys
359 Types:
361 Map = #{Key => term()}
363 Keys = [Key]
364 Returns a complete list of keys, in any order, which resides
366 within Map.
367 The call fails with a {badmap,Map} exception if Map is not a
369 map.
370 Example:
372 > Map = #{42 => value_three,1337 => "value two","a" => 1},
374 maps:keys(Map).
375 [42,1337,"a"]
376 map(Fun, MapOrIter) -> Map
378 Types:
380 Fun = fun((Key, Value1) -> Value2)
382 MapOrIter = #{Key => Value1} | iterator(Key, Value1)
383 Map = #{Key => Value2}
384 Produces a new map Map by calling function fun F(Key, Value1)
386 for every Key to value Value1 association in MapOrIter in any
387 order. Function fun Fun/2 must return value Value2 to be associ‐
388 ated with key Key for the new map Map.
389 The call fails with a {badmap,Map} exception if MapOrIter is not
391 a map or valid iterator, or with badarg if Fun is not a function
392 of arity 2.
393 Example:
395 > Fun = fun(K,V1) when is_list(K) -> V1*2 end,
397 Map = #{"k1" => 1, "k2" => 2, "k3" => 3},
398 maps:map(Fun,Map).
399 #{"k1" => 2,"k2" => 4,"k3" => 6}
400 merge(Map1, Map2) -> Map3
402 Types:
404 Map1 = Map2 = Map3 = map()
406 Merges two maps into a single map Map3. If two keys exist in
408 both maps, the value in Map1 is superseded by the value in Map2.
409 The call fails with a {badmap,Map} exception if Map1 or Map2 is
411 not a map.
412 Example:
414 > Map1 = #{a => "value_one", b => "value_two"},
416 Map2 = #{a => 1, c => 2},
417 maps:merge(Map1,Map2).
418 #{a => 1,b => "value_two",c => 2}
419 merge_with(Combiner, Map1, Map2) -> Map3
421 Types:
423 Map1 = #{Key1 => Value1}
425 Map2 = #{Key2 => Value2}
426 Combiner = fun((Key1, Value1, Value2) -> CombineResult)
427 Map3 = #{Key1 => CombineResult, Key1 => Value1, Key2 =>
428 Value2}
429 Merges two maps into a single map Map3. If a key exists in both
431 maps, the value in Map1 is combined with the value in Map2 by
432 the Combiner fun. When Combiner is applied the key that exists
433 in both maps is the first parameter, the value from Map1 is the
434 second parameter, and the value from Map2 is the third parame‐
435 ter.
436 The call fails with a {badmap,Map} exception if Map1 or Map2 is
438 not a map. The call fails with a badarg exception if Combiner is
439 not a fun that takes three arguments.
440 Example:
442 > Map1 = #{a => "value_one", b => "value_two"},
444 Map2 = #{a => 1, c => 2},
445 maps:merge_with(fun(_Key, Value1, Value2) -> {Value1, Value2} end, Map1, Map2).
446 #{a => {"value_one",1},b => "value_two",c => 2}
447 new() -> Map
449 Types:
451 Map = #{}
453 Returns a new empty map.
455 Example:
457 > maps:new().
459 #{}
460 next(Iterator) -> {Key, Value, NextIterator} | none
462 Types:
464 Iterator = NextIterator = iterator(Key, Value)
466 Returns the next key-value association in Iterator and a new it‐
468 erator for the remaining associations in the iterator.
469 If there are no more associations in the iterator, none is re‐
471 turned.
472 Example:
474 > Map = #{a => 1, b => 2, c => 3}.
476 #{a => 1,b => 2,c => 3}
477 > I = maps:iterator(Map), ok.
478 ok
479 > {K1, V1, I1} = maps:next(I), {K1, V1}.
480 {a,1}
481 > {K2, V2, I2} = maps:next(I1), {K2, V2}.
482 {b,2}
483 > {K3, V3, I3} = maps:next(I2), {K3, V3}.
484 {c,3}
485 > maps:next(I3).
486 none
487 put(Key, Value, Map1) -> Map2
489 Types:
491 Key = Value = term()
493 Map1 = Map2 = map()
494 Associates Key with value Value and inserts the association into
496 map Map2. If key Key already exists in map Map1, the old associ‐
497 ated value is replaced by value Value. The function returns a
498 new map Map2 containing the new association and the old associa‐
499 tions in Map1.
500 The call fails with a {badmap,Map} exception if Map1 is not a
502 map.
503 Example:
505 > Map = #{"a" => 1}.
507 #{"a" => 1}
508 > maps:put("a", 42, Map).
509 #{"a" => 42}
510 > maps:put("b", 1337, Map).
511 #{"a" => 1,"b" => 1337}
512 remove(Key, Map1) -> Map2
514 Types:
516 Key = term()
518 Map1 = Map2 = map()
519 Removes the Key, if it exists, and its associated value from
521 Map1 and returns a new map Map2 without key Key.
522 The call fails with a {badmap,Map} exception if Map1 is not a
524 map.
525 Example:
527 > Map = #{"a" => 1}.
529 #{"a" => 1}
530 > maps:remove("a",Map).
531 #{}
532 > maps:remove("b",Map).
533 #{"a" => 1}
534 size(Map) -> integer() >= 0
536 Types:
538 Map = map()
540 Returns the number of key-value associations in Map. This opera‐
542 tion occurs in constant time.
543 Example:
545 > Map = #{42 => value_two,1337 => "value one","a" => 1},
547 maps:size(Map).
548 3
549 take(Key, Map1) -> {Value, Map2} | error
551 Types:
553 Map1 = #{Key => Value, term() => term()}
555 Map2 = #{term() => term()}
556 The function removes the Key, if it exists, and its associated
558 value from Map1 and returns a tuple with the removed Value and
559 the new map Map2 without key Key. If the key does not exist er‐
560 ror is returned.
561 The call will fail with a {badmap,Map} exception if Map1 is not
563 a map.
564 Example:
566 > Map = #{"a" => "hello", "b" => "world"}.
568 #{"a" => "hello", "b" => "world"}
569 > maps:take("a",Map).
570 {"hello",#{"b" => "world"}}
571 > maps:take("does not exist",Map).
572 error
573 to_list(Map) -> [{Key, Value}]
575 Types:
577 Map = #{Key => Value}
579 Returns a list of pairs representing the key-value associations
581 of Map, where the pairs [{K1,V1}, ..., {Kn,Vn}] are returned in
582 arbitrary order.
583 The call fails with a {badmap,Map} exception if Map is not a
585 map.
586 Example:
588 > Map = #{42 => value_three,1337 => "value two","a" => 1},
590 maps:to_list(Map).
591 [{42,value_three},{1337,"value two"},{"a",1}]
592 update(Key, Value, Map1) -> Map2
594 Types:
596 Map1 = #{Key := term(), term() => term()}
598 Map2 = #{Key := Value, term() => term()}
599 If Key exists in Map1, the old associated value is replaced by
601 value Value. The function returns a new map Map2 containing the
602 new associated value.
603 The call fails with a {badmap,Map} exception if Map1 is not a
605 map, or with a {badkey,Key} exception if no value is associated
606 with Key.
607 Example:
609 > Map = #{"a" => 1}.
611 #{"a" => 1}
612 > maps:update("a", 42, Map).
613 #{"a" => 42}
614 update_with(Key, Fun, Map1) -> Map2
616 Types:
618 Map1 = #{Key := Value1, term() => term()}
620 Map2 = #{Key := Value2, term() => term()}
621 Fun = fun((Value1) -> Value2)
622 Update a value in a Map1 associated with Key by calling Fun on
624 the old value to get a new value. An exception {badkey,Key} is
625 generated if Key is not present in the map.
626 Example:
628 > Map = #{"counter" => 1},
630 Fun = fun(V) -> V + 1 end,
631 maps:update_with("counter",Fun,Map).
632 #{"counter" => 2}
633 update_with(Key, Fun, Init, Map1) -> Map2
635 Types:
637 Map1 = #{Key => Value1, term() => term()}
639 Map2 = #{Key := Value2 | Init, term() => term()}
640 Fun = fun((Value1) -> Value2)
641 Update a value in a Map1 associated with Key by calling Fun on
643 the old value to get a new value. If Key is not present in Map1
644 then Init will be associated with Key.
645 Example:
647 > Map = #{"counter" => 1},
649 Fun = fun(V) -> V + 1 end,
650 maps:update_with("new counter",Fun,42,Map).
651 #{"counter" => 1,"new counter" => 42}
652 values(Map) -> Values
654 Types:
656 Map = #{term() => Value}
658 Values = [Value]
659 Returns a complete list of values, in arbitrary order, contained
661 in map Map.
662 The call fails with a {badmap,Map} exception if Map is not a
664 map.
665 Example:
667 > Map = #{42 => value_three,1337 => "value two","a" => 1},
669 maps:values(Map).
670 [value_three,"value two",1]
671 with(Ks, Map1) -> Map2
673 Types:
675 Ks = [K]
677 Map1 = #{K => V, term() => term()}
678 Map2 = #{K => V}
679 Returns a new map Map2 with the keys K1 through Kn and their as‐
681 sociated values from map Map1. Any key in Ks that does not exist
682 in Map1 is ignored.
683 Example:
685 > Map = #{42 => value_three,1337 => "value two","a" => 1},
687 Ks = ["a",42,"other key"],
688 maps:with(Ks,Map).
689 #{42 => value_three,"a" => 1}
690 without(Ks, Map1) -> Map2
692 Types:
694 Ks = [K]
696 Map1 = Map2 = map()
697 K = term()
698 Returns a new map Map2 without keys K1 through Kn and their as‐
700 sociated values from map Map1. Any key in Ks that does not exist
701 in Map1 is ignored
702 Example:
704 > Map = #{42 => value_three,1337 => "value two","a" => 1},
706 Ks = ["a",42,"other key"],
707 maps:without(Ks,Map).
708 #{1337 => "value two"}
709Ericsson AB stdlib 4.2 maps(3)