Карта

Набор функций для работы с картами.

Карты — это структура данных «ключ-значение» по умолчанию в 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 для определения, является ли термин картой.

Резюме

Функции

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, fun): Объединяет две карты в одну, разрешая конфликты с помощью заданной fun
new(): Возвращает новую пустую карту
new(enumerable): Создает карту из enumerable
new(enumerable, transform): Создает карту из enumerable с помощью заданной функции преобразования
pop(map, key, default \\ nil): Возвращает и удаляет значение, связанное с key в map
pop_lazy(map, key, fun): Лениво возвращает и удаляет значение, связанное с key в map
put(map, key, value): Добавляет заданное value под key в map
put_new(map, key, value): Добавляет заданное value под key, если запись key еще не существует в map
put_new_lazy(map, key, fun): Вычисляет fun и добавляет результат под key в map, если key еще не присутствует
replace!(map, key, value): Изменяет значение, хранящееся под key на value, но только если запись key уже существует в map
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 или сам struct и просто удаляет поле __struct__ из заданного 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 вызывается со текущим значением под key в map (или nil, если key не присутствует в map) и должно вернуть кортеж из двух элементов: значение «получения» (извлеченное значение, которое можно обработать перед возвратом) и новое значение, которое должно храниться под key в результирующей новой карте. fun также может вернуть :pop, что означает, что текущее значение должно быть удалено из map и возвращено (что делает эту функцию похожей на Map.pop(map, key)).

Возвращаемое значение — кортеж со значением «получения», возвращенным 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()} | :pop)) ::
  {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, fun)

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

Объединяет две карты в одну, разрешая конфликты с помощью заданной fun.

Все ключи в map2 будут добавлены в map1. Заданная функция будет вызвана при наличии дублирующихся ключей; ее аргументы — key (дублирующийся ключ), value1 (значение key в map1), и value2 (значение key в map2). Значение, возвращенное fun, используется как значение под 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()}

Возвращает и удаляет значение, связанное с key в map.

Если key присутствует в map со значением value, возвращается {value, new_map}, где new_map — результат удаления key из map . Если key отсутствует в map, возвращается {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()}

Лениво возвращает и удаляет значение, связанное с key в map.

Это полезно, если значение по умолчанию очень дорого вычисляется или его сложно настроить и отключить.

Примеры

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 и помещает результат под key в map, если key еще не присутствует.

Эта функция полезна, если вы хотите вычислить значение, которое нужно поместить под 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.

Если key не присутствует в map, возникает исключение 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 в список.

Каждая пара ключ-значение в 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 с помощью заданной функции.

Примеры

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]