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

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

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

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

[{: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]

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

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, также можно обратиться, особенно когда требуется упорядочивание.

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

Типы

key()

t()

t(value)

value()

Функции

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() | 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]

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()} | 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_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)

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() | 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]

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]