@spec 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]

@spec 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]

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

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

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

Примеры

iex> Keyword.drop([a: 1, a: 2], [:a])
[]
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]

@spec 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

Сравнение значений выполняется с помощью ===/3, что означает, что целые числа не эквивалентны числам с плавающей точкой:

iex> Keyword.equal?([a: 1.0], [a: 1])
false

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

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

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

Примеры

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

@spec 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]

@spec filter(t(), ({key(), value()} -> as_boolean(term()))) :: t()

Возвращает список ключевых слов, содержащий только записи из keywords, для которых функция fun возвращает истинное значение.

См. также reject/2, которая отбрасывает все записи, где функция возвращает истинное значение.

Примеры

iex> Keyword.filter([one: 1, two: 2, three: 3], fn {_key, val} -> rem(val, 2) == 1 end)
[one: 1, three: 3]

@spec from_keys([key()], value()) :: t(value())

Создает ключевое слово из заданных keys и фиксированного value.

Примеры

iex> Keyword.from_keys([:foo, :bar, :baz], :atom)
[foo: :atom, bar: :atom, baz: :atom]

@spec 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

@spec get_and_update(
  t(),
  key(),
  (value() | nil -> {current_value, new_value :: value()} | :pop)
) ::
  {current_value, new_keywords :: t()}
when current_value: value()

Получает значение из 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: 2], :a, fn number ->
...>   {2 * number, 3 * number}
...> end)
{4, [a: 6]}

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]}

@spec get_and_update!(
  t(),
  key(),
  (value() | nil -> {current_value, new_value :: value()} | :pop)
) ::
  {current_value, new_keywords :: t()}
when current_value: value()

Получает значение под 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, []}

@spec 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

@spec 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]

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

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

Примеры

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

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

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

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

Примеры

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

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

iex> Keyword.keys([{:a, 1}, {"b", 2}, {:c, 3}])
** (ArgumentError) expected a keyword list, but an entry in the list is not a two-element tuple with an atom as its first element, got: {"b", 2}

@spec keyword?(term()) :: boolean()

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

Когда term является списком, он проходит по нему до конца.

Примеры

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

@spec 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]

@spec 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]

@spec new() :: []

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

Примеры

iex> Keyword.new()
[]

@spec new(Enumerable.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]

@spec new(Enumerable.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]

@spec 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, []}

@spec pop!(t(), key()) :: {value(), t()}

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

Эта функция ведет себя как pop/3, но вызывает исключение в случае, если key отсутствует в заданном keywords.

Примеры

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

@spec 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]}

@spec 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]}

@spec pop_values(t(), key()) :: {[value()], t()}

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

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

Если вам не нужно удалять все записи, связанные с key, используйте pop_first/3 вместо этого, что удалит только первую запись.

Примеры

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

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

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

Если значение под 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]

@spec 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]

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

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

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

Примеры

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

@spec reject(t(), ({key(), value()} -> as_boolean(term()))) :: t()

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

См. также filter/2.

Примеры

iex> Keyword.reject([one: 1, two: 2, three: 3], fn {_key, val} -> rem(val, 2) == 1 end)
[two: 2]

@spec replace(t(), key(), value()) :: t()

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

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

Примеры

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

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

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

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

Если key не присутствует в keywords, вызывается исключение KeyError.

Примеры

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

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

@spec replace_lazy(t(), key(), (existing_value :: value() -> new_value :: value())) ::
  t()

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

По сравнению с replace/3, это может быть полезно, когда вычисление значения является дорогостоящим.

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

Примеры

iex> Keyword.replace_lazy([a: 1, b: 2], :a, fn v -> v * 4 end)
[a: 4, b: 2]

iex> Keyword.replace_lazy([a: 2, b: 2, a: 1], :a, fn v -> v * 4 end)
[a: 8, b: 2]

iex> Keyword.replace_lazy([a: 1, b: 2], :c, fn v -> v * 4 end)
[a: 1, b: 2]

@spec 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]}

@spec 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]

@spec to_list(t()) :: t()

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

Примеры

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

@spec update(
  t(),
  key(),
  default :: value(),
  (existing_value :: value() -> new_value :: value())
) :: t()

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

Если ключ key не существует, вставляет заданное значение default. Не пропускает значение default через функцию обновления.

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

Примеры

iex> Keyword.update([a: 1], :a, 13, fn existing_value -> existing_value * 2 end)
[a: 2]

iex> Keyword.update([a: 1, a: 2], :a, 13, fn existing_value -> existing_value * 2 end)
[a: 2]

iex> Keyword.update([a: 1], :b, 11, fn existing_value -> existing_value * 2 end)
[a: 1, b: 11]

@spec update!(t(), key(), (current_value :: value() -> new_value :: value())) :: t()

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

Вызывает исключение KeyError, если ключ key не существует.

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

Примеры

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

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

@spec validate(
  keyword(),
  values :: [atom() | {atom(), term()}]
) :: {:ok, keyword()} | {:error, [atom()]}

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

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

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

См. также: validate!/2.

Примеры

iex> {:ok, result} = Keyword.validate([], [one: 1, two: 2])
iex> Enum.sort(result)
[one: 1, two: 2]

iex> {:ok, result} = Keyword.validate([two: 3], [one: 1, two: 2])
iex> Enum.sort(result)
[one: 1, two: 3]

Если передаются атомы, они поддерживаются в качестве ключей, но не предоставляют значение по умолчанию:

iex> {:ok, result} = Keyword.validate([], [:one, two: 2])
iex> Enum.sort(result)
[two: 2]

iex> {:ok, result} = Keyword.validate([one: 1], [:one, two: 2])
iex> Enum.sort(result)
[one: 1, two: 2]

Передача неизвестных ключей приводит к ошибке:

iex> Keyword.validate([three: 3, four: 4], [one: 1, two: 2])
{:error, [:four, :three]}

Передача одного и того же ключа несколько раз также приводит к ошибке:

iex> Keyword.validate([one: 1, two: 2, one: 1], [:one, :two])
{:error, [:one]}

@spec validate!(
  keyword(),
  values :: [atom() | {atom(), term()}]
) :: keyword()

Аналогично validate/2, но возвращает список ключевых слов или вызывает исключение.

Примеры

iex> Keyword.validate!([], [one: 1, two: 2]) |> Enum.sort()
[one: 1, two: 2]
iex> Keyword.validate!([two: 3], [one: 1, two: 2]) |> Enum.sort()
[one: 1, two: 3]

Если передаются атомы, они поддерживаются в качестве ключей, но не предоставляют значение по умолчанию:

iex> Keyword.validate!([], [:one, two: 2]) |> Enum.sort()
[two: 2]
iex> Keyword.validate!([one: 1], [:one, two: 2]) |> Enum.sort()
[one: 1, two: 2]

Передача неизвестных ключей вызывает исключение:

iex> Keyword.validate!([three: 3], [one: 1, two: 2])
** (ArgumentError) unknown keys [:three] in [three: 3], the allowed keys are: [:one, :two]

Передача одного и того же ключа несколько раз также вызывает исключение:

iex> Keyword.validate!([one: 1, two: 2, one: 1], [:one, :two])
** (ArgumentError) duplicate keys [:one] in [one: 1, two: 2, one: 1]

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

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

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

Примеры

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