Erlang--STDLIB：maps

Module

maps

Exports

filter(Pred, MapOrIter) -> Map

Types

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

该函数用于过滤map中的元素。
第一个参数Pred是一个返回值是布尔型的函数，第二个参数是一个map；调用该函数时，map会被遍历调用Pred，Pred判定为true的元素才会被保留。返回一个经过Pred过滤的map。

如果第二个参数MapOrIter不是一个map或者有效的iterator，将会返回 {badmap,Map} ，如果第一个参数Pred不是一个有两个参数的函数，将会返回badarg

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

如果在Key在Map中有对应的Value，则返回{ok, Value}；否则返回error。

如果参数Map不是一个map，将会返回 {badmap,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()

对map里面的键值对递归遍历执行一系列操作。
按任意顺序为MapOrIter中的每个key-value键值对调用F（K，V，AccIn）。函数fun F / 3返回一个新的累加器，它将被传递给下一次连续的调用。此函数返回累加器的最终值。如果map为空，则返回初始累加器值Init。

如果第二个参数MapOrIter不是一个map或者有效的iterator，将会返回 {badmap,Map} ，如果第一个参数Pred不是一个有三个参数的函数，将会返回badarg。

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

将[{key1, val1}, {key2, val2}]这种形式的列表转换为#{key1 => val1, key2 => val2} = map
如果同一个key出现多次，则使用后一个（最右侧）值，并忽略先前的值。

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

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

如果第二个参数Map不是一个map，将会返回 {badmap,Map} ，Key在Map中没有对应的Value值，则会返回{badkey,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()

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

如果第二个参数Map不是一个map，将会返回 {badmap,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()

如果Map包含Key，则返回true; 如果不包含Key，则返回false。

如果第二个参数Map不是一个map，将会返回 {badmap,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()

返回一个能使用 maps:next/1 遍历map中的键值对的迭代器Iterator。

如果第一个参数Map不是一个map，将会返回 {badmap,Map} 。

Example:

> M = #{ a => 1, b => 2 }.
#{a => 1,b => 2}
> I = maps:iterator(M).
[{a,1},{b,2}]
> {K1, V1, I2} = maps:next(I).
{a,1,[{b,2}]}
> {K2, V2, I3} = maps:next(I2).
{b,2,[]}
> maps:next(I3).
none

keys(Map) -> Keys

Types

Map = map()
Keys = [Key]
Key = term()

返回map中所有key组成的列表，且这个列表是的顺序是任意的。

如果第一个参数Map不是一个map，将会返回 {badmap,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()

通过对Map中每一个Key-Value键值对调用fun F(K, V1)，返回一个新的Val值，生成一个新的Map

如果第二个参数Map不是一个map，则会返回 {badmap,Map} ；

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

merge(Map1, Map2) -> Map3

将map合并为一个新map，如果两个map中都存在两个Key，则Map1中的值将被Map2中的值取代。

如果参数Map1或Map2不是一个map，则会返回 {badmap,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()

返回一个空的map

Example:

> maps:new().
#{}

put(Key, Value, Map1) -> Map2

Types

Key = Value = term()
Map1 = Map2 = map()

将Key与值Value关联，插入到Map1中。
如果Key已存在于映射Map1中，则新的Value将会替换旧的Value值。返回Map2。

如果参数Map1不是一个map，则会返回 {badmap,Map} 。

Example:

> maps:new().
#{}

remove(Key, Map1) -> Map2

Types

Key = term()
Map1 = Map2 = map()

删除Key（如果存在）及其与Map1的Value，并返回没有键Key的新映射Map2

如果参数Map1不是一个map，则会返回 {badmap,Map} 。

Example:

> maps:new().
#{}

size(Map) -> integer() >= 0

Types

Map = map()

返回Map中的Key-Value键值对数量。

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

该函数删除Key及其在Map1中对应Value，并返回带有已删除Key对应的Value和没有Key的Map2所组成的元组。
如果Key不存在，则返回error。

如果参数Map1不是一个map，则会返回 {badmap,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
3

to_list(Map) -> [{Key, Value}]

Types

Map = map()
Key = Value = term()

将map中的 #{K1 => V1, K2 => V2} ，转换为列表[{K1, V1}, {K2, V2}]

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

如果Key存在于Map1中，则旧的Value将替换为新的Value。该函数返回包含新Value的Map2。

如果Map1不是map，则返回{badmap，Map}；如果没有与Key关联的值，返回{badkey，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())

通过Map1中Key对应的Value调用Fun得到一个新的Value，并更新与Key关联的Map1中的值，得到一个新的Map2。

如果map中不存在该Key，返回{badkey，Key}。

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

用Map1中Key对应的Value调用Fun，得到一个新的Value，并更新与Key关联的Map1中的值，得到一个新的Map2。
如果Map1中没有Key，那么Init成为与Key相关联的Value。

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

返回map中所有value组成的列表，且这个列表是的顺序是任意的。

如果第一个参数Map不是一个map，将会返回 {badmap,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()

Ks为一个List [K1, K2, … , Kn]，Ks中的每个元素都为一个Key
返回一个新的Map2，Map2只包含Map1在列表Ks中存在的Key以及对应的Value值。

如果第二个参数Map不是一个map，将会返回 {badmap,Map} 。

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

Ks为一个List [K1, K2, … , Kn]，Ks中的每个元素都为一个Key
返回一个新的Map2，Map2只包含Map1在列表Ks中不存在的Key以及对应的Value值。

如果第二个参数Map不是一个map，将会返回 {badmap,Map} 。

Example:

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