This module contains functions for maps processing. The
Efficiency Guide contains a chapter that describes
An iterator representing the associations in a map with keys of type
Created using
Consumed by:
Key-based iterator order option that can be one of
Used by
The
Returns a map
The call fails with a
Example:
> M = #{a => 2, b => 3, c=> 4, "a" => 1, "b" => 2, "c" => 4},
Pred = fun(K,V) -> is_atom(K) andalso (V rem 2) =:= 0 end,
maps:filter(Pred,M).
#{a => 2,c => 4}
Returns a map
If
The call fails with a
Example:
> Fun = fun(K,V) when is_atom(K) -> {true, V*2}; (_,V) -> (V rem 2) =:= 0 end,
Map = #{k1 => 1, "k2" => 2, "k3" => 3},
maps:filtermap(Fun,Map).
#{k1 => 2,"k2" => 2}
Returns a tuple
The call fails with a
Example:
> Map = #{"hi" => 42},
Key = "hi",
maps:find(Key,Map).
{ok,42}
Calls
The call fails with a
Example:
> Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end,
Map = #{"k1" => 1, "k2" => 2, "k3" => 3},
maps:fold(Fun,0,Map).
6
Calls
The call fails with a
Takes a list of keys and a value and builds a map where all keys point to the same value. The key can be in any order, and keys and value can be of any term.
Example:
> Keys = ["a", "b", "c"], maps:from_keys(Keys, ok).
#{"a" => ok,"b" => ok,"c" => ok}
Takes a list of key-value tuples elements and builds a map. The associations can be in any order, and both keys and values in the association can be of any term. If the same key appears more than once, the latter (right-most) value is used and the previous values are ignored.
Example:
> List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}],
maps:from_list(List).
#{42 => value_three,1337 => "value two","a" => 1}
Returns value
The call fails with a
Example:
> Key = 1337,
Map = #{42 => value_two,1337 => "value one","a" => 1},
maps:get(Key,Map).
"value one"
Returns value
The call fails with a
Example:
> Map = #{ key1 => val1, key2 => val2 }.
#{key1 => val1,key2 => val2}
> maps:get(key1, Map, "Default value").
val1
> maps:get(key3, Map, "Default value").
"Default value"
Partitions the given
The result is a map where each key is given by
The order of elements within each group list is preserved from the original list.
Examples:
> EvenOdd = fun(X) -> case X rem 2 of 0 -> even; 1 -> odd end end, maps:groups_from_list(EvenOdd, [1, 2, 3]). #{even => [2], odd => [1, 3]} > maps:groups_from_list(fun erlang:length/1, ["ant", "buffalo", "cat", "dingo"]). #{3 => ["ant", "cat"], 5 => ["dingo"], 7 => ["buffalo"]}
Partitions the given
The result is a map where each key is given by
The order of elements within each group list is preserved from the original list.
Examples:
> EvenOdd = fun(X) -> case X rem 2 of 0 -> even; 1 -> odd end end, > Square = fun(X) -> X * X end, > maps:groups_from_list(EvenOdd, Square, [1, 2, 3]). #{even => [4], odd => [1, 9]} > maps:groups_from_list( fun erlang:length/1, fun lists:reverse/1, ["ant", "buffalo", "cat", "dingo"]). #{3 => ["tna", "tac"],5 => ["ognid"],7 => ["olaffub"]}
Intersects two maps into a single map
The call fails with a
Example:
> Map1 = #{a => "value_one", b => "value_two"},
Map2 = #{a => 1, c => 2},
maps:intersect(Map1,Map2).
#{a => 1}
Intersects two maps into a single map
The call fails with a
Example:
> Map1 = #{a => "value_one", b => "value_two"},
Map2 = #{a => 1, c => 2},
maps:intersect_with(fun(_Key, Value1, Value2) -> {Value1, Value2} end, Map1, Map2).
#{a => {"value_one",1}}
Returns
The call fails with a
Example:
> Map = #{"42" => value}.
#{"42" => value}
> maps:is_key("42",Map).
true
> maps:is_key(value,Map).
false
Returns a map iterator
The call fails with a
Example:
> M = #{ a => 1, b => 2 }.
#{a => 1,b => 2}
> I = maps:iterator(M), ok.
ok
> {K1, V1, I2} = maps:next(I), {K1, V1}.
{a,1}
> {K2, V2, I3} = maps:next(I2),{K2, V2}.
{b,2}
> maps:next(I3).
none
Returns a map iterator
The call fails with a
Example (when
M = #{ a => 1, b => 2 }.
#{a => 1,b => 2}
> OrdI = maps:iterator(M, ordered), ok.
ok
> {K1, V1, OrdI2} = maps:next(OrdI), {K1, V1}.
{a,1}
> {K2, V2, OrdI3} = maps:next(OrdI2),{K2, V2}.
{b,2}
> maps:next(OrdI3).
none
]]>
Example (when
M = #{ a => 1, b => 2 }.
#{a => 1,b => 2}
> RevI = maps:iterator(M, reversed), ok.
ok
> {K2, V2, RevI2} = maps:next(RevI), {K2, V2}.
{b,2}
> {K1, V1, RevI3} = maps:next(RevI2),{K1, V1}.
{a,1}
> maps:next(RevI3).
none
]]>
Example (when
M = #{ -1 => a, -1.0 => b, 0 => c, 0.0 => d }.
#{-1 => a,0 => c,-1.0 => b,0.0 => d}
> ArithOrdI = maps:iterator(M, fun(A, B) -> A =< B end), ok.
ok
> maps:to_list(ArithOrdI).
[{-1,a},{-1.0,b},{0,c},{0.0,d}]
> ArithRevI = maps:iterator(M, fun(A, B) -> B < A end), ok.
ok
> maps:to_list(ArithRevI).
[{0.0,d},{0,c},{-1.0,b},{-1,a}]
]]>
Returns a complete list of keys, in any order, which resides
within
The call fails with a
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1},
maps:keys(Map).
[42,1337,"a"]
Produces a new map
The call fails with a
Example:
> Fun = fun(K,V1) when is_list(K) -> V1*2 end,
Map = #{"k1" => 1, "k2" => 2, "k3" => 3},
maps:map(Fun,Map).
#{"k1" => 2,"k2" => 4,"k3" => 6}
Merges two maps into a single map
The call fails with a
Example:
> Map1 = #{a => "value_one", b => "value_two"},
Map2 = #{a => 1, c => 2},
maps:merge(Map1,Map2).
#{a => 1,b => "value_two",c => 2}
Merges two maps into a single map
The call fails with a
Example:
> Map1 = #{a => "value_one", b => "value_two"},
Map2 = #{a => 1, c => 2},
maps:merge_with(fun(_Key, Value1, Value2) -> {Value1, Value2} end, Map1, Map2).
#{a => {"value_one",1},b => "value_two",c => 2}
Returns a new empty map.
Example:
> maps:new().
#{}
Returns the next key-value association in
If there are no more associations in the iterator,
Example:
> Map = #{a => 1, b => 2, c => 3}.
#{a => 1,b => 2,c => 3}
> I = maps:iterator(Map), ok.
ok
> {K1, V1, I1} = maps:next(I), {K1, V1}.
{a,1}
> {K2, V2, I2} = maps:next(I1), {K2, V2}.
{b,2}
> {K3, V3, I3} = maps:next(I2), {K3, V3}.
{c,3}
> maps:next(I3).
none
Associates
The call fails with a
Example:
> Map = #{"a" => 1}.
#{"a" => 1}
> maps:put("a", 42, Map).
#{"a" => 42}
> maps:put("b", 1337, Map).
#{"a" => 1,"b" => 1337}
Removes the
The call fails with a
Example:
> Map = #{"a" => 1}.
#{"a" => 1}
> maps:remove("a",Map).
#{}
> maps:remove("b",Map).
#{"a" => 1}
Returns the number of key-value associations in
Example:
> Map = #{42 => value_two,1337 => "value one","a" => 1},
maps:size(Map).
3
The function removes the
The call will fail with a
Example:
> Map = #{"a" => "hello", "b" => "world"}.
#{"a" => "hello", "b" => "world"}
> maps:take("a",Map).
{"hello",#{"b" => "world"}}
> maps:take("does not exist",Map).
error
Returns a list of pairs representing the key-value associations of
The call fails with a
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1},
maps:to_list(Map).
[{42,value_three},{1337,"value two"},{"a",1}]
Example (using
Map = #{ z => 1, y => 2, x => 3 }.
#{x => 3,y => 2,z => 1}
> maps:to_list(maps:iterator(Map, ordered)).
[{x,3},{y,2},{z,1}]
]]>
If
The call fails with a
Example:
> Map = #{"a" => 1}.
#{"a" => 1}
> maps:update("a", 42, Map).
#{"a" => 42}
Update a value in a
Example:
> Map = #{"counter" => 1},
Fun = fun(V) -> V + 1 end,
maps:update_with("counter",Fun,Map).
#{"counter" => 2}
Update a value in a
Example:
> Map = #{"counter" => 1},
Fun = fun(V) -> V + 1 end,
maps:update_with("new counter",Fun,42,Map).
#{"counter" => 1,"new counter" => 42}
Returns a complete list of values, in arbitrary order, contained in
map
The call fails with a
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1},
maps:values(Map).
[value_three,"value two",1]
Returns a new map
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1},
Ks = ["a",42,"other key"],
maps:with(Ks,Map).
#{42 => value_three,"a" => 1}
Returns a new map
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1},
Ks = ["a",42,"other key"],
maps:without(Ks,Map).
#{1337 => "value two"}