maps(3)



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

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

       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

       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"

       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}

       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 it-
              erator for the remaining associations in the iterator.

              If there are no more associations in the iterator, none  is  re-
              turned.

              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 er-
              ror 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 as-
              sociated 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  as-
              sociated 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.13                       maps(3erl)

Man(1) output converted with man2html
list of all man pages