Scroll to navigation

maps(3erl) Erlang Module Definition maps(3erl)

NAME

maps - Maps Processing Functions

DESCRIPTION

This module contains functions for maps processing.

EXPORTS

find(Key, Map) -> {ok, Value} | error
 
 
Types:
Key = term()
 
Map = #{}
 
Value = 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.
Example:
> Map = #{"hi" => 42}, Key = "hi", maps:find(Key,Map). {ok,42}
fold(Fun, Init, Map) -> Acc
 
 
Types:
Fun = fun((K, V, AccIn) -> AccOut)
 
Init = Acc = AccIn = AccOut = term()
 
Map = #{}
 
K = V = term()
 
Calls F(K, V, AccIn) for every K to value V association in Map 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 Init 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
 
 
Types:
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
 
 
Types:
Key = term()
 
Map = #{}
 
Value = term()
 
Returns the value Value associated with Key if Map contains Key. If no value is associated with Key then the call will fail with an exception.
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:
Key = term()
 
Map = #{}
 
Value = Default = term()
 
Returns the value Value associated with Key if Map contains Key. If no value is associated with Key then returns Default.
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()
 
 
Types:
Key = term()
 
Map = #{}
 
Returns true if map Map contains Key and returns false if it does not contain the Key. The function will fail with an 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
keys(Map) -> Keys
 
 
Types:
Map = #{}
 
Keys = [Key]
 
Key = term()
 
Returns a complete list of keys, in arbitrary order, which resides within Map.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, maps:keys(Map). [42,1337,"a"]
map(Fun, Map1) -> Map2
 
 
Types:
Fun = fun((K, V1) -> V2)
 
Map1 = Map2 = #{}
 
K = V1 = V2 = term()
 
The function produces a new map Map2 by calling the function fun F(K, V1) for every K to value V1 association in Map1 in arbitrary order. The function fun F/2 must return the value V2 to be associated with key K for the new map Map2.
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 = #{}
 
Merges two maps into a single map Map3. If two keys exists in both maps the value in Map1 will be superseded by the value in Map2.
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
 
 
Types:
Map = #{}
 
Returns a new empty map.
Example:
> maps:new(). #{}
put(Key, Value, Map1) -> Map2
 
 
Types:
Key = Value = term()
 
Map1 = Map2 = #{}
 
Associates Key with value Value and inserts the association into map Map2. If key Key already exists in map Map1, the old associated value is replaced by value Value. The function returns a new map Map2 containing the new association and the old associations in Map1.
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 = #{}
 
The function removes the Key, if it exists, and its associated value from Map1 and returns a new map Map2 without key Key.
Example:
> Map = #{"a" => 1}. #{"a" => 1} > maps:remove("a",Map). #{} > maps:remove("b",Map). #{"a" => 1}
size(Map) -> integer() >= 0
 
 
Types:
Map = #{}
 
The function returns the number of key-value associations in the Map. 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}]
 
 
Types:
Map = #{}
 
Key = Value = term()
 
The fuction returns a list of pairs representing the key-value associations of Map, where the pairs, [{K1,V1}, ..., {Kn,Vn}], are returned in arbitrary order.
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:
Key = Value = term()
 
Map1 = Map2 = #{}
 
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. If Key does not exist in Map1 an exception is generated.
Example:
> Map = #{"a" => 1}. #{"a" => 1} > maps:update("a", 42, Map). #{"a" => 42}
values(Map) -> Values
 
 
Types:
Map = #{}
 
Values = [Value]
 
Value = term()
 
Returns a complete list of values, in arbitrary order, contained in map M.
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 = Map2 = #{}
 
K = term()
 
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 are ignored.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, Ks = ["a",42,"other key"], maps:without(Ks,Map). #{42 => value_three,"a" => 1}
without(Ks, Map1) -> Map2
 
 
Types:
Ks = [K]
 
Map1 = Map2 = #{}
 
K = term()
 
Returns a new map Map2 without the keys K1 through Kn and their associated values from map Map1. Any key in Ks that does not exist in Map1 are ignored.
Example:
> Map = #{42 => value_three,1337 => "value two","a" => 1}, Ks = ["a",42,"other key"], maps:without(Ks,Map). #{1337 => "value two"}
stdlib 2.2 Ericsson AB