Map

Карты — это основная структура данных "ключ-значение" в Elixir.

Карты можно создавать с помощью синтаксиса %{}, а пары "ключ-значение" можно выразить как key => value.

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

Пары "ключ-значение" в карте не следуют никакому порядку (поэтому отпечатанная карта в примере выше имеет другой порядок, чем карта, которая была создана).

Карты не накладывают никаких ограничений на тип ключа: ключом в карте может быть всё. Как структура "ключ-значение", карты не допускают дублирования ключей. Ключи сравниваются с помощью оператора точного равенства (===/2). Если в литерале карты определены коллидирующие ключи, приоритет имеет последний.

Когда ключ в паре "ключ-значение" является атомом, можно использовать сокращённый синтаксис key: value (как и во многих других специальных формах):

iex> %{a: 1, b: 2}
%{a: 1, b: 2}

Если вы хотите смешать сокращённый синтаксис с =>, сокращённый синтаксис должен стоять в конце:

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

К ключам в картах можно получить доступ с помощью некоторых функций в этом модуле (например, Map.get/3 или Map.fetch/2) или с помощью синтаксиса map[], предоставляемого модулем 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. Обратите внимание, что map.key вызовет исключение KeyError, если карта map не содержит ключ :key, в отличие от map[:key], которая вернёт nil.

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

Избегайте скобок

Не добавляйте скобки при обращении к полям, как в data.key(). Если скобки используются, Elixir ожидает, что data будет атомом, представляющим модуль, и попытается вызвать функцию key/0 в нём.

Два синтаксиса для доступа к ключам раскрывают двойственную природу карт. Синтаксис map[key] используется для динамически созданных карт, которые могут иметь любой ключ любого типа. map.key используется с картами, содержащими предопределённый набор атомных ключей, которые, как ожидается, всегда будут присутствовать. Структуры, определённые с помощью defstruct/1, являются одним примером таких "статических карт", где ключи также могут проверяться во время компиляции.

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

iex> %{} = %{foo: "bar"}
%{foo: "bar"}
iex> %{a: a} = %{:a => 1, "b" => 2, [:c, :e, :e] => 3}
iex> a
1

Но это вызовет исключение MatchError:

%{:c => 3} = %{:a => 1, 2 => :b}

Переменные могут использоваться в качестве ключей карт как при написании литералов карт, так и при сопоставлении:

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> other_map = %{"three" => 3, "four" => 4}
iex> %{other_map | "three" => "three"}
%{"four" => 4, "three" => "three"}

При обновлении ключа, который не существует в карте, будет вызвано исключение KeyError:

%{map | three: 3}

Функции в этом модуле, которые должны найти определённый ключ, работают за логарифмическое время. Это означает, что время, необходимое для поиска ключей, растёт по мере увеличения карты, но оно не прямо пропорционально размеру карты. По сравнению с поиском элемента в списке, это работает лучше, потому что списки имеют линейную сложность времени. Некоторые функции, такие как keys/1 и values/1, работают за линейное время, потому что им необходимо получить доступ ко всем элементам карты.

Карты также реализуют протокол Enumerable, поэтому многие функции для работы с картами находятся в модуле Enum. Кроме того, следующие функции для карт находятся в Kernel:

map_size/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.
filter(map, fun): Возвращает словарь, содержащий только те пары из map, для которых fun возвращает истинное значение.
from_keys(keys, value): Создаёт словарь из заданных keys и фиксированного value.
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.
intersect(map1, map2): Пересекает два словаря, возвращая словарь с общими ключами.
intersect(map1, map2, fun): Пересекает два словаря, возвращая словарь с общими ключами и разрешая конфликты с помощью функции.
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!(map, key): Удаляет значение, связанное с key в map и возвращает значение и обновлённый словарь, или возбуждает исключение, если key отсутствует.
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 ещё не присутствует.
reject(map, fun): Возвращает словарь, исключая пары из map для которых fun возвращает истинное значение.
replace(map, key, value): Заменяет значение под key только если key уже существует в map.
replace!(map, key, value): Заменяет значение под key только если key уже существует в map.
replace_lazy(map, key, fun): Заменяет значение под key с помощью заданной функции только если key уже существует в map.
split(map, keys): Берёт все записи, соответствующие указанным keys в map и извлекает их в отдельный словарь.
split_with(map, fun): Разделяет map на два словаря в соответствии с заданной функцией fun.
take(map, keys): Возвращает новый словарь со всеми парами ключ-значение в map , где ключ находится в keys.
to_list(map): Преобразует map в список.
update(map, key, default, fun): Обновляет key в map с помощью заданной функции.
update!(map, key, fun): Обновляет key с помощью заданной функции.
values(map): Возвращает все значения из map.

key()Source

@type key() :: any()

value()Source

@type value() :: any()

delete(map, key)Source

@spec delete(map(), key()) :: map()

Удаляет запись в map для определенного key.

Если key не существует, возвращает map без изменений.

Встроено компилятором.

Map

Избегайте скобок

Типы

Функции

key()Source

value()Source

delete(map, key)Source

drop(map, keys)Source

equal?(map1, map2)Source

fetch(map, key)Source

fetch!(map, key)Source

filter(map, fun)Source

Рекомендации по производительности

from_keys(keys, value)Source

from_struct(struct)Source

get(map, key, default \\ nil)Source

get_and_update(map, key, fun)Source

get_and_update!(map, key, fun)Source

get_lazy(map, key, fun)Source

has_key?(map, key)Source

intersect(map1, map2)Source

intersect(map1, map2, fun)Source

keys(map)Source

merge(map1, map2)Source

merge(map1, map2, fun)Source

new()Source

new(enumerable)Source

new(enumerable, transform)Source

pop(map, key, default \\ nil)Source

pop!(map, key)Source

pop_lazy(map, key, fun)Source

put(map, key, value)Source

put_new(map, key, value)Source

put_new_lazy(map, key, fun)Source

reject(map, fun)Source

replace(map, key, value)Source

replace!(map, key, value)Source

replace_lazy(map, key, fun)Source

split(map, keys)Source

split_with(map, fun)Source

take(map, keys)Source

to_list(map)Source

update(map, key, default, fun)Source

update!(map, key, fun)Source

values(map)Source