Provided by: erlang-manpages_22.0.7+dfsg-1build1_all bug

NAME

       maps - Maps processing functions.

DESCRIPTION

       This module contains functions for maps processing.

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 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}

       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 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

       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
              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 = 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"

       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 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

       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 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}

       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}

       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  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}

       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 operation 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"}