Спецификации

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(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(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(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?(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(t(), key()) :: {:ok, value()} | :error

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

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

Примеры

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

Спецификации

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

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

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

Возвращаемое значение представляет собой кортеж со значением "get", возвращаемым 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!(t(), key(), (value() -> {get, value()})) :: {get, t()}
when get: term()

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

Этот fun аргумент получает значение key и должен возвращать кортеж из двух элементов: значение "get" (извлеченное значение, которое может быть обработано перед возвратом) и новое значение для хранения под key.

Возвращаемое значение представляет собой кортеж со значением "get", возвращаемым 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(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(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?(t(), key()) :: boolean()

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

Примеры

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

Спецификации

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

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

Примеры

iex> Keyword.new()
[]

Спецификации

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(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(t(), key(), value()) :: {value(), t()}

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

Возвращает кортеж, где первый элемент — первое значение для key, а второй элемент — список ключевых слов со всеми записями, связанными с key, удаленными. Если key отсутствует в списке ключевых слов, возвращается {default, keyword_list}.

Если вы не хотите удалять все записи, связанные с 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(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(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(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(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(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!(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(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(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(t()) :: t()

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

Примеры

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

Спецификации

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!(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(t()) :: [value()]

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

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

Примеры

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