maps
(stdlib)Maps Processing Functions
This module contains functions for maps processing.
Functions
filter(Pred, Map1) -> Map2
Pred = fun((Key, Value) -> boolean())
Key = Value = term()
Map1 = Map2 = #{}
Returns a map
for which predicate
holds true in
.
The call will fail with a {badmap,Map}
exception if
is not a map or with badarg
if
is not a function of arity 2.
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}
find(Key, Map) -> {ok, Value} | error
Key = term()
Map = #{}
Value = term()
Returns a tuple {ok, Value}
where
is the value associated with
,
or error
if no value is associated with
in
.
The call will fail with a {badmap,Map}
exception if
is not a map.
Example:
> Map = #{"hi" => 42}, Key = "hi", maps:find(Key,Map). {ok,42}
fold(Fun, Init, Map) -> Acc
Fun = fun((K, V, AccIn) -> AccOut)
Init = Acc = AccIn = AccOut = term()
Map = #{}
K = V = term()
Calls F(K, V, AccIn)
for every
to value
association in
in
arbitrary order. The function fun F/3
must return a new accumulator
which is passed to the next successive call. maps:fold/3
returns the final
value of the accumulator. The initial accumulator value
is returned if
the map is empty.
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
from_list(List) -> Map
List = [{Key, Value}]
Key = Value = term()
Map = #{}
The function takes a list of key-value tuples elements and builds a map. The associations may be in any order and both keys and values in the association may be of any term. If the same key appears more than once, the latter (rightmost) 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}
get(Key, Map) -> Value
Key = term()
Map = #{}
Value = term()
Returns the value
associated with
if
contains
.
The call will fail with a {badmap,Map}
exception if
is not a map,
or with a {badkey,Key}
exception if no value is associated with
.
Example:
> Key = 1337, Map = #{42 => value_two,1337 => "value one","a" => 1}, maps:get(Key,Map). "value one"
get(Key, Map, Default) -> Value | Default
Key = term()
Map = #{}
Value = Default = term()
Returns the value
associated with
if
contains
.
If no value is associated with
then returns
.
The call will fail with a {badmap,Map}
exception if
is not a map.
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"
is_key(Key, Map) -> boolean()
Key = term()
Map = #{}
Returns true
if map
contains
and returns
false
if it does not contain the
.
The call will fail with a {badmap,Map}
exception if
is not a map.
Example:
> Map = #{"42" => value}. #{"42"> => value} > maps:is_key("42",Map). true > maps:is_key(value,Map). false
keys(Map) -> Keys
Map = #{}
Keys = [Key]
Key = term()
Returns a complete list of keys, in arbitrary order, which resides within
.
The call will fail with a {badmap,Map}
exception if
is not a map.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, maps:keys(Map). [42,1337,"a"]
map(Fun, Map1) -> Map2
Fun = fun((K, V1) -> V2)
Map1 = Map2 = #{}
K = V1 = V2 = term()
The function produces a new map
by calling the function fun F(K, V1)
for
every
to value
association in
in arbitrary order.
The function fun F/2
must return the value
to be associated with key
for
the new map
.
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}
merge(Map1, Map2) -> Map3
Map1 = Map2 = Map3 = #{}
Merges two maps into a single map
. If two keys exists in both maps the
value in
will be superseded by the value in
.
The call will fail with a {badmap,Map}
exception if
or
is not a map.
Example:
> Map1 = #{a => "value_one", b => "value_two"}, Map2 = #{a => 1, c => 2}, maps:merge(Map1,Map2). #{a => 1,b => "value_two",c => 2}
new() -> Map
Map = #{}
Returns a new empty map.
Example:
> maps:new(). #{}
put(Key, Value, Map1) -> Map2
Key = Value = term()
Map1 = Map2 = #{}
Associates
with value
and inserts the association into map Map2
.
If key
already exists in map
, the old associated value is
replaced by value
. The function returns a new map
containing the new association and
the old associations in
.
The call will fail with a {badmap,Map}
exception if
is not a map.
Example:
> Map = #{"a" => 1}. #{"a" => 1} > maps:put("a", 42, Map). #{"a" => 42} > maps:put("b", 1337, Map). #{"a" => 1,"b" => 1337}
remove(Key, Map1) -> Map2
Key = term()
Map1 = Map2 = #{}
The function removes the
, if it exists, and its associated value from
and returns a new map
without key
.
The call will fail with a {badmap,Map}
exception if
is not a map.
Example:
> Map = #{"a" => 1}. #{"a" => 1} > maps:remove("a",Map). #{} > maps:remove("b",Map). #{"a" => 1}
size(Map) -> integer() >= 0
Map = #{}
The function returns the number of key-value associations in the
.
This operation happens in constant time.
Example:
> Map = #{42 => value_two,1337 => "value one","a" => 1}, maps:size(Map). 3
to_list(Map) -> [{Key, Value}]
Map = #{}
Key = Value = term()
The fuction returns a list of pairs representing the key-value associations of
,
where the pairs, [{K1,V1}, ..., {Kn,Vn}]
, are returned in arbitrary order.
The call will fail with a {badmap,Map}
exception if
is not a map.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, maps:to_list(Map). [{42,value_three},{1337,"value two"},{"a",1}]
update(Key, Value, Map1) -> Map2
Key = Value = term()
Map1 = Map2 = #{}
If
exists in
the old associated value is
replaced by value
. The function returns a new map
containing
the new associated value.
The call will fail with a {badmap,Map}
exception if
is not a map,
or with a {badkey,Key}
exception if no value is associated with
.
Example:
> Map = #{"a" => 1}. #{"a" => 1} > maps:update("a", 42, Map). #{"a" => 42}
values(Map) -> Values
Map = #{}
Values = [Value]
Value = term()
Returns a complete list of values, in arbitrary order, contained in map Map
.
The call will fail with a {badmap,Map}
exception if
is not a map.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, maps:values(Map). [value_three,"value two",1]
with(Ks, Map1) -> Map2
Ks = [K]
Map1 = Map2 = #{}
K = term()
Returns a new map
with the keys K1
through Kn
and their associated values from map
.
Any key in
that does not exist in
are ignored.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, Ks = ["a",42,"other key"], maps:with(Ks,Map). #{42 => value_three,"a" => 1}
without(Ks, Map1) -> Map2
Ks = [K]
Map1 = Map2 = #{}
K = term()
Returns a new map
without the keys K1
through Kn
and their associated values from map
.
Any key in
that does not exist in
are ignored.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, Ks = ["a",42,"other key"], maps:without(Ks,Map). #{1337 => "value two"}