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

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

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

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

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

Существует несколько функций для обработки дублирующих ключей, в частности, 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)

Возвращает значение, существует ли данный 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 ещё не присутствует

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]

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]