maps(3)

NAME
maps - Maps processing functions.

DESCRIPTION

This module contains functions for maps processing.

DATA TYPES
iterator()

    An iterator representing the key value associations in a map.

    Created using maps:iterator/1.

    Consumed by maps:next/1, maps:filter/2, maps:fold/3 and maps:map/2.

EXPORTS

filter(Pred, MapOrIter) -> Map

    Types:
        Pred = fun((Key, Value) -> boolean())
        Key = Value = term()
        MapOrIter = map() | iterator()
        Map = map()

    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:
        Key = term()
        Map = 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.

    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((K, V, AccIn) -> AccOut)
        Init = Acc = AccIn = AccOut = term()
        MapOrIter = map() | iterator()
        K = V = term()

    Calls F(K, V, AccIn) for every K to value V 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:
        Key = term()
        Map = map()
        Value = Default = 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 = map()
        Iterator = iterator()

    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 = map()
        Keys = [Key]
        Key = term()

    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((K, V1) -> V2)
        MapOrIter = map() | iterator()
        Map = map()
        K = V1 = V2 = term()

    Produces a new map Map by calling function fun F(K, V1) for every K to value V1 association in MapOrIter in any order. Function fun F/2 must return value V2 to be associated with key K 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 = map()

    Returns a new empty map.

    Example:

    > maps:new().
    #{}

next(Iterator) -> {Key, Value, NextIterator} | none

    Types:
        Iterator = iterator()
        Key = Value = term()
        NextIterator = iterator()

    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:
        Key = term()
        Map1 = map()
        Value = term()
        Map2 = map()

    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 = map()
        Key = Value = term()

    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:
        Key = Value = term()
        Map1 = Map2 = map()

    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:
        Key = term()
        Map1 = Map2 = map()
        Fun = fun((Value1 :: term()) -> Value2 :: term())

    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:
        Key = term()
        Map1 = Map1
        Map2 = Map2
        Fun = fun((Value1 :: term()) -> Value2 :: term())
        Init = term()

    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 = map()
        Values = [Value]
        Value = term()

    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 = Map2 = map()
        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 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"}