地图 | Map

一组用于处理地图的函数。

地图是Elixir中的“前往”键值数据结构。地图可以用%{}语法创建，键值对可以表示为key => value：

iex> %{}
%{}
iex> %{"one" => :two, 3 => "four"}
%{3 => "four", "one" => :two}

地图中的键值对不遵循任何顺序（这就是为什么上面示例中的打印地图与创建的地图顺序不同）。

地图不对关键字类型施加任何限制：任何东西都可以成为地图中的关键字。作为键值结构，地图不允许重复键。密钥使用完全相等运算符（===）进行比较。如果在地图文字中定义了碰撞键，则以最后一个为准。

当键 - 值对中的键是原子时，key: value可以使用简写语法（如许多其他特殊形式），只要在末尾放置键值对即可：

iex> %{"hello" => "world", a: 1, b: 2}
%{:a => 1, :b => 2, "hello" => "world"}

地图中的键可通过此模块中的某些功能（如Map.get/3或Map.fetch/2）或通过模块[]提供的语法来访问Access：

iex> map = %{a: 1, b: 2}
iex> Map.fetch(map, :a)
{:ok, 1}
iex> map[:b]
2
iex> map["non_existing_key"]
nil

替代访问语法map.key与[]地图具有:key关键字时一起提供; 注意，虽然map[key]将返回nil，如果map不包含key，map.key如果将募集map不包含关键:key。

iex> map = %{foo: "bar", baz: "bong"}
iex> map.foo
"bar"
iex> map.non_existing_key
** (KeyError) key :non_existing_key not found in: %{baz: "bong", foo: "bar"}

地图可以在模式上匹配; 当地图位于模式匹配的左侧时，如果右侧的地图包含左侧的键并且其值与左侧的匹配，则匹配。这意味着空地图匹配每个地图。

iex> %{} = %{foo: "bar"}
%{foo: "bar"}
iex> %{a: a} = %{:a => 1, "b" => 2, [:c, :e, :e] => 3}
iex> a
1
iex> %{:c => 3} = %{:a => 1, 2 => :b}
** (MatchError) no match of right hand side value: %{2 => :b, :a => 1}

在写入地图文本时以及在匹配时，变量都可以用作映射键：

iex> n = 1
1
iex> %{n => :one}
%{1 => :one}
iex> %{^n => :one} = %{1 => :one, 2 => :two, 3 => :three}
%{1 => :one, 2 => :two, 3 => :three}

地图还支持特定的更新语法来更新存储在现有原子键下的值：

iex> map = %{one: 1, two: 2}
iex> %{map | one: "one"}
%{one: "one", two: 2}
iex> %{map | three: 3}
** (KeyError) key :three not found

使用地图的模块

该模块旨在提供执行特定于地图的操作（如访问键，更新值等）的功能。为了将地图作为集合进行遍历，开发人员应该使用Enum适用于各种数据类型的模块。

该Kernel模块还提供了几个功能来处理地图：例如，Kernel.map_size/1了解地图中键值对的数量或Kernel.is_map/1知道某个术语是否为地图。

类型

key()value()

功能

delete(map, key)

删除map对于一个特定的key

drop(map, keys)

丢弃给定keys的map

equal?(map1, map2)

检查两个映射是否相等

fetch(map, key)

获取特定key在给定的map

fetch!(map, key)

获取特定key在给定的map，如果map不包含key

from_struct(struct)

转换struct地图

get(map, key, default \ nil)

获取指定的key在map

get_and_update(map, key, fun)

获取key并更新它，在一次传递中

get_and_update!(map, key, fun)

获取key并更新它。如果没有key

get_lazy(map, key, fun)

获取指定的key在map

has_key?(map, key)

返回给定的key存在于给定的map

keys(map)

返回所有密钥。map

merge(map1, map2)

将两幅地图合并为一幅

merge(map1, map2, callback)

将两个映射合并为一个，通过给定的callback

new()

返回一个新的空映射。

new(enumerable)

创建一个地图。enumerable

new(enumerable, transform)

创建一个地图。enumerable通过给定的变换函数

pop(map, key, default \ nil)

返回并移除与key在map

pop_lazy(map, key, fun)

懒惰返回并删除与keyin 关联的值map

put(map, key, value)

放给value下key在map

put_new(map, key, value)

使给定value下key，除非该条目key中已存在map

put_new_lazy(map, key, fun)

除非已经存在，否则评估fun和放置结果keymapkey

replace(map, key, value)

改变下存储的值key来value，但前提是该条目key中已存在map

replace!(map, key, value)

类似于replace/3，但会引起KeyError如果映射中不存在密钥

split(map, keys)

获取与给定keys在map并将它们提取成一张单独的地图

take(map, keys)

返回密钥map所在的所有键值对的新映射keys

to_list(map)

转换map为列表

update(map, key, initial, fun)

更新key在map具有给定的函数

update!(map, key, fun)

更新key具有给定的函数

values(map)

从中返回所有值 map

key()

key() :: any

value()

value() :: any

delete(map, key)

delete(map, key) :: map

删除map特定条目key。

如果key不存在，返回map没有变化。

实例

iex> Map.delete(%{a: 1, b: 2}, :a)
%{b: 2}
iex> Map.delete(%{b: 2}, :a)
%{b: 2}

编译器插入。

drop(map, keys)

drop(map, Enumerable.t) :: map

丢弃给定keys的map。

如果keys包含不在的键，则map简单地忽略它们。

实例

iex> Map.drop(%{a: 1, b: 2, c: 3}, [:b, :d])
%{a: 1, c: 3}

equal?(map1, map2)

equal?(map, map) :: boolean

检查两个映射是否相等。

如果两个映射包含相同的键，而这些键包含相同的值，则认为它们是相等的。

实例

iex> Map.equal?(%{a: 1, b: 2}, %{b: 2, a: 1})
true
iex> Map.equal?(%{a: 1, b: 2}, %{b: 1, a: 2})
false

fetch(map, key)

fetch(map, key) :: {:ok, value} | :error

获取特定的值，key在给定的map。

如果map包含给定key值value，则{:ok, value}返回。如果map不包含key，:error则返回。

实例

iex> Map.fetch(%{a: 1}, :a)
{:ok, 1}
iex> Map.fetch(%{a: 1}, :b)
:error

编译器插入。

fetch!(map, key)

fetch!(map, key) :: value | no_return

获取key给定值中的特定值，map如果map不包含则返回错误值key。

如果map包含给定key，则返回相应的值。如果map不包含key，KeyError则会引发异常。

实例

iex> Map.fetch!(%{a: 1}, :a)
1
iex> Map.fetch!(%{a: 1}, :b)
** (KeyError) key :b not found in: %{a: 1}

from_struct(struct)

from_struct(atom | struct) :: map

转换struct去地图。

它接受结构模块或结构本身，并简单地__struct__从给定结构或从给定模块生成的新结构中删除该字段。

例

defmodule User do
  defstruct [:name]
end

Map.from_struct(User)
#=> %{name: nil}

Map.from_struct(%User{name: "john"})
#=> %{name: "john"}

get(map, key, default \ nil)

get(map, key, value) :: value

获取特定的价值key在map。

如果key出现在map值中value，则value返回。否则，default返回（nil除非另有说明）。

实例

iex> Map.get(%{}, :a)
nil
iex> Map.get(%{a: 1}, :a)
1
iex> Map.get(%{a: 1}, :b)
nil
iex> Map.get(%{a: 1}, :b, 3)
3

get_and_update(map, key, fun)

get_and_update(map, key, (value -> {get, value} | :pop)) :: {get, map} when get: term

获取key更新一下，一次就可以了。

fun用keyin中的当前值调用map（或者nil如果key不存在map），并且必须返回一个两元素元组：“get”值（返回的值，可以在返回前操作）和新的值存储key在生成的新地图中。fun也可能会返回:pop，这意味着当前值将被移除map并返回（使得该函数的行为类似于Map.pop(map, key)。

返回值是一个带有返回值“get”值的元组，fun以及一个带有更新值的新映射key。

实例

iex> Map.get_and_update(%{a: 1}, :a, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{1, %{a: "new value!"}}

iex> Map.get_and_update(%{a: 1}, :b, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{nil, %{b: "new value!", a: 1}}

iex> Map.get_and_update(%{a: 1}, :a, fn _ -> :pop end)
{1, %{}}

iex> Map.get_and_update(%{a: 1}, :b, fn _ -> :pop end)
{nil, %{a: 1}}

get_and_update!(map, key, fun)

get_and_update!(map, key, (value -> {get, value})) ::
  {get, map} |
  no_return when get: term

从中获取价值key并进行更新。如果没有，则引发key。

表现完全一样get_and_update/3，但KeyError如果key不存在则引发异常map。

实例

iex> Map.get_and_update!(%{a: 1}, :a, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{1, %{a: "new value!"}}

iex> Map.get_and_update!(%{a: 1}, :b, fn current_value ->
...>   {current_value, "new value!"}
...> end)
** (KeyError) key :b not found in: %{a: 1}

iex> Map.get_and_update!(%{a: 1}, :a, fn _ ->
...>   :pop
...> end)
{1, %{}}

get_lazy(map, key, fun)

get_lazy(map, key, (() -> value)) :: value

获取特定的价值key在map。

如果key存在于map有价值value，然后value会被归还。否则，fun计算并返回其结果。

如果默认值计算成本很高，或者通常很难设置和重新删除，这是非常有用的。

实例

iex> map = %{a: 1}
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Map.get_lazy(map, :a, fun)
1
iex> Map.get_lazy(map, :b, fun)
13

has_key?(map, key)

has_key?(map, key) :: boolean

返回给定中是否key存在给定值map。

实例

iex> Map.has_key?(%{a: 1}, :a)
true
iex> Map.has_key?(%{a: 1}, :b)
false

编译器插入。

keys(map)

keys(map) :: [key]

从中返回所有密钥map。

实例

iex> Map.keys(%{a: 1, b: 2})
[:a, :b]

merge(map1, map2)

merge(map, map) :: map

将两幅地图合并为一幅。

所有密钥map2将被添加到map1，覆盖任何现有密钥（即，map2“优先于”中的密钥map1）。

如果你有一个结构，并且你想将一组键合并到结构中，不要使用这个函数，因为它会将右侧的所有键合并到结构中，即使键不是结构的一部分。相反，使用Kernel.struct/2。

实例

iex> Map.merge(%{a: 1, b: 2}, %{a: 3, d: 4})
%{a: 3, b: 2, d: 4}

merge(map1, map2, callback)

merge(map, map, (key, value, value -> value)) :: map

将两张地图合并为一张，通过给定的解决冲突callback。

所有密钥map2将被添加到map1。当有重复的键时，将调用给定的函数; 它的参数是key（重复键），value1（keyin 的值map1）和value2（keyin 的值map2）。返回的值将callback用作key结果映射中的值。

实例

iex> Map.merge(%{a: 1, b: 2}, %{a: 3, d: 4}, fn _k, v1, v2 ->
...>   v1 + v2
...> end)
%{a: 4, b: 2, d: 4}

new()

new() :: map

返回一个新的空地图。

实例

iex> Map.new
%{}

new(enumerable)

new(Enumerable.t) :: map

从一个地图创建一个地图enumerable。

重复的键被移除；最新的键占上风。

实例

iex> Map.new([{:b, 1}, {:a, 2}])
%{a: 2, b: 1}
iex> Map.new([a: 1, a: 2, a: 3])
%{a: 3}

new(enumerable, transform)

new(Enumerable.t, (term -> {key, value})) :: map

enumerable通过给定的转换函数创建一个映射。

重复的密钥被删除; 最新的一个流行。

实例

iex> Map.new([:a, :b], fn x -> {x, x} end)
%{a: :a, b: :b}

pop(map, key, default \ nil)

pop(map, key, value) :: {value, map}

返回并删除与keyin 关联的值map。

如果key存在于map值中value，{value, new_map}则返回从中new_map移除的结果。如果不存在，则返回。keymapkeymap{default, map}

实例

iex> Map.pop(%{a: 1}, :a)
{1, %{}}
iex> Map.pop(%{a: 1}, :b)
{nil, %{a: 1}}
iex> Map.pop(%{a: 1}, :b, 3)
{3, %{a: 1}}

pop_lazy(map, key, fun)

pop_lazy(map, key, (() -> value)) :: {value, map}

懒惰返回并删除与keyin 关联的值map。

如果key存在于map值中value，{value, new_map}则返回从中new_map移除的结果。如果不存在，返回，申请的结果在哪里。keymapkeymap{fun_result, map}fun_resultfun

如果默认值的计算非常昂贵，或者通常难以设置和拆卸，这很有用。

实例

iex> map = %{a: 1}
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Map.pop_lazy(map, :a, fun)
{1, %{}}
iex> Map.pop_lazy(map, :b, fun)
{13, %{a: 1}}

put(map, key, value)

put(map, key, value) :: map

放给value下key在map。

实例

iex> Map.put(%{a: 1}, :b, 2)
%{a: 1, b: 2}
iex> Map.put(%{a: 1, b: 2}, :a, 3)
%{a: 3, b: 2}

编译器插入。

put_new(map, key, value)

put_new(map, key, value) :: map

使给定value下key，除非该条目key中已存在map。

实例

iex> Map.put_new(%{a: 1}, :b, 2)
%{a: 1, b: 2}
iex> Map.put_new(%{a: 1, b: 2}, :a, 3)
%{a: 1, b: 2}

put_new_lazy(map, key, fun)

put_new_lazy(map, key, (() -> value)) :: map

除非已经存在，否则评估fun和放置结果。keymapkey

如果您想要计算要放入的值（key如果该值key尚未存在）（例如，该值计算昂贵或通常难以设置和拆卸），此功能非常有用。

实例

iex> map = %{a: 1}
iex> fun = fn ->
...>   # some expensive operation here
...>   3
...> end
iex> Map.put_new_lazy(map, :a, fun)
%{a: 1}
iex> Map.put_new_lazy(map, :b, fun)
%{a: 1, b: 3}

replace(map, key, value)

replace(map, key, value) :: map

改变下存储的值key来value，但前提是该条目key已经存在map。

实例

iex> Map.replace(%{a: 1}, :b, 2)
%{a: 1}
iex> Map.replace(%{a: 1, b: 2}, :a, 3)
%{a: 3, b: 2}

replace!(map, key, value)

replace!(map, key, value) :: map

类似于replace/3，但KeyError如果密钥不存在于地图中，则会提高。

实例

iex> Map.replace!(%{a: 1, b: 2}, :a, 3)
%{a: 3, b: 2}
iex> Map.replace!(%{a: 1}, :b, 2)
** (KeyError) key :b not found in: %{a: 1}

编译器插入。

split(map, keys)

split(map, Enumerable.t) :: {map, map}

获取与给定的相对应的所有条目keys，map并将它们提取到单独的地图中。

返回带有新映射的元组和带有移除键的旧映射。

没有条目的键map被忽略。

实例

iex> Map.split(%{a: 1, b: 2, c: 3}, [:a, :c, :e])
{%{a: 1, c: 3}, %{b: 2}}

take(map, keys)

take(map, Enumerable.t) :: map

返回密钥map所在的所有键值对的新映射keys。

如果keys包含不在的键，则map简单地忽略它们。

实例

iex> Map.take(%{a: 1, b: 2, c: 3}, [:a, :c, :e])
%{a: 1, c: 3}

to_list(map)

to_list(map) :: [{term, term}]

转换map为列表。

映射中的每个键值对都会转换为{key, value}结果列表中的两元素元组。

实例

iex> Map.to_list(%{a: 1})
[a: 1]
iex> Map.to_list(%{1 => 2})
[{1, 2}]

update(map, key, initial, fun)

update(map, key, value, (value -> value)) :: map

更新key在map用给定的函数。

如果key存在于map值中value，fun则用参数调用value并将其结果用作新的值key。如果key不存在map，initial则插入为值key。初始值不会通过更新功能。

实例

iex> Map.update(%{a: 1}, :a, 13, &(&1 * 2))
%{a: 2}
iex> Map.update(%{a: 1}, :b, 11, &(&1 * 2))
%{a: 1, b: 11}

update!(map, key, fun)

update!(map, key, (value -> value)) :: map

更新key用给定的函数。

如果key存在于map值中value，fun则用参数调用value并将其结果用作新的值key。如果key不存在map，KeyError则会引发异常。

实例

iex> Map.update!(%{a: 1}, :a, &(&1 * 2))
%{a: 2}

iex> Map.update!(%{a: 1}, :b, &(&1 * 2))
** (KeyError) key :b not found in: %{a: 1}

values(map)

values(map) :: [value]

从中返回所有值map。

实例

iex> Map.values(%{a: 1, b: 2})
[1, 2]