maps - Maps processing functions.
Please see following description for synopsis
maps(3) Erlang Module Definition maps(3)
NAME
maps - Maps processing functions.
DESCRIPTION
This module contains functions for maps processing. The Efficiency
Guide contains a chapter that describes how to use maps efficiently.
DATA TYPES
iterator(Key, Value)
An iterator representing the associations in a map with keys of
type Key and values of type Value.
Created using maps:iterator/1.
Consumed by maps:next/1, maps:filter/2, maps:fold/3 and
maps:map/2.
iterator() = iterator(term(), term())
EXPORTS
filter(Pred, MapOrIter) -> Map
Types:
Pred = fun((Key, Value) -> boolean())
MapOrIter = #{Key => Value} | iterator(Key, Value)
Map = #{Key => Value}
Returns a map Map for which predicate Pred holds true in MapOr-
Iter.
The call fails with a {badmap,Map} exception if MapOrIter is not
a map or valid iterator, or with badarg if Pred is not a func-
tion 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}
filtermap(Fun, MapOrIter) -> Map
Types:
Fun = fun((Key, Value1) -> boolean() | {true, Value2})
MapOrIter = #{Key => Value1} | iterator(Key, Value1)
Map = #{Key => Value1 | Value2}
Returns a map Map that is the result of calling Fun(Key, Value1)
for every Key to value Value1 association in MapOrIter in any
order.
If Fun(Key, Value1) returns true, the association is copied to
the result map. If it returns false, the association is not
copied. If it returns {true, NewValue}, the value for Key is
replaced with NewValueat this position is replaced in the result
map.
The call fails with a {badmap,Map} exception if MapOrIter is not
a map or valid iterator, or with badarg if Fun is not a function
of arity 2.
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}
find(Key, Map) -> {ok, Value} | error
Types:
Map = #{Key => Value, term() => term()}
Returns a tuple {ok, Value}, where Value is the value associated
with Key, or error if no value is associated with Key in Map.
The call fails with a {badmap,Map} exception if Map is not a
map.
Example:
> Map = #{"hi" => 42},
Key = "hi",
maps:find(Key,Map).
{ok,42}
fold(Fun, Init, MapOrIter) -> Acc
Types:
Fun = fun((Key, Value, AccIn) -> AccOut)
Init = term()
Acc = AccOut
AccIn = Init | AccOut
MapOrIter = #{Key => Value} | iterator(Key, Value)
Calls F(Key, Value, AccIn) for every Key to value Value associa-
tion in MapOrIter in any order. Function fun F/3 must return a
new accumulator, which is passed to the next successive call.
This function returns the final value of the accumulator. The
initial accumulator value Init is returned if the map is empty.
The call fails with a {badmap,Map} exception if MapOrIter is not
a map or valid iterator, or with badarg if Fun is not a function
of arity 3.
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
foreach(Fun, MapOrIter) -> ok
Types:
Fun = fun((Key, Value) -> term())
MapOrIter = #{Key => Value} | iterator(Key, Value)
Calls fun F(Key, Value) for every Key to value Value association
in MapOrIter in any order.
The call fails with a {badmap,Map} exception if MapOrIter is not
a map or valid iterator, or with badarg if Fun is not a function
of arity 2.
from_keys(Keys, Value) -> Map
Types:
Keys = list()
Value = term()
Map = map()
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}
from_list(List) -> Map
Types:
List = [{Key, Value}]
Key = Value = term()
Map = map()
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 previ-
ous 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
Types:
Key = term()
Map = map()
Value = term()
Returns value Value associated with Key if Map contains Key.
The call fails with a {badmap,Map} exception if Map is not a
map, or with a {badkey,Key} exception if no value is associated
with Key.
Example:
> Key = 1337,
Map = #{42 => value_two,1337 => "value one","a" => 1},
maps:get(Key,Map).
"value one"
get(Key, Map, Default) -> Value | Default
Types:
Map = #{Key => Value, term() => term()}
Returns value Value associated with Key if Map contains Key. If
no value is associated with Key, Default is returned.
The call fails with a {badmap,Map} exception if Map 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"
intersect(Map1, Map2) -> Map3
Types:
Map1 = #{Key => term()}
Map2 = #{term() => Value2}
Map3 = #{Key => Value2}
Intersects two maps into a single map Map3. If a key exists in
both maps, the value in Map1 is superseded by the value in Map2.
The call fails with a {badmap,Map} exception if Map1 or Map2 is
not a map.
Example:
> Map1 = #{a => "value_one", b => "value_two"},
Map2 = #{a => 1, c => 2},
maps:intersect(Map1,Map2).
#{a => 1}
intersect_with(Combiner, Map1, Map2) -> Map3
Types:
Map1 = #{Key => Value1}
Map2 = #{term() => Value2}
Combiner = fun((Key, Value1, Value2) -> CombineResult)
Map3 = #{Key => CombineResult}
Intersects two maps into a single map Map3. If a key exists in
both maps, the value in Map1 is combined with the value in Map2
by the Combiner fun. When Combiner is applied the key that
exists in both maps is the first parameter, the value from Map1
is the second parameter, and the value from Map2 is the third
parameter.
The call fails with a {badmap,Map} exception if Map1 or Map2 is
not a map. The call fails with a badarg exception if Combiner is
not a fun that takes three arguments.
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}}
is_key(Key, Map) -> boolean()
Types:
Key = term()
Map = map()
Returns true if map Map contains Key and returns false if it
does not contain the Key.
The call fails with a {badmap,Map} exception if Map is not a
map.
Example:
> Map = #{"42" => value}.
#{"42" => value}
> maps:is_key("42",Map).
true
> maps:is_key(value,Map).
false
iterator(Map) -> Iterator
Types:
Map = #{Key => Value}
Iterator = iterator(Key, Value)
Returns a map iterator Iterator that can be used by maps:next/1
to traverse the key-value associations in a map. When iterating
over a map, the memory usage is guaranteed to be bounded no mat-
ter the size of the map.
The call fails with a {badmap,Map} exception if Map is not a
map.
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
keys(Map) -> Keys
Types:
Map = #{Key => term()}
Keys = [Key]
Returns a complete list of keys, in any order, which resides
within Map.
The call fails with a {badmap,Map} exception if Map is not a
map.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1},
maps:keys(Map).
[42,1337,"a"]
map(Fun, MapOrIter) -> Map
Types:
Fun = fun((Key, Value1) -> Value2)
MapOrIter = #{Key => Value1} | iterator(Key, Value1)
Map = #{Key => Value2}
Produces a new map Map by calling function fun F(Key, Value1)
for every Key to value Value1 association in MapOrIter in any
order. Function fun Fun/2 must return value Value2 to be associ-
ated with key Key for the new map Map.
The call fails with a {badmap,Map} exception if MapOrIter is not
a map or valid iterator, or with badarg if Fun is not a function
of arity 2.
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
Types:
Map1 = Map2 = Map3 = map()
Merges two maps into a single map Map3. If two keys exist in
both maps, the value in Map1 is superseded by the value in Map2.
The call fails with a {badmap,Map} exception if Map1 or Map2 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}
merge_with(Combiner, Map1, Map2) -> Map3
Types:
Map1 = #{Key1 => Value1}
Map2 = #{Key2 => Value2}
Combiner = fun((Key1, Value1, Value2) -> CombineResult)
Map3 = #{Key1 => CombineResult, Key1 => Value1, Key2 =>
Value2}
Merges two maps into a single map Map3. If a key exists in both
maps, the value in Map1 is combined with the value in Map2 by
the Combiner fun. When Combiner is applied the key that exists
in both maps is the first parameter, the value from Map1 is the
second parameter, and the value from Map2 is the third parame-
ter.
The call fails with a {badmap,Map} exception if Map1 or Map2 is
not a map. The call fails with a badarg exception if Combiner is
not a fun that takes three arguments.
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}
new() -> Map
Types:
Map = #{}
Returns a new empty map.
Example:
> maps:new().
#{}
next(Iterator) -> {Key, Value, NextIterator} | none
Types:
Iterator = NextIterator = iterator(Key, Value)
Returns the next key-value association in Iterator and a new
iterator for the remaining associations in the iterator.
If there are no more associations in the iterator, none is
returned.
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
put(Key, Value, Map1) -> Map2
Types:
Key = Value = term()
Map1 = Map2 = map()
Associates Key with value Value and inserts the association into
map Map2. If key Key already exists in map Map1, the old associ-
ated value is replaced by value Value. The function returns a
new map Map2 containing the new association and the old associa-
tions in Map1.
The call fails with a {badmap,Map} exception if Map1 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
Types:
Key = term()
Map1 = Map2 = map()
Removes the Key, if it exists, and its associated value from
Map1 and returns a new map Map2 without key Key.
The call fails with a {badmap,Map} exception if Map1 is not a
map.
Example:
> Map = #{"a" => 1}.
#{"a" => 1}
> maps:remove("a",Map).
#{}
> maps:remove("b",Map).
#{"a" => 1}
size(Map) -> integer() >= 0
Types:
Map = map()
Returns the number of key-value associations in Map. This opera-
tion occurs in constant time.
Example:
> Map = #{42 => value_two,1337 => "value one","a" => 1},
maps:size(Map).
3
take(Key, Map1) -> {Value, Map2} | error
Types:
Map1 = #{Key => Value, term() => term()}
Map2 = #{term() => term()}
The function removes the Key, if it exists, and its associated
value from Map1 and returns a tuple with the removed Value and
the new map Map2 without key Key. If the key does not exist
error is returned.
The call will fail with a {badmap,Map} exception if Map1 is not
a map.
Example:
> Map = #{"a" => "hello", "b" => "world"}.
#{"a" => "hello", "b" => "world"}
> maps:take("a",Map).
{"hello",#{"b" => "world"}}
> maps:take("does not exist",Map).
error
to_list(Map) -> [{Key, Value}]
Types:
Map = #{Key => Value}
Returns a list of pairs representing the key-value associations
of Map, where the pairs [{K1,V1}, ..., {Kn,Vn}] are returned in
arbitrary order.
The call fails with a {badmap,Map} exception if Map 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
Types:
Map1 = #{Key := term(), term() => term()}
Map2 = #{Key := Value, term() => term()}
If Key exists in Map1, the old associated value is replaced by
value Value. The function returns a new map Map2 containing the
new associated value.
The call fails with a {badmap,Map} exception if Map1 is not a
map, or with a {badkey,Key} exception if no value is associated
with Key.
Example:
> Map = #{"a" => 1}.
#{"a" => 1}
> maps:update("a", 42, Map).
#{"a" => 42}
update_with(Key, Fun, Map1) -> Map2
Types:
Map1 = #{Key := Value1, term() => term()}
Map2 = #{Key := Value2, term() => term()}
Fun = fun((Value1) -> Value2)
Update a value in a Map1 associated with Key by calling Fun on
the old value to get a new value. An exception {badkey,Key} is
generated if Key is not present in the map.
Example:
> Map = #{"counter" => 1},
Fun = fun(V) -> V + 1 end,
maps:update_with("counter",Fun,Map).
#{"counter" => 2}
update_with(Key, Fun, Init, Map1) -> Map2
Types:
Map1 = #{Key => Value1, term() => term()}
Map2 = #{Key := Value2 | Init, term() => term()}
Fun = fun((Value1) -> Value2)
Update a value in a Map1 associated with Key by calling Fun on
the old value to get a new value. If Key is not present in Map1
then Init will be associated with Key.
Example:
> Map = #{"counter" => 1},
Fun = fun(V) -> V + 1 end,
maps:update_with("new counter",Fun,42,Map).
#{"counter" => 1,"new counter" => 42}
values(Map) -> Values
Types:
Map = #{term() => Value}
Values = [Value]
Returns a complete list of values, in arbitrary order, contained
in map Map.
The call fails with a {badmap,Map} exception if Map 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
Types:
Ks = [K]
Map1 = #{K => V, term() => term()}
Map2 = #{K => V}
Returns a new map Map2 with the keys K1 through Kn and their
associated values from map Map1. Any key in Ks that does not
exist in Map1 is 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
Types:
Ks = [K]
Map1 = Map2 = map()
K = term()
Returns a new map Map2 without keys K1 through Kn and their
associated values from map Map1. Any key in Ks that does not
exist in Map1 is ignored
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1},
Ks = ["a",42,"other key"],
maps:without(Ks,Map).
#{1337 => "value two"}
Ericsson AB stdlib 3.17 maps(3)