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

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

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

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

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

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

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

Дублированные ключи сохраняются в новом списке ключевых слов.

Примеры

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.

Примеры

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 и возвращает результат.

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

Примеры

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]

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]

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)

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

Возвращает кортеж с новым списком и старым списком с удалёнными ключами.

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

Записи с дублирующими ключами попадают в один и тот же список ключевых слов.

Примеры

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)

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

Дублирующие ключи сохраняются в новом списке ключевых слов.

Примеры

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)

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

Примеры

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]