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

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

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

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

[{: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 и обновляет его. Вызывает исключение, если key отсутствует
get_and_update(keywords, key, fun): Получает значение из key и обновляет его за один проход
get_lazy(keywords, key, fun): Получает значение для определённого key
get_values(keywords, key): Получает все значения для определённого key
has_key?(keywords, key): Возвращает значение, существует ли заданный 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, fun): Обновляет key с помощью заданной функции
update(keywords, key, initial, fun): Обновляет key в keywords с помощью заданной функции
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()) :: value() | no_return()

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

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

Примеры

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

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

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()})) ::
  {get, t()} | no_return()
when get: term()

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

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

Возвращаемое значение — кортеж со значением «получить», возвращённым 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)
** (KeyError) key :b not found in: [a: 1]

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

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, что означает, что текущее значение должно быть удалено из списка ключевых слов и возвращено.

Примеры

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_lazy(keywords, key, fun)

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

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

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

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

Примеры

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

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

Обновляет 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]

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]

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]