Ключевое слово

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

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

Например, следующий список является ключевым словом:

[{:exit_on_close, true}, {:active, :once}, {:packet_size, 1024}]

Elixir предоставляет специальный и более лаконичный синтаксис для списков ключевых слов, который выглядит так:

[exit_on_close: true, active: :once, packet_size: 1024]

Это также синтаксис, который Elixir использует для проверки списков ключевых слов:

iex> [{:active, :once}]
[active: :once]

Оба синтаксиса полностью эквивалентны. Как и атомы, ключевые слова должны состоять из символов Юникода, таких как буквы, цифры, нижнее подчеркивание и @. Если ключевое слово содержит символ, который не относится к вышеуказанной категории, например, пробелы, вы можете заключить его в кавычки:

iex> ["exit on close": true]
["exit on close": true]

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

Обратите внимание, что когда списки ключевых слов передаются в качестве последнего аргумента функции, если используется сокращённый синтаксис, то квадратные скобки вокруг списка ключевых слов также могут быть опущены. Например, следующее:

String.split("1-0", "-", trim: true, parts: 2)

эквивалентно:

String.split("1-0", "-", [trim: true, parts: 2])

Ключевое слово может иметь дублирующиеся ключи, поэтому это не строго говоря хранилище ключ-значение. Однако большинство функций в этом модуле ведут себя точно как словарь, поэтому они работают аналогично функциям, которые вы найдёте в модуле Map.

Например, Keyword.get/3 получит первую запись, соответствующую заданному ключу, независимо от того, существуют ли дублирующиеся записи. Аналогично, Keyword.put/3 и Keyword.delete/3 гарантируют удаление всех дублирующихся записей для данного ключа при вызове. Обратите внимание, что операции, требующие поиска ключей в списке ключевых слов (например, Keyword.get/3), требуют перебора списка для поиска ключей, поэтому эти операции могут быть медленнее, чем их аналоги из модуля map.

Существует несколько функций для обработки дублирующихся ключей, в частности, Enum.into/2 позволяет создавать новые ключевые слова без удаления дублирующихся ключей, get_values/2 возвращает все значения для данного ключа, а delete_first/2 удаляет только одну из существующих записей.

Функции в Keyword не гарантируют каких-либо свойств в отношении упорядоченности. Однако, поскольку список ключевых слов — это просто список, к нему также можно применять все операции, определённые в Enum и List, особенно когда требуется упорядоченность.

Краткое описание

Функции

delete(keywords, key): Удаляет записи в списке ключевых слов для определённого key.
delete(keywords, key, value): Удаляет записи в списке ключевых слов для key с value.
delete_first(keywords, key): Удаляет первую запись в списке ключевых слов для определённого key.
drop(keywords, keys): Удаляет заданные ключи из списка ключевых слов.
equal?(left, right): Проверяет, равны ли два ключевых слова.
fetch(keywords, key): Извлекает значение для определённого key и возвращает его в кортеже.
fetch!(keywords, key): Извлекает значение для определённого key.
get(keywords, key, default \\ nil): Получает значение для определённого key.
get_and_update(keywords, key, fun): Получает значение из key и обновляет его, все в одной операции.
get_and_update!(keywords, key, fun): Получает значение из key и обновляет его. Выбрасывает исключение, если key не существует.
get_lazy(keywords, key, fun): Получает значение для определённого key.
get_values(keywords, key): Получает все значения для определённого key.
has_key?(keywords, key): Возвращает значение true, если заданный key существует в заданном keywords.
keys(keywords): Возвращает все ключи из списка ключевых слов.
keyword?(term): Возвращает true, если term является списком ключевых слов; в противном случае возвращает false.
merge(keywords1, keywords2): Объединяет два списка ключевых слов в один.
merge(keywords1, keywords2, fun): Объединяет два списка ключевых слов в один.
new(): Возвращает пустой список ключевых слов, т.е. пустой список.
new(pairs): Создаёт ключевое слово из перечислимого объекта.
new(pairs, transform): Создаёт ключевое слово из перечислимого объекта с помощью функции преобразования.
pop(keywords, key, default \\ nil): Возвращает и удаляет все значения, связанные с key в списке ключевых слов.
pop_first(keywords, key, default \\ nil): Возвращает и удаляет первое значение, связанное с key в списке ключевых слов.
pop_lazy(keywords, key, fun): Лениво возвращает и удаляет все значения, связанные с key в списке ключевых слов.
put(keywords, key, value): Добавляет заданное value под key.
put_new(keywords, key, value): Добавляет заданное value под key только если запись key ещё не существует.
put_new_lazy(keywords, key, fun): Вычисляет fun и добавляет результат под key в списке ключевых слов, если key ещё не присутствует.
replace!(keywords, key, value): Изменяет значение, хранящееся под key на value, но только если запись key уже существует в keywords.
split(keywords, keys): Берёт все записи, соответствующие заданным ключам, и извлекает их в отдельный список ключевых слов.
take(keywords, keys): Берёт все записи, соответствующие заданным ключам, и возвращает их в новом списке ключевых слов.
to_list(keyword): Возвращает сам список ключевых слов.
update(keywords, key, initial, fun): Обновляет key в keywords с помощью заданной функции.
update!(keywords, key, fun): Обновляет key с помощью заданной функции.
values(keywords): Возвращает все значения из списка ключевых слов.

Типы

key()

key() :: atom()

t()

t() :: [{key(), value()}]

t(value)

t(value) :: [{key(), value}]

value()

value() :: any()

Функции

delete(keywords, key)

delete(t(), key()) :: t()

Удаляет записи в списке ключевых слов для определённого key.

Если key не существует, возвращает список ключевых слов без изменений. Используйте delete_first/2 для удаления только первой записи в случае дублирующихся ключей.

Примеры

iex> Keyword.delete([a: 1, b: 2], :a)
[b: 2]
iex> Keyword.delete([a: 1, b: 2, a: 3], :a)
[b: 2]
iex> Keyword.delete([b: 2], :a)
[b: 2]

delete(keywords, key, value)

delete(t(), key(), value()) :: t()

Удаляет записи в списке ключевых слов для key с value.

Если key с value не существует, возвращает список ключевых слов без изменений.

Примеры

iex> Keyword.delete([a: 1, b: 2], :a, 1)
[b: 2]
iex> Keyword.delete([a: 1, b: 2, a: 3], :a, 3)
[a: 1, b: 2]
iex> Keyword.delete([a: 1], :a, 5)
[a: 1]
iex> Keyword.delete([a: 1], :b, 5)
[a: 1]

delete_first(keywords, key)

delete_first(t(), key()) :: t()

Удаляет первую запись в списке ключевых слов для определенного key.

Если key не существует, возвращает список ключевых слов без изменений.

Примеры

iex> Keyword.delete_first([a: 1, b: 2, a: 3], :a)
[b: 2, a: 3]
iex> Keyword.delete_first([b: 2], :a)
[b: 2]

drop(keywords, keys)

drop(t(), [key()]) :: t()

Удаляет заданные ключи из списка ключевых слов.

Дублирующиеся ключи сохраняются в новом списке ключевых слов.

Примеры

iex> Keyword.drop([a: 1, b: 2, c: 3], [:b, :d])
[a: 1, c: 3]
iex> Keyword.drop([a: 1, b: 2, b: 3, c: 3, a: 5], [:b, :d])
[a: 1, c: 3, a: 5]

equal?(left, right)

equal?(t(), t()) :: boolean()

Проверяет, равны ли два ключевых слова.

Два ключевых слова считаются равными, если они содержат одинаковые ключи, и эти ключи содержат одинаковые значения.

Примеры

iex> Keyword.equal?([a: 1, b: 2], [b: 2, a: 1])
true
iex> Keyword.equal?([a: 1, b: 2], [b: 1, a: 2])
false
iex> Keyword.equal?([a: 1, b: 2, a: 3], [b: 2, a: 3, a: 1])
true

fetch(keywords, key)

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

Извлекает значение для определенного key и возвращает его в кортеже.

Если key не существует, возвращает :error.

Примеры

iex> Keyword.fetch([a: 1], :a)
{:ok, 1}
iex> Keyword.fetch([a: 1], :b)
:error

fetch!(keywords, key)

fetch!(t(), key()) :: value()

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

Если key не существует, генерируется исключение KeyError.

Примеры

iex> Keyword.fetch!([a: 1], :a)
1
iex> Keyword.fetch!([a: 1], :b)
** (KeyError) key :b not found in: [a: 1]

get(keywords, key, default \\ nil)

get(t(), key(), value()) :: value()

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

Если key не существует, возвращает значение по умолчанию (nil если значение по умолчанию не задано).

Если существуют дублирующиеся записи, возвращается первая. Используйте get_values/2, чтобы получить все записи.

Примеры

iex> Keyword.get([], :a)
nil
iex> Keyword.get([a: 1], :a)
1
iex> Keyword.get([a: 1], :b)
nil
iex> Keyword.get([a: 1], :b, 3)
3

С дублирующимися ключами:

iex> Keyword.get([a: 1, a: 2], :a, 3)
1
iex> Keyword.get([a: 1, a: 2], :b, 3)
3

get_and_update(keywords, key, fun)

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

Получает значение из key и обновляет его за один проход.

Аргумент fun получает значение key (или nil если key отсутствует) и должен вернуть кортеж из двух элементов: значение «получить» (извлеченное значение, над которым можно произвести операции перед возвратом) и новое значение для хранения под key. Аргумент fun также может вернуть :pop, подразумевая, что текущее значение должно быть удалено из списка ключевых слов и возвращено.

Возвращаемое значение — кортеж со значением «получить», возвращенным fun, и новым списком ключевых слов с обновленным значением под key.

Примеры

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

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

iex> Keyword.get_and_update([a: 1], :a, fn _ -> :pop end)
{1, []}

iex> Keyword.get_and_update([a: 1], :b, fn _ -> :pop end)
{nil, [a: 1]}

get_and_update!(keywords, key, fun)

get_and_update!(t(), key(), (value() -> {get, value()})) :: {get, t()}
when get: term()

Получает значение из key и обновляет его. Выбрасывает исключение, если key отсутствует.

Аргумент fun получает значение key и должен вернуть кортеж из двух элементов: значение «получить» (извлеченное значение, над которым можно произвести операции перед возвратом) и новое значение для хранения под key.

Примеры

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

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

iex> Keyword.get_and_update!([a: 1], :a, fn _ ->
...>   :pop
...> end)
{1, []}

get_lazy(keywords, key, fun)

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

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

Если key не существует, лениво вычисляет fun и возвращает результат.

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

Если существуют дублирующиеся записи, возвращается первая. Используйте get_values/2, чтобы получить все записи.

Примеры

iex> keyword = [a: 1]
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Keyword.get_lazy(keyword, :a, fun)
1
iex> Keyword.get_lazy(keyword, :b, fun)
13

get_values(keywords, key)

get_values(t(), key()) :: [value()]

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

Примеры

iex> Keyword.get_values([], :a)
[]
iex> Keyword.get_values([a: 1], :a)
[1]
iex> Keyword.get_values([a: 1, a: 2], :a)
[1, 2]

has_key?(keywords, key)

has_key?(t(), key()) :: boolean()

Возвращает, существует ли заданный key в заданных keywords.

Примеры

iex> Keyword.has_key?([a: 1], :a)
true
iex> Keyword.has_key?([a: 1], :b)
false

keys(keywords)

keys(t()) :: [key()]

Возвращает все ключи из списка ключевых слов.

Дублирующиеся ключи появляются дважды в итоговом списке ключей.

Примеры

iex> Keyword.keys(a: 1, b: 2)
[:a, :b]
iex> Keyword.keys(a: 1, b: 2, a: 3)
[:a, :b, :a]

keyword?(term)

keyword?(term()) :: boolean()

Возвращает true если term является списком ключевых слов, иначе возвращает false.

Примеры

iex> Keyword.keyword?([])
true
iex> Keyword.keyword?(a: 1)
true
iex> Keyword.keyword?([{Foo, 1}])
true
iex> Keyword.keyword?([{}])
false
iex> Keyword.keyword?([:key])
false
iex> Keyword.keyword?(%{})
false

merge(keywords1, keywords2)

merge(t(), t()) :: t()

Объединяет два списка ключевых слов в один.

Все ключи, включая дублирующиеся ключи, указанные в keywords2, будут добавлены в keywords1, перезаписывая любые существующие.

Порядок ключей в возвращаемом ключевом слове не гарантируется.

Примеры

iex> Keyword.merge([a: 1, b: 2], [a: 3, d: 4])
[b: 2, a: 3, d: 4]

iex> Keyword.merge([a: 1, b: 2], [a: 3, d: 4, a: 5])
[b: 2, a: 3, d: 4, a: 5]

iex> Keyword.merge([a: 1], [2, 3])
** (ArgumentError) expected a keyword list as the second argument, got: [2, 3]

merge(keywords1, keywords2, fun)

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

Объединяет два списка ключевых слов в один.

Все ключи, включая дублирующиеся ключи, указанные в keywords2, будут добавлены в keywords1. Указанная функция будет вызвана для решения конфликтов.

Если у keywords2 есть дублирующиеся ключи, указанная функция будет вызвана для каждой соответствующей пары в keywords1.

Порядок ключей в возвращаемом ключевом слове не гарантируется.

Примеры

iex> Keyword.merge([a: 1, b: 2], [a: 3, d: 4], fn _k, v1, v2 ->
...>   v1 + v2
...> end)
[b: 2, a: 4, d: 4]

iex> Keyword.merge([a: 1, b: 2], [a: 3, d: 4, a: 5], fn :a, v1, v2 ->
...>   v1 + v2
...> end)
[b: 2, a: 4, d: 4, a: 5]

iex> Keyword.merge([a: 1, b: 2, a: 3], [a: 3, d: 4, a: 5], fn :a, v1, v2 ->
...>   v1 + v2
...> end)
[b: 2, a: 4, d: 4, a: 8]

iex> Keyword.merge([a: 1, b: 2], [:a, :b], fn :a, v1, v2 ->
...>   v1 + v2
...> end)
** (ArgumentError) expected a keyword list as the second argument, got: [:a, :b]

new()

new() :: []

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

Примеры

iex> Keyword.new()
[]

new(pairs)

new(Enum.t()) :: t()

Создает ключевое слово из перечисляемого объекта.

Дублирующиеся записи удаляются, последняя сохраняется. В отличие от Enum.into(enumerable, []), Keyword.new(enumerable) гарантирует, что ключи уникальны.

Примеры

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

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

new(pairs, transform)

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

Создает ключевое слово из перечисляемого объекта с помощью функции преобразования.

Дублирующиеся записи удаляются, последняя сохраняется. В отличие от Enum.into(enumerable, [], fun), Keyword.new(enumerable, fun) гарантирует, что ключи уникальны.

Примеры

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

pop(keywords, key, default \\ nil)

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

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

Все дублирующиеся ключи удаляются. См. pop_first/3 для удаления только первой записи.

Примеры

iex> Keyword.pop([a: 1], :a)
{1, []}
iex> Keyword.pop([a: 1], :b)
{nil, [a: 1]}
iex> Keyword.pop([a: 1], :b, 3)
{3, [a: 1]}
iex> Keyword.pop([a: 1, a: 2], :a)
{1, []}

pop_first(keywords, key, default \\ nil)

pop_first(t(), key(), value()) :: {value(), t()}

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

Дублирующиеся ключи не удаляются.

Примеры

iex> Keyword.pop_first([a: 1], :a)
{1, []}
iex> Keyword.pop_first([a: 1], :b)
{nil, [a: 1]}
iex> Keyword.pop_first([a: 1], :b, 3)
{3, [a: 1]}
iex> Keyword.pop_first([a: 1, a: 2], :a)
{1, [a: 2]}

pop_lazy(keywords, key, fun)

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

Лениво возвращает и удаляет все значения, связанные с key в списке ключевых слов.

Все дублирующиеся ключи удаляются. См. pop_first/3 для удаления только первой записи.

Примеры

iex> keyword = [a: 1]
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Keyword.pop_lazy(keyword, :a, fun)
{1, []}
iex> Keyword.pop_lazy(keyword, :b, fun)
{13, [a: 1]}

put(keywords, key, value)

put(t(), key(), value()) :: t()

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

Если ранее хранилось значение, все записи удаляются, и значение перезаписывается.

Примеры

iex> Keyword.put([a: 1], :b, 2)
[b: 2, a: 1]
iex> Keyword.put([a: 1, b: 2], :a, 3)
[a: 3, b: 2]
iex> Keyword.put([a: 1, b: 2, a: 4], :a, 3)
[a: 3, b: 2]

put_new(keywords, key, value)

put_new(t(), key(), value()) :: t()

Добавляет указанное value под key, только если запись key еще не существует.

Примеры

iex> Keyword.put_new([a: 1], :b, 2)
[b: 2, a: 1]
iex> Keyword.put_new([a: 1, b: 2], :a, 3)
[a: 1, b: 2]

put_new_lazy(keywords, key, fun)

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

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

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

Примеры

iex> keyword = [a: 1]
iex> fun = fn ->
...>   # some expensive operation here
...>   3
...> end
iex> Keyword.put_new_lazy(keyword, :a, fun)
[a: 1]
iex> Keyword.put_new_lazy(keyword, :b, fun)
[b: 3, a: 1]

replace!(keywords, key, value)

(since 1.5.0)

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

Изменяет значение, хранящееся под key, на value, но только если запись key уже существует в keywords.

Если key отсутствует в keywords, возникает исключение KeyError.

Примеры

iex> Keyword.replace!([a: 1, b: 2, a: 4], :a, 3)
[a: 3, b: 2]

iex> Keyword.replace!([a: 1], :b, 2)
** (KeyError) key :b not found in: [a: 1]

split(keywords, keys)

split(t(), [key()]) :: {t(), t()}

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

Возвращает кортеж с новым списком и старым списком с удаленными ключами.

Ключи, для которых в списке ключевых слов нет записей, игнорируются.

Записи с дублирующимися ключами попадают в один и тот же список ключевых слов.

Примеры

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

take(keywords, keys)

take(t(), [key()]) :: t()

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

Дублирующиеся ключи сохраняются в новом списке ключевых слов.

Примеры

iex> Keyword.take([a: 1, b: 2, c: 3], [:a, :c, :e])
[a: 1, c: 3]
iex> Keyword.take([a: 1, b: 2, c: 3, a: 5], [:a, :c, :e])
[a: 1, c: 3, a: 5]

to_list(keyword)

to_list(t()) :: t()

Возвращает сам список ключевых слов.

Примеры

iex> Keyword.to_list(a: 1)
[a: 1]

update(keywords, key, initial, fun)

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

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

Если key не существует, вставляет заданное значение initial.

Если есть дублирующиеся ключи, все они удаляются, и обновляется только первый.

Примеры

iex> Keyword.update([a: 1], :a, 13, &(&1 * 2))
[a: 2]
iex> Keyword.update([a: 1, a: 2], :a, 13, &(&1 * 2))
[a: 2]
iex> Keyword.update([a: 1], :b, 11, &(&1 * 2))
[a: 1, b: 11]

update!(keywords, key, fun)

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

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

Если key не существует, генерируется исключение KeyError.

Если есть дублирующиеся ключи, все они удаляются, и обновляется только первый.

Примеры

iex> Keyword.update!([a: 1], :a, &(&1 * 2))
[a: 2]
iex> Keyword.update!([a: 1, a: 2], :a, &(&1 * 2))
[a: 2]

iex> Keyword.update!([a: 1], :b, &(&1 * 2))
** (KeyError) key :b not found in: [a: 1]

values(keywords)

values(t()) :: [value()]

Возвращает все значения из списка ключевых слов.

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

Примеры

iex> Keyword.values(a: 1, b: 2)
[1, 2]
iex> Keyword.values(a: 1, b: 2, a: 3)
[1, 2, 3]