-spec filter(Pred, MapOrIter) -> Map
                when
                    Pred :: fun((Key, Value) -> boolean()),
                    MapOrIter :: #{Key => Value} | iterator(Key, Value),
                    Map :: #{Key => Value}.

返回一个映射 Map，对于 MapOrIter 中的每一个元素，谓词 Pred 都为真。

如果 MapOrIter 不是映射或有效的迭代器，则调用会失败并抛出 {badmap,Map} 异常；如果 Pred 不是一个arity 为 2 的函数，则会抛出 badarg 异常。

示例

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

-spec filtermap(Fun, MapOrIter) -> Map
                   when
                       Fun :: fun((Key, Value1) -> boolean() | {true, Value2}),
                       MapOrIter :: #{Key => Value1} | iterator(Key, Value1),
                       Map :: #{Key => Value1 | Value2}.

返回一个映射 Map，它是对 MapOrIter 中每个 Key 到值 Value1 的关联按任意顺序调用 Fun(Key, Value1) 的结果。

如果 Fun(Key, Value1) 返回 true，则该关联会被复制到结果映射中。 如果它返回 false，则该关联不会被复制。 如果它返回 {true, NewValue}，则 Key 的值在结果映射中会被替换为 NewValue。

如果 MapOrIter 不是映射或有效的迭代器，则调用会失败并抛出 {badmap,Map} 异常；如果 Fun 不是一个arity 为 2 的函数，则会抛出 badarg 异常。

示例

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

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

返回一个元组 {ok, Value}，其中 Value 是与 Key 关联的值；如果 Map 中没有与 Key 关联的值，则返回 error。

如果 Map 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map = #{"hi" => 42},
  Key = "hi",
  maps:find(Key,Map).
{ok,42}

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

对 MapOrIter 中每个 Key 到值 Value 的关联按任意顺序调用 F(Key, Value, AccIn)。函数 fun F/3 必须返回一个新的累加器，该累加器被传递给下一个连续的调用。此函数返回累加器的最终值。如果映射为空，则返回初始累加器值 Init。

如果 MapOrIter 不是映射或有效的迭代器，则调用会失败并抛出 {badmap,Map} 异常；如果 Fun 不是一个arity 为 3 的函数，则会抛出 badarg 异常。

示例

> 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

-spec foreach(Fun, MapOrIter) -> ok
                 when
                     Fun :: fun((Key, Value) -> term()),
                     MapOrIter :: #{Key => Value} | iterator(Key, Value).

对 MapOrIter 中每个 Key 到值 Value 的关联按任意顺序调用 fun F(Key, Value)。

如果 MapOrIter 不是映射或有效的迭代器，则调用会失败并抛出 {badmap,Map} 异常；如果 Fun 不是一个arity 为 2 的函数，则会抛出 badarg 异常。

-spec from_keys(Keys, Value) -> Map when Keys :: list(), Value :: term(), Map :: map().

接受一个键列表和一个值，并构建一个映射，其中所有键都指向同一个值。键可以是任意顺序，并且键和值可以是任意项。

示例

> Keys = ["a", "b", "c"], maps:from_keys(Keys, ok).
#{"a" => ok,"b" => ok,"c" => ok}

-spec from_list(List) -> Map when List :: [{Key, Value}], Key :: term(), Value :: term(), Map :: map().

接受一个键值元组元素列表并构建一个映射。关联可以是任意顺序，并且关联中的键和值都可以是任意项。

如果同一个键出现多次，则使用后者（最右边的）值，而忽略之前的值。

示例

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

-spec get(Key, Map) -> Value when Key :: term(), Map :: map(), Value :: term().

如果 Map 包含 Key，则返回与 Key 关联的值 Value。

如果 Map 不是映射，则调用会失败并抛出 {badmap,Map} 异常；如果 Key 没有关联的值，则会抛出 {badkey,Key} 异常。

示例

> Key = 1337,
  Map = #{42 => value_two,1337 => "value one","a" => 1},
  maps:get(Key,Map).
"value one"

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

如果 Map 包含 Key，则返回与 Key 关联的值 Value。如果没有与 Key 关联的值，则返回 Default。

如果 Map 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map = #{ key1 => val1, key2 => val2 }.
#{key1 => val1,key2 => val2}
> maps:get(key1, Map, "Default value").
val1
> maps:get(key3, Map, "Default value").
"Default value"

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

将给定的 List 分区到一组映射中。

结果是一个映射，其中每个键由 KeyFun 给出，每个值是给定 List 中 KeyFun 返回相同键的元素的列表。

每个组列表中的元素顺序与原始列表中的顺序一致。

示例

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

-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().

将给定的 List 分区到一组映射中。

结果是一个映射，其中每个键由 KeyFun 给出，每个值是给定 List 中通过 ValueFun 映射的元素的列表，这些元素的 KeyFun 返回相同的键。

每个组列表中的元素顺序与原始列表中的顺序一致。

示例

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

-spec intersect(Map1, Map2) -> Map3
                   when Map1 :: #{Key => term()}, Map2 :: #{term() => Value2}, Map3 :: #{Key => Value2}.

将两个映射相交为一个映射 Map3。如果一个键存在于两个映射中，则 Map1 中的值将被 Map2 中的值取代。

如果 Map1 或 Map2 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map1 = #{a => "value_one", b => "value_two"},
  Map2 = #{a => 1, c => 2},
  maps:intersect(Map1,Map2).
#{a => 1}

-spec intersect_with(Combiner, Map1, Map2) -> Map3
                        when
                            Map1 :: #{Key => Value1},
                            Map2 :: #{term() => Value2},
                            Combiner :: fun((Key, Value1, Value2) -> CombineResult),
                            Map3 :: #{Key => CombineResult}.

将两个映射相交为一个映射 Map3。如果一个键存在于两个映射中，则 Map1 中的值将与 Map2 中的值通过 Combiner 函数组合。

当应用 Combiner 时，在两个映射中都存在的键是第一个参数，来自 Map1 的值是第二个参数，来自 Map2 的值是第三个参数。

如果 Map1 或 Map2 不是映射，则调用会失败并抛出 {badmap,Map} 异常。 如果 Combiner 不是一个接受三个参数的函数，则调用会失败并抛出 badarg 异常。

示例

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

-spec is_key(Key, Map) -> boolean() when Key :: term(), Map :: map().

如果映射 Map 包含 Key，则返回 true；如果它不包含 Key，则返回 false。

如果 Map 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map = #{"42" => value}.
#{"42" => value}
> maps:is_key("42",Map).
true
> maps:is_key(value,Map).
false

-spec iterator(Map) -> Iterator when Map :: #{Key => Value}, Iterator :: iterator(Key, Value).

返回一个映射迭代器 Iterator，maps:next/1 可以使用它来遍历映射中的键值关联。当遍历一个映射时，无论映射的大小如何，内存使用都保证是有界的。

如果 Map 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> 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

-spec iterator(Map, Order) -> Iterator
                  when
                      Map :: #{Key => Value},
                      Order :: iterator_order(Key),
                      Iterator :: iterator(Key, Value).

返回一个映射迭代器 Iterator，maps:next/1 可以使用它来遍历映射中的键值关联，并使用给定的 Order 按键排序。

如果 Map 不是映射或者 Order 无效，则调用会失败并抛出 {badmap,Map} 异常。

示例 (当 Order 是 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

示例 (当 Order 是 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

示例 (当 Order 是一个算术排序函数时):

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

-spec keys(Map) -> Keys when Map :: #{Key => _}, Keys :: [Key].

返回 Map 中所有键的完整列表，顺序任意。

如果 Map 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

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

-spec map(Fun, MapOrIter) -> Map
             when
                 Fun :: fun((Key, Value1) -> Value2),
                 MapOrIter :: #{Key => Value1} | iterator(Key, Value1),
                 Map :: #{Key => Value2}.

通过对 MapOrIter 中每个 Key 到值 Value1 的关联按任意顺序调用函数 fun F(Key, Value1) 来生成一个新的映射 Map。函数 fun Fun/2 必须返回值 Value2，该值将与新映射 Map 的键 Key 关联。

如果 MapOrIter 不是映射或有效的迭代器，则调用会失败并抛出 {badmap,Map} 异常；如果 Fun 不是一个arity 为 2 的函数，则会抛出 badarg 异常。

示例

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

-spec merge(Map1, Map2) -> Map3 when Map1 :: map(), Map2 :: map(), Map3 :: map().

将两个映射合并为一个映射 Map3。如果两个键存在于两个映射中，则 Map1 中的值将被 Map2 中的值取代。

如果 Map1 或 Map2 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map1 = #{a => "value_one", b => "value_two"},
  Map2 = #{a => 1, c => 2},
  maps:merge(Map1,Map2).
#{a => 1,b => "value_two",c => 2}

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

将两个映射合并为一个映射 Map3。如果一个键存在于两个映射中，则 Map1 中的值将与 Map2 中的值通过 Combiner 函数组合。

当应用 Combiner 时，在两个映射中都存在的键是第一个参数，来自 Map1 的值是第二个参数，来自 Map2 的值是第三个参数。

如果 Map1 或 Map2 不是映射，则调用会失败并抛出 {badmap,Map} 异常。 如果 Combiner 不是一个接受三个参数的函数，则调用会失败并抛出 badarg 异常。

示例

> 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 :: #{}.

返回一个新的空映射。

示例

> maps:new().
#{}

-spec next(Iterator) -> {Key, Value, NextIterator} | none
              when Iterator :: iterator(Key, Value), NextIterator :: iterator(Key, Value).

返回 Iterator 中的下一个键值关联和一个新的迭代器，用于迭代器中剩余的关联。

如果迭代器中没有更多关联，则返回 none。

示例

> 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

-spec put(Key, Value, Map1) -> Map2 when Key :: term(), Value :: term(), Map1 :: map(), Map2 :: map().

将 Key 与值 Value 关联，并将该关联插入到映射 Map2 中。如果键 Key 已经存在于映射 Map1 中，则旧的关联值将被值 Value 替换。该函数返回一个新映射 Map2，其中包含新的关联和 Map1 中的旧关联。

如果 Map1 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map = #{"a" => 1}.
#{"a" => 1}
> maps:put("a", 42, Map).
#{"a" => 42}
> maps:put("b", 1337, Map).
#{"a" => 1,"b" => 1337}

-spec remove(Key, Map1) -> Map2 when Key :: term(), Map1 :: map(), Map2 :: map().

从 Map1 中删除 Key（如果存在）及其关联的值，并返回一个不包含键 Key 的新映射 Map2。

如果 Map1 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map = #{"a" => 1}.
#{"a" => 1}
> maps:remove("a",Map).
#{}
> maps:remove("b",Map).
#{"a" => 1}

-spec size(Map) -> non_neg_integer() when Map :: map().

返回 Map 中键值关联的数量。此操作以恒定时间完成。

示例

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

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

该函数从 Map1 中删除 Key（如果存在）及其关联的值，并返回一个元组，其中包含删除的 Value 和不包含键 Key 的新映射 Map2。如果键不存在，则返回 error。

如果 Map1 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

> Map = #{"a" => "hello", "b" => "world"}.
#{"a" => "hello", "b" => "world"}
> maps:take("a",Map).
{"hello",#{"b" => "world"}}
> maps:take("does not exist",Map).
error

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

返回一个表示 MapOrIterator 的键值关联的对列表，其中对 [{K1,V1}, ..., {Kn,Vn}] 以任意顺序返回。

如果 MapOrIterator 不是映射或通过调用 iterator/1 或 iterator/2 获得的迭代器，则调用会失败并抛出 {badmap,Map} 异常。

示例

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

示例 (使用 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}]

-spec update(Key, Value, Map1) -> Map2 when Map1 :: #{Key := _, _ => _}, Map2 :: #{Key := Value, _ => _}.

如果 Key 存在于 Map1 中，则旧的关联值将被值 Value 替换。该函数返回一个包含新关联值的新映射 Map2。

如果 Map1 不是映射，则调用会失败并抛出 {badmap,Map} 异常；如果 Key 没有关联的值，则会抛出 {badkey,Key} 异常。

示例

> Map = #{"a" => 1}.
#{"a" => 1}
> maps:update("a", 42, Map).
#{"a" => 42}

-spec update_with(Key, Fun, Map1) -> Map2
                     when
                         Map1 :: #{Key := Value1, _ => _},
                         Map2 :: #{Key := Value2, _ => _},
                         Fun :: fun((Value1) -> Value2).

通过对旧值调用 Fun 来获取新值，从而更新 Map1 中与 Key 关联的值。如果 Key 不在映射中，则会生成一个异常 {badkey,Key}。

示例

> Map = #{"counter" => 1},
  Fun = fun(V) -> V + 1 end,
  maps:update_with("counter",Fun,Map).
#{"counter" => 2}

-spec update_with(Key, Fun, Init, Map1) -> Map2
                     when
                         Map1 :: #{Key => Value1, _ => _},
                         Map2 :: #{Key := Value2 | Init, _ => _},
                         Fun :: fun((Value1) -> Value2).

通过对旧值调用 Fun 来获取新值，从而更新 Map1 中与 Key 关联的值。如果 Key 不在 Map1 中，则 Init 将与 Key 关联。

示例

> Map = #{"counter" => 1},
  Fun = fun(V) -> V + 1 end,
  maps:update_with("new counter",Fun,42,Map).
#{"counter" => 1,"new counter" => 42}

-spec values(Map) -> Values when Map :: #{_ => Value}, Values :: [Value].

返回映射 Map 中包含的所有值的完整列表，顺序任意。

如果 Map 不是映射，则调用会失败并抛出 {badmap,Map} 异常。

示例

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

-spec with(Ks, Map1) -> Map2 when Ks :: [K], Map1 :: #{K => V, _ => _}, Map2 :: #{K => V}.

返回一个新映射 Map2，其中包含键 K1 到 Kn 以及它们在映射 Map1 中的关联值。Ks 中任何不存在于 Map1 中的键都将被忽略。

示例

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

-spec without(Ks, Map1) -> Map2 when Ks :: [K], Map1 :: map(), Map2 :: map(), K :: term().

返回一个新映射 Map2，其中不包含来自映射 Map1 的键 K1 到 Kn 及其关联的值。Ks 中任何不存在于 Map1 中的键都将被忽略。

示例

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