View Source maps (stdlib v6.0.1)

Maps processing functions.

This module contains functions for maps processing. The Efficiency Guide contains a chapter that describes how to use maps efficiently.

Summary

Types

An iterator representing the associations in a map with keys of type Key and values of type Value.

Key-based iterator order option that can be one of undefined (default for maps:iterator/1), ordered (sorted in map-key order), reversed, or a custom sorting function.

Functions

Returns a map Map for which predicate Pred holds true in MapOrIter.

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.

Returns a tuple {ok, Value}, where Value is the value associated with Key, or error if no value is associated with Key in Map.

Calls F(Key, Value, AccIn) for every Key to value Value association 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.

Calls fun F(Key, Value) for every Key to value Value association in MapOrIter in any order.

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.

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.

Returns value Value associated with Key if Map contains Key.

Returns value Value associated with Key if Map contains Key. If no value is associated with Key, Default is returned.

Partitions the given List into a map of groups.

Partitions the given List into a map of groups.

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.

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.

Returns true if map Map contains Key and returns false if it does not contain the Key.

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 matter the size of the map.

Returns a map iterator Iterator that can be used by maps:next/1 to traverse the key-value associations in a map sorted by key using the given Order.

Returns a complete list of keys, in any order, which resides within Map.

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 associated with key Key for the new map 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.

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.

Returns a new empty map.

Returns the next key-value association in Iterator and a new iterator for the remaining associations in the iterator.

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.

Removes the Key, if it exists, and its associated value from Map1 and returns a new map Map2 without key Key.

Returns the number of key-value associations in Map. This operation occurs in constant time.

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.

Returns a list of pairs representing the key-value associations of MapOrIterator, where the pairs [{K1,V1}, ..., {Kn,Vn}] are returned in arbitrary order.

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.

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.

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.

Returns a complete list of values, in arbitrary order, contained in map Map.

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.

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

Types

Link to this type

iterator()

View Source (since OTP 17.0)
-type iterator() :: iterator(term(), term()).
Link to this opaque

iterator(Map, Order)

View Source (since OTP 17.0)
-opaque 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 or maps:iterator/2.

Consumed by:

Link to this type

iterator_order()

View Source (since OTP 17.0)
-type iterator_order() :: iterator_order(term()).
Link to this type

iterator_order(Key)

View Source (since OTP 17.0)
-type iterator_order(Key) :: undefined | ordered | reversed | fun((A :: Key, B :: Key) -> boolean()).

Key-based iterator order option that can be one of undefined (default for maps:iterator/1), ordered (sorted in map-key order), reversed, or a custom sorting function.

Used by maps:iterator/2.

The Expressions section contains descriptions of how terms are ordered.

Functions

Link to this function

filter(Pred, MapOrIter)

View Source (since OTP 18.0)
-spec filter(Pred, MapOrIter) -> Map
                when
                    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 MapOrIter.

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 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}
Link to this function

filtermap(Fun, MapOrIter)

View Source (since OTP 24.0)
-spec filtermap(Fun, MapOrIter) -> Map
                   when
                       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 NewValue 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}
Link to this function

find(Key, Map)

View Source (since OTP 17.0)
-spec find(Key, Map) -> {ok, Value} | error when Map :: #{Key => Value, _ => _}.

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}
Link to this function

fold(Fun, Init, MapOrIter)

View Source (since OTP 17.0)
-spec fold(Fun, Init, MapOrIter) -> Acc
              when
                  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 association 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
Link to this function

foreach(Fun, MapOrIter)

View Source (since OTP 24.0)
-spec foreach(Fun, MapOrIter) -> ok
                 when
                     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.

Link to this function

from_keys(Keys, Value)

View Source (since OTP 24.0)
-spec from_keys(Keys, Value) -> Map when 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}
Link to this function

from_list(List)

View Source (since OTP 17.0)
-spec from_list(List) -> Map when List :: [{Key, Value}], Key :: term(), 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 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}
Link to this function

get(Key, Map)

View Source (since OTP 17.0)
-spec get(Key, Map) -> Value when 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"
Link to this function

get(Key, Map, Default)

View Source (since OTP 17.1)
-spec get(Key, Map, Default) -> Value | Default when Map :: #{Key => Value, _ => _}.

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"
Link to this function

groups_from_list(KeyFun, List)

View Source (since OTP 25.0)
-spec groups_from_list(KeyFun, List) -> GroupsMap
                          when
                              KeyFun :: fun((Elem) -> Key),
                              GroupsMap :: #{Key => Group},
                              Key :: term(),
                              List :: [Elem],
                              Group :: [Elem],
                              Elem :: term().

Partitions the given List into a map of groups.

The result is a map where each key is given by KeyFun and each value is a list of elements from the given List for which KeyFun returned the same key.

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"]}
Link to this function

groups_from_list(KeyFun, ValueFun, List)

View Source (since OTP 25.0)
-spec groups_from_list(KeyFun, ValueFun, List) -> GroupsMap
                          when
                              KeyFun :: fun((Elem) -> Key),
                              ValueFun :: fun((Elem) -> Value),
                              GroupsMap :: #{Key := Group},
                              Key :: term(),
                              Value :: term(),
                              List :: [Elem],
                              Group :: [Value],
                              Elem :: term().

Partitions the given List into a map of groups.

The result is a map where each key is given by KeyFun and each value is a list of elements from the given List, mapped via ValueFun, for which KeyFun returned the same key.

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"]}
Link to this function

intersect(Map1, Map2)

View Source (since OTP 24.0)
-spec intersect(Map1, Map2) -> Map3
                   when 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}
Link to this function

intersect_with(Combiner, Map1, Map2)

View Source (since OTP 24.0)
-spec intersect_with(Combiner, Map1, Map2) -> Map3
                        when
                            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}}
Link to this function

is_key(Key, Map)

View Source (since OTP 17.0)
-spec is_key(Key, Map) -> boolean() when 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
Link to this function

iterator(Map)

View Source (since OTP 21.0)
-spec iterator(Map) -> Iterator when 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 matter 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
Link to this function

iterator(Map, Order)

View Source (since OTP 26.0)
-spec iterator(Map, Order) -> Iterator
                  when
                      Map :: #{Key => Value},
                      Order :: iterator_order(Key),
                      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 sorted by key using the given Order.

The call fails with a {badmap,Map} exception if Map is not a map or if Order is invalid.

Example (when Order is ordered):

> 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 Order is reversed):

> 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 Order is an arithmetic sorting function):

> 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}]
Link to this function

keys(Map)

View Source (since OTP 17.0)
-spec keys(Map) -> Keys when Map :: #{Key => _}, 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"]
Link to this function

map(Fun, MapOrIter)

View Source (since OTP 17.0)
-spec map(Fun, MapOrIter) -> Map
             when
                 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 associated 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}
Link to this function

merge(Map1, Map2)

View Source (since OTP 17.0)
-spec merge(Map1, Map2) -> Map3 when Map1 :: map(), Map2 :: map(), 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}
Link to this function

merge_with(Combiner, Map1, Map2)

View Source (since OTP 24.0)
-spec merge_with(Combiner, Map1, Map2) -> Map3
                    when
                        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 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:merge_with(fun(_Key, Value1, Value2) -> {Value1, Value2} end, Map1, Map2).
#{a => {"value_one",1},b => "value_two",c => 2}
-spec new() -> Map when Map :: #{}.

Returns a new empty map.

Example:

> maps:new().
#{}
Link to this function

next(Iterator)

View Source (since OTP 21.0)
-spec next(Iterator) -> {Key, Value, NextIterator} | none
              when Iterator :: iterator(Key, Value), 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
Link to this function

put(Key, Value, Map1)

View Source (since OTP 17.0)
-spec put(Key, Value, Map1) -> Map2 when Key :: term(), Value :: term(), Map1 :: map(), Map2 :: map().

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.

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}
Link to this function

remove(Key, Map1)

View Source (since OTP 17.0)
-spec remove(Key, Map1) -> Map2 when Key :: term(), Map1 :: map(), 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}
Link to this function

size(Map)

View Source (since OTP 17.0)
-spec size(Map) -> non_neg_integer() when Map :: map().

Returns the number of key-value associations in Map. This operation occurs in constant time.

Example:

> Map = #{42 => value_two,1337 => "value one","a" => 1},
  maps:size(Map).
3
Link to this function

take(Key, Map1)

View Source (since OTP 19.0)
-spec take(Key, Map1) -> {Value, Map2} | error when Map1 :: #{Key => Value, _ => _}, Map2 :: #{_ => _}.

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
Link to this function

to_list(MapOrIterator)

View Source (since OTP 17.0)
-spec to_list(MapOrIterator) -> [{Key, Value}]
                 when MapOrIterator :: #{Key => Value} | iterator(Key, Value).

Returns a list of pairs representing the key-value associations of MapOrIterator, where the pairs [{K1,V1}, ..., {Kn,Vn}] are returned in arbitrary order.

The call fails with a {badmap,Map} exception if MapOrIterator is not a map or an iterator obtained by a call to iterator/1 or iterator/2.

Example:

> Map = #{42 => value_three,1337 => "value two","a" => 1},
  maps:to_list(Map).
[{42,value_three},{1337,"value two"},{"a",1}]

Example (using iterator/2):

> 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}]
Link to this function

update(Key, Value, Map1)

View Source (since OTP 17.0)
-spec update(Key, Value, Map1) -> Map2 when Map1 :: #{Key := _, _ => _}, Map2 :: #{Key := Value, _ => _}.

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}
Link to this function

update_with(Key, Fun, Map1)

View Source (since OTP 19.0)
-spec update_with(Key, Fun, Map1) -> Map2
                     when
                         Map1 :: #{Key := Value1, _ => _},
                         Map2 :: #{Key := Value2, _ => _},
                         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}
Link to this function

update_with(Key, Fun, Init, Map1)

View Source (since OTP 19.0)
-spec update_with(Key, Fun, Init, Map1) -> Map2
                     when
                         Map1 :: #{Key => Value1, _ => _},
                         Map2 :: #{Key := Value2 | Init, _ => _},
                         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}
Link to this function

values(Map)

View Source (since OTP 17.0)
-spec values(Map) -> Values when Map :: #{_ => 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]
Link to this function

with(Ks, Map1)

View Source (since OTP 17.3)
-spec with(Ks, Map1) -> Map2 when Ks :: [K], Map1 :: #{K => V, _ => _}, 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}
Link to this function

without(Ks, Map1)

View Source (since OTP 17.0)
-spec without(Ks, Map1) -> Map2 when Ks :: [K], Map1 :: map(), 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"}