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:
21 * maps:next/1
23 * maps:filter/2
25 * maps:filtermap/2
27 * maps:fold/3
29 * maps:foreach/2
31 * maps:map/2
33 iterator() = iterator(term(), term())
35
37 filter(Pred, MapOrIter) -> Map
38 Types:
40 Pred = fun((Key, Value) -> boolean())
42 MapOrIter = #{Key => Value} | iterator(Key, Value)
43 Map = #{Key => Value}
44 Returns a map Map for which predicate Pred holds true in MapOr‐
46 Iter.
47 The call fails with a {badmap,Map} exception if MapOrIter is not
49 a map or valid iterator, or with badarg if Pred is not a func‐
50 tion of arity 2.
51 Example:
53 > M = #{a => 2, b => 3, c=> 4, "a" => 1, "b" => 2, "c" => 4},
55 Pred = fun(K,V) -> is_atom(K) andalso (V rem 2) =:= 0 end,
56 maps:filter(Pred,M).
57 #{a => 2,c => 4}
58 filtermap(Fun, MapOrIter) -> Map
60 Types:
62 Fun = fun((Key, Value1) -> boolean() | {true, Value2})
64 MapOrIter = #{Key => Value1} | iterator(Key, Value1)
65 Map = #{Key => Value1 | Value2}
66 Returns a map Map that is the result of calling Fun(Key, Value1)
68 for every Key to value Value1 association in MapOrIter in any
69 order.
70 If Fun(Key, Value1) returns true, the association is copied to
72 the result map. If it returns false, the association is not
73 copied. If it returns {true, NewValue}, the value for Key is re‐
74 placed with NewValueat this position is replaced in the result
75 map.
76 The call fails with a {badmap,Map} exception if MapOrIter is not
78 a map or valid iterator, or with badarg if Fun is not a function
79 of arity 2.
80 Example:
82 > Fun = fun(K,V) when is_atom(K) -> {true, V*2}; (_,V) -> (V rem 2) =:= 0 end,
84 Map = #{k1 => 1, "k2" => 2, "k3" => 3},
85 maps:filtermap(Fun,Map).
86 #{k1 => 2,"k2" => 2}
87 find(Key, Map) -> {ok, Value} | error
89 Types:
91 Map = #{Key => Value, term() => term()}
93 Returns a tuple {ok, Value}, where Value is the value associated
95 with Key, or error if no value is associated with Key in Map.
96 The call fails with a {badmap,Map} exception if Map is not a
98 map.
99 Example:
101 > Map = #{"hi" => 42},
103 Key = "hi",
104 maps:find(Key,Map).
105 {ok,42}
106 fold(Fun, Init, MapOrIter) -> Acc
108 Types:
110 Fun = fun((Key, Value, AccIn) -> AccOut)
112 Init = term()
113 Acc = AccOut
114 AccIn = Init | AccOut
115 MapOrIter = #{Key => Value} | iterator(Key, Value)
116 Calls F(Key, Value, AccIn) for every Key to value Value associa‐
118 tion in MapOrIter in any order. Function fun F/3 must return a
119 new accumulator, which is passed to the next successive call.
120 This function returns the final value of the accumulator. The
121 initial accumulator value Init is returned if the map is empty.
122 The call fails with a {badmap,Map} exception if MapOrIter is not
124 a map or valid iterator, or with badarg if Fun is not a function
125 of arity 3.
126 Example:
128 > Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end,
130 Map = #{"k1" => 1, "k2" => 2, "k3" => 3},
131 maps:fold(Fun,0,Map).
132 6
133 foreach(Fun, MapOrIter) -> ok
135 Types:
137 Fun = fun((Key, Value) -> term())
139 MapOrIter = #{Key => Value} | iterator(Key, Value)
140 Calls fun F(Key, Value) for every Key to value Value association
142 in MapOrIter in any order.
143 The call fails with a {badmap,Map} exception if MapOrIter is not
145 a map or valid iterator, or with badarg if Fun is not a function
146 of arity 2.
147 from_keys(Keys, Value) -> Map
149 Types:
151 Keys = list()
153 Value = term()
154 Map = map()
155 Takes a list of keys and a value and builds a map where all keys
157 point to the same value. The key can be in any order, and keys
158 and value can be of any term.
159 Example:
161 > Keys = ["a", "b", "c"], maps:from_keys(Keys, ok).
163 #{"a" => ok,"b" => ok,"c" => ok}
164 from_list(List) -> Map
166 Types:
168 List = [{Key, Value}]
170 Key = Value = term()
171 Map = map()
172 Takes a list of key-value tuples elements and builds a map. The
174 associations can be in any order, and both keys and values in
175 the association can be of any term. If the same key appears more
176 than once, the latter (right-most) value is used and the previ‐
177 ous values are ignored.
178 Example:
180 > List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}],
182 maps:from_list(List).
183 #{42 => value_three,1337 => "value two","a" => 1}
184 get(Key, Map) -> Value
186 Types:
188 Key = term()
190 Map = map()
191 Value = term()
192 Returns value Value associated with Key if Map contains Key.
194 The call fails with a {badmap,Map} exception if Map is not a
196 map, or with a {badkey,Key} exception if no value is associated
197 with Key.
198 Example:
200 > Key = 1337,
202 Map = #{42 => value_two,1337 => "value one","a" => 1},
203 maps:get(Key,Map).
204 "value one"
205 get(Key, Map, Default) -> Value | Default
207 Types:
209 Map = #{Key => Value, term() => term()}
211 Returns value Value associated with Key if Map contains Key. If
213 no value is associated with Key, Default is returned.
214 The call fails with a {badmap,Map} exception if Map is not a
216 map.
217 Example:
219 > Map = #{ key1 => val1, key2 => val2 }.
221 #{key1 => val1,key2 => val2}
222 > maps:get(key1, Map, "Default value").
223 val1
224 > maps:get(key3, Map, "Default value").
225 "Default value"
226 groups_from_list(Fun, List) -> MapOut
228 Types:
230 Fun = fun((Elem :: T) -> Selected)
232 MapOut = #{Selected => List}
233 Selected = term()
234 List = [T]
235 T = term()
236 The result is a map where each key is given by Fun and each
238 value is a list of elements. The order of elements within each
239 list is preserved from the list.
240 Examples:
242 > maps:groups_from_list(fun(X) -> X rem 2 end, [1,2,3]).
244 #{0 => [2], 1 => [1, 3]}
245 > maps:groups_from_list(fun erlang:length/1, ["ant", "buffalo", "cat", "dingo"]).
246 #{3 => ["ant", "cat"], 5 => ["dingo"], 7 => ["buffalo"]}
247 groups_from_list(Fun, ValueFun, List) -> MapOut
249 Types:
251 Fun = fun((Elem :: T) -> Key)
253 ValueFun = fun((Elem :: T) -> ValOut)
254 MapOut = #{Key := ListOut}
255 Key = ValOut = term()
256 List = [T]
257 ListOut = [ValOut]
258 T = term()
259 The result is a map where each key is given by Fun and each
261 value is a list of elements given by the ValueFun. The order of
262 elements within each list is preserved from the list.
263 Examples:
265 > maps:groups_from_list(fun(X) -> X rem 2 end, fun(X) -> X*X end, [1,2,3]).
267 #{0 => [4], 1 => [1, 9]}
268 > maps:groups_from_list(fun erlang:length/1, fun lists:reverse/1, ["ant", "buffalo", "cat", "dingo"]).
269 #{3 => ["tna","tac"],5 => ["ognid"],7 => ["olaffub"]}
270 intersect(Map1, Map2) -> Map3
272 Types:
274 Map1 = #{Key => term()}
276 Map2 = #{term() => Value2}
277 Map3 = #{Key => Value2}
278 Intersects two maps into a single map Map3. If a key exists in
280 both maps, the value in Map1 is superseded by the value in Map2.
281 The call fails with a {badmap,Map} exception if Map1 or Map2 is
283 not a map.
284 Example:
286 > Map1 = #{a => "value_one", b => "value_two"},
288 Map2 = #{a => 1, c => 2},
289 maps:intersect(Map1,Map2).
290 #{a => 1}
291 intersect_with(Combiner, Map1, Map2) -> Map3
293 Types:
295 Map1 = #{Key => Value1}
297 Map2 = #{term() => Value2}
298 Combiner = fun((Key, Value1, Value2) -> CombineResult)
299 Map3 = #{Key => CombineResult}
300 Intersects two maps into a single map Map3. If a key exists in
302 both maps, the value in Map1 is combined with the value in Map2
303 by the Combiner fun. When Combiner is applied the key that ex‐
304 ists in both maps is the first parameter, the value from Map1 is
305 the second parameter, and the value from Map2 is the third pa‐
306 rameter.
307 The call fails with a {badmap,Map} exception if Map1 or Map2 is
309 not a map. The call fails with a badarg exception if Combiner is
310 not a fun that takes three arguments.
311 Example:
313 > Map1 = #{a => "value_one", b => "value_two"},
315 Map2 = #{a => 1, c => 2},
316 maps:intersect_with(fun(_Key, Value1, Value2) -> {Value1, Value2} end, Map1, Map2).
317 #{a => {"value_one",1}}
318 is_key(Key, Map) -> boolean()
320 Types:
322 Key = term()
324 Map = map()
325 Returns true if map Map contains Key and returns false if it
327 does not contain the Key.
328 The call fails with a {badmap,Map} exception if Map is not a
330 map.
331 Example:
333 > Map = #{"42" => value}.
335 #{"42" => value}
336 > maps:is_key("42",Map).
337 true
338 > maps:is_key(value,Map).
339 false
340 iterator(Map) -> Iterator
342 Types:
344 Map = #{Key => Value}
346 Iterator = iterator(Key, Value)
347 Returns a map iterator Iterator that can be used by maps:next/1
349 to traverse the key-value associations in a map. When iterating
350 over a map, the memory usage is guaranteed to be bounded no mat‐
351 ter the size of the map.
352 The call fails with a {badmap,Map} exception if Map is not a
354 map.
355 Example:
357 > M = #{ a => 1, b => 2 }.
359 #{a => 1,b => 2}
360 > I = maps:iterator(M), ok.
361 ok
362 > {K1, V1, I2} = maps:next(I), {K1, V1}.
363 {a,1}
364 > {K2, V2, I3} = maps:next(I2),{K2, V2}.
365 {b,2}
366 > maps:next(I3).
367 none
368 keys(Map) -> Keys
370 Types:
372 Map = #{Key => term()}
374 Keys = [Key]
375 Returns a complete list of keys, in any order, which resides
377 within Map.
378 The call fails with a {badmap,Map} exception if Map is not a
380 map.
381 Example:
383 > Map = #{42 => value_three,1337 => "value two","a" => 1},
385 maps:keys(Map).
386 [42,1337,"a"]
387 map(Fun, MapOrIter) -> Map
389 Types:
391 Fun = fun((Key, Value1) -> Value2)
393 MapOrIter = #{Key => Value1} | iterator(Key, Value1)
394 Map = #{Key => Value2}
395 Produces a new map Map by calling function fun F(Key, Value1)
397 for every Key to value Value1 association in MapOrIter in any
398 order. Function fun Fun/2 must return value Value2 to be associ‐
399 ated with key Key for the new map Map.
400 The call fails with a {badmap,Map} exception if MapOrIter is not
402 a map or valid iterator, or with badarg if Fun is not a function
403 of arity 2.
404 Example:
406 > Fun = fun(K,V1) when is_list(K) -> V1*2 end,
408 Map = #{"k1" => 1, "k2" => 2, "k3" => 3},
409 maps:map(Fun,Map).
410 #{"k1" => 2,"k2" => 4,"k3" => 6}
411 merge(Map1, Map2) -> Map3
413 Types:
415 Map1 = Map2 = Map3 = map()
417 Merges two maps into a single map Map3. If two keys exist in
419 both maps, the value in Map1 is superseded by the value in Map2.
420 The call fails with a {badmap,Map} exception if Map1 or Map2 is
422 not a map.
423 Example:
425 > Map1 = #{a => "value_one", b => "value_two"},
427 Map2 = #{a => 1, c => 2},
428 maps:merge(Map1,Map2).
429 #{a => 1,b => "value_two",c => 2}
430 merge_with(Combiner, Map1, Map2) -> Map3
432 Types:
434 Map1 = #{Key1 => Value1}
436 Map2 = #{Key2 => Value2}
437 Combiner = fun((Key1, Value1, Value2) -> CombineResult)
438 Map3 = #{Key1 => CombineResult, Key1 => Value1, Key2 =>
439 Value2}
440 Merges two maps into a single map Map3. If a key exists in both
442 maps, the value in Map1 is combined with the value in Map2 by
443 the Combiner fun. When Combiner is applied the key that exists
444 in both maps is the first parameter, the value from Map1 is the
445 second parameter, and the value from Map2 is the third parame‐
446 ter.
447 The call fails with a {badmap,Map} exception if Map1 or Map2 is
449 not a map. The call fails with a badarg exception if Combiner is
450 not a fun that takes three arguments.
451 Example:
453 > Map1 = #{a => "value_one", b => "value_two"},
455 Map2 = #{a => 1, c => 2},
456 maps:merge_with(fun(_Key, Value1, Value2) -> {Value1, Value2} end, Map1, Map2).
457 #{a => {"value_one",1},b => "value_two",c => 2}
458 new() -> Map
460 Types:
462 Map = #{}
464 Returns a new empty map.
466 Example:
468 > maps:new().
470 #{}
471 next(Iterator) -> {Key, Value, NextIterator} | none
473 Types:
475 Iterator = NextIterator = iterator(Key, Value)
477 Returns the next key-value association in Iterator and a new it‐
479 erator for the remaining associations in the iterator.
480 If there are no more associations in the iterator, none is re‐
482 turned.
483 Example:
485 > Map = #{a => 1, b => 2, c => 3}.
487 #{a => 1,b => 2,c => 3}
488 > I = maps:iterator(Map), ok.
489 ok
490 > {K1, V1, I1} = maps:next(I), {K1, V1}.
491 {a,1}
492 > {K2, V2, I2} = maps:next(I1), {K2, V2}.
493 {b,2}
494 > {K3, V3, I3} = maps:next(I2), {K3, V3}.
495 {c,3}
496 > maps:next(I3).
497 none
498 put(Key, Value, Map1) -> Map2
500 Types:
502 Key = Value = term()
504 Map1 = Map2 = map()
505 Associates Key with value Value and inserts the association into
507 map Map2. If key Key already exists in map Map1, the old associ‐
508 ated value is replaced by value Value. The function returns a
509 new map Map2 containing the new association and the old associa‐
510 tions in Map1.
511 The call fails with a {badmap,Map} exception if Map1 is not a
513 map.
514 Example:
516 > Map = #{"a" => 1}.
518 #{"a" => 1}
519 > maps:put("a", 42, Map).
520 #{"a" => 42}
521 > maps:put("b", 1337, Map).
522 #{"a" => 1,"b" => 1337}
523 remove(Key, Map1) -> Map2
525 Types:
527 Key = term()
529 Map1 = Map2 = map()
530 Removes the Key, if it exists, and its associated value from
532 Map1 and returns a new map Map2 without key Key.
533 The call fails with a {badmap,Map} exception if Map1 is not a
535 map.
536 Example:
538 > Map = #{"a" => 1}.
540 #{"a" => 1}
541 > maps:remove("a",Map).
542 #{}
543 > maps:remove("b",Map).
544 #{"a" => 1}
545 size(Map) -> integer() >= 0
547 Types:
549 Map = map()
551 Returns the number of key-value associations in Map. This opera‐
553 tion occurs in constant time.
554 Example:
556 > Map = #{42 => value_two,1337 => "value one","a" => 1},
558 maps:size(Map).
559 3
560 take(Key, Map1) -> {Value, Map2} | error
562 Types:
564 Map1 = #{Key => Value, term() => term()}
566 Map2 = #{term() => term()}
567 The function removes the Key, if it exists, and its associated
569 value from Map1 and returns a tuple with the removed Value and
570 the new map Map2 without key Key. If the key does not exist er‐
571 ror is returned.
572 The call will fail with a {badmap,Map} exception if Map1 is not
574 a map.
575 Example:
577 > Map = #{"a" => "hello", "b" => "world"}.
579 #{"a" => "hello", "b" => "world"}
580 > maps:take("a",Map).
581 {"hello",#{"b" => "world"}}
582 > maps:take("does not exist",Map).
583 error
584 to_list(Map) -> [{Key, Value}]
586 Types:
588 Map = #{Key => Value}
590 Returns a list of pairs representing the key-value associations
592 of Map, where the pairs [{K1,V1}, ..., {Kn,Vn}] are returned in
593 arbitrary order.
594 The call fails with a {badmap,Map} exception if Map is not a
596 map.
597 Example:
599 > Map = #{42 => value_three,1337 => "value two","a" => 1},
601 maps:to_list(Map).
602 [{42,value_three},{1337,"value two"},{"a",1}]
603 update(Key, Value, Map1) -> Map2
605 Types:
607 Map1 = #{Key := term(), term() => term()}
609 Map2 = #{Key := Value, term() => term()}
610 If Key exists in Map1, the old associated value is replaced by
612 value Value. The function returns a new map Map2 containing the
613 new associated value.
614 The call fails with a {badmap,Map} exception if Map1 is not a
616 map, or with a {badkey,Key} exception if no value is associated
617 with Key.
618 Example:
620 > Map = #{"a" => 1}.
622 #{"a" => 1}
623 > maps:update("a", 42, Map).
624 #{"a" => 42}
625 update_with(Key, Fun, Map1) -> Map2
627 Types:
629 Map1 = #{Key := Value1, term() => term()}
631 Map2 = #{Key := Value2, term() => term()}
632 Fun = fun((Value1) -> Value2)
633 Update a value in a Map1 associated with Key by calling Fun on
635 the old value to get a new value. An exception {badkey,Key} is
636 generated if Key is not present in the map.
637 Example:
639 > Map = #{"counter" => 1},
641 Fun = fun(V) -> V + 1 end,
642 maps:update_with("counter",Fun,Map).
643 #{"counter" => 2}
644 update_with(Key, Fun, Init, Map1) -> Map2
646 Types:
648 Map1 = #{Key => Value1, term() => term()}
650 Map2 = #{Key := Value2 | Init, term() => term()}
651 Fun = fun((Value1) -> Value2)
652 Update a value in a Map1 associated with Key by calling Fun on
654 the old value to get a new value. If Key is not present in Map1
655 then Init will be associated with Key.
656 Example:
658 > Map = #{"counter" => 1},
660 Fun = fun(V) -> V + 1 end,
661 maps:update_with("new counter",Fun,42,Map).
662 #{"counter" => 1,"new counter" => 42}
663 values(Map) -> Values
665 Types:
667 Map = #{term() => Value}
669 Values = [Value]
670 Returns a complete list of values, in arbitrary order, contained
672 in map Map.
673 The call fails with a {badmap,Map} exception if Map is not a
675 map.
676 Example:
678 > Map = #{42 => value_three,1337 => "value two","a" => 1},
680 maps:values(Map).
681 [value_three,"value two",1]
682 with(Ks, Map1) -> Map2
684 Types:
686 Ks = [K]
688 Map1 = #{K => V, term() => term()}
689 Map2 = #{K => V}
690 Returns a new map Map2 with the keys K1 through Kn and their as‐
692 sociated values from map Map1. Any key in Ks that does not exist
693 in Map1 is ignored.
694 Example:
696 > Map = #{42 => value_three,1337 => "value two","a" => 1},
698 Ks = ["a",42,"other key"],
699 maps:with(Ks,Map).
700 #{42 => value_three,"a" => 1}
701 without(Ks, Map1) -> Map2
703 Types:
705 Ks = [K]
707 Map1 = Map2 = map()
708 K = term()
709 Returns a new map Map2 without keys K1 through Kn and their as‐
711 sociated values from map Map1. Any key in Ks that does not exist
712 in Map1 is ignored
713 Example:
715 > Map = #{42 => value_three,1337 => "value two","a" => 1},
717 Ks = ["a",42,"other key"],
718 maps:without(Ks,Map).
719 #{1337 => "value two"}
720Ericsson AB stdlib 4.3.1.3 maps(3)