Карта

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

Карты — это хранилища пар ключ-значение, где ключи могут быть любыми значениями и сравниваются с помощью оператора совпадения (===). Карты могут быть созданы с помощью специальной формы %{}, определённой в модуле Kernel.SpecialForms.

Обзор

Типы

key()
value()

Функции

delete(map, key): Удаляет записи в map для определённого key
drop(map, keys): Удаляет заданные keys из map
equal?(map1, map2): Проверяет, равны ли две карты
fetch(map, key): Извлекает значение для определённого key и возвращает его в кортеже
fetch!(map, key): Извлекает значение для указанного key
from_struct(struct): Преобразует struct в карту
get(map, key, default \\ nil): Получает значение для определённого key
get_and_update(map, key, fun): Получает значение из key и обновляет его за один проход
get_and_update!(map, key, fun): Получает значение из key и обновляет его. Выбрасывает исключение, если соответствующего key нет
get_lazy(map, key, fun): Получает значение для указанного key
has_key?(map, key): Возвращает, существует ли указанный key в данной map
keys(map): Возвращает все ключи из map
merge(map1, map2): Объединяет две карты в одну
merge(map1, map2, callback): Объединяет две карты в одну
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, val): Добавляет заданное value под key
put_new(map, key, value): Добавляет заданное value под key только если запись key ещё не существует
put_new_lazy(map, key, fun): Вычисляет fun и добавляет результат под key в карту, если key ещё не присутствует
split(map, keys): Берёт все записи, соответствующие указанным keys и выделяет их в отдельную map
take(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.

Примеры

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 и возвращает его в кортеже.

Если 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.

Если 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.

Если key не существует, возвращает значение по умолчанию (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 (или nil если key отсутствует) и должен возвращать кортеж из двух элементов: значение «get» (извлечённое значение, которое можно обработать перед возвратом) и новое значение, которое будет сохранено под key. Аргумент fun также может вернуть :pop, подразумевая, что текущее значение должно быть удалено из map и возвращено.

Возвращаемое значение — кортеж, содержащий значение «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.

Аргумент fun получает значение key и должен возвращать кортеж из двух элементов: значение «get» (извлечённое значение, которое можно обработать перед возвратом) и новое значение, которое будет сохранено под 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)
** (KeyError) key :b not found

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

get_lazy(map, key, fun)

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

Получает значение для указанного key.

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

Если у вас есть структура и вы хотите объединить набор ключей в структуру, не используйте эту функцию, так как она объединит все ключи справа в структуру, даже если ключ не является частью структуры. Вместо этого используйте 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

Объединяет две карты в одну.

Все ключи из map2 будут добавлены в map1. Указанная функция будет вызвана с ключом, значением1 и значением2 для разрешения конфликтов.

Примеры

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

Примеры

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, val)

put(map, key, value) :: map

Добавляет заданное value под key.

Примеры

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 ещё не существует.

Примеры

iex> Map.put_new(%{a: 1}, :b, 2)
%{b: 2, a: 1}
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 ещё не существует.

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

Примеры

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}

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

Взять все записи, соответствующие заданным ключам, и вернуть их в новой карте.

Примеры

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 в список.

Примеры

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 не существует, вставляет заданное initial значение.

Примеры

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

Обновляет key с помощью заданной функции.

Если key не существует, поднимает KeyError.

Примеры

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

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

values(map)

values(map) :: [value]

Возвращает все значения из map.

Примеры

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