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

返回一個映射 Map，其中謂詞 Pred 在 MapOrIter 中成立。

如果 MapOrIter 不是 map 或有效的迭代器，則呼叫會失敗並拋出 {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，則該關聯會複製到結果 map 中。如果回傳 false，則不會複製該關聯。如果回傳 {true, NewValue}，則結果 map 中 Key 的值會被替換為 NewValue。

如果 MapOrIter 不是 map 或有效的迭代器，則呼叫會失敗並拋出 {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 不是 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 不是 map 或有效的迭代器，則呼叫會失敗並拋出 {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 不是 map 或有效的迭代器，則呼叫會失敗並拋出 {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 不是 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 不是 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 分割成一個群組映射。

結果是一個 map，其中每個鍵由 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 分割成一個群組映射。

結果是一個 map，其中每個鍵由 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 不是 map，則呼叫會失敗並拋出 {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 時，存在於兩個 map 中的鍵是第一個參數，來自 Map1 的值是第二個參數，來自 Map2 的值是第三個參數。

如果 Map1 或 Map2 不是 map，則呼叫會失敗並拋出 {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 不是 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 不是 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 不是 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 不是 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 不是 map 或有效的迭代器，則呼叫會失敗並拋出 {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 不是 map，則呼叫會失敗並拋出 {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 時，存在於兩個 map 中的鍵是第一個參數，來自 Map1 的值是第二個參數，來自 Map2 的值是第三個參數。

如果 Map1 或 Map2 不是 map，則呼叫會失敗並拋出 {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 不是 map，則呼叫會失敗並拋出 {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 不是 map，則呼叫會失敗並拋出 {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 不是 map，則呼叫會失敗並拋出 {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 不是 map 或透過呼叫 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 不是 map，則呼叫會失敗並拋出 {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 來取得新值，以更新與 Key 相關聯的 Map1 中的值。如果 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 來取得新值，以更新與 Key 相關聯的 Map1 中的值。如果 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 不是 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 的關聯值。任何在 Map1 中不存在的 Ks 中的鍵都會被忽略。

範例

> 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 及其關聯值。任何在 Map1 中不存在的 Ks 中的鍵都會被忽略

範例

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