Spec-Zone.ru › Elixir 1.16

Источник Ключевое слово

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

Первый элемент этих кортежей известен как ключ, и он должен быть атомом. Второй элемент, известный как значение, может быть любым термином.

Ключевые слова в основном используются для работы с необязательными значениями. Для общего введения в ключевые слова и того, как они сравниваются с картами, см. наше руководство Ключевые слова и карты.

Примеры

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

[{:exit_on_close, true}, {:active, :once}, {:packet_size, 1024}]

Elixir предоставляет специальный и более лаконичный синтаксис для списков ключевых слов:

[exit_on_close: true, active: :once, packet_size: 1024]

Два синтаксиса возвращают точно такое же значение.

Ключ может быть любым атомом, состоящим из букв Unicode, цифр, символа подчеркивания или символа @. Если ключ должен содержать другие символы, такие как пробелы, вы можете заключить его в кавычки:

iex> ["exit on close": true]
["exit on close": true]

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

Дублирование ключей и упорядочение

В списке ключевых слов могут быть дублированные ключи, поэтому это не строго тип данных «ключ-значение». Однако большинство функций в этом модуле работают со структурой «ключ-значение» и ведут себя аналогично функциям, которые вы найдёте в модуле Map. Например, Keyword.get/3 получит первую запись, соответствующую заданному ключу, независимо от того, существуют ли дублированные записи. Аналогично, Keyword.put/3 и Keyword.delete/2 гарантируют удаление всех дублированных записей для данного ключа при вызове. Однако обратите внимание, что операции со списком ключевых слов должны пройтись по всему списку, чтобы найти ключи, поэтому эти операции медленнее, чем их аналоги для карт.

Существует несколько функций для работы с дублированными ключами, например, get_values/2 возвращает все значения для данного ключа, а delete_first/2 удаляет только первую запись из имеющихся.

Несмотря на то, что списки сохраняют порядок, функции в Keyword не гарантируют какой-либо порядок. Например, если вы вызовете Keyword.put(opts, new_key, new_value), нет никакой гарантии, куда new_key будет добавлен (в начало, в конец или в любое другое место).

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

def my_function([some_key: value, another_key: another_value])

будет совпадать

my_function([some_key: :foo, another_key: :bar])

но не будет совпадать

my_function([another_key: :bar, some_key: :foo])

Большинство функций в этом модуле работают за линейное время. Это означает, что время, необходимое для выполнения операции, растет с той же скоростью, что и длина списка.

Синтаксис вызова

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

String.split("1-0", "-", [trim: true, parts: 2])

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

String.split("1-0", "-", trim: true, parts: 2)

Поскольку кортежи, списки и карты обрабатываются аналогично аргументам функций в синтаксисе Elixir, это свойство также доступно и для них:

iex> {1, 2, foo: :bar}
{1, 2, [{:foo, :bar}]}

iex> [1, 2, foo: :bar]
[1, 2, {:foo, :bar}]

iex> %{1 => 2, foo: :bar}
%{1 => 2, :foo => :bar}

Резюме

Типы

key()
t()
t(value)
value()

Функции

delete(keywords, key)

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

delete_first(keywords, key)

Удаляет первую запись в списке ключевых слов под определённым key.

drop(keywords, keys)

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

equal?(left, right)

Проверяет, равны ли два ключевых слова.

fetch(keywords, key)

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

fetch!(keywords, key)

Извлекает значение для указанного key.

filter(keywords, fun)

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

from_keys(keys, value)

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

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!(keywords, key)

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

pop_first(keywords, key, default \\ nil)

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

pop_lazy(keywords, key, fun)

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

pop_values(keywords, key)

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

put(keywords, key, value)

Помещает заданное value под указанный key.

put_new(keywords, key, value)

Помещает заданное value под key, если запись key ещё не существует.

put_new_lazy(keywords, key, fun)

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

reject(keywords, fun)

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

replace(keywords, key, value)

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

replace!(keywords, key, value)

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

replace_lazy(keywords, key, fun)

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

split(keywords, keys)

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

split_with(keywords, fun)

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

take(keywords, keys)

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

to_list(keywords)

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

update(keywords, key, default, fun)

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

update!(keywords, key, fun)

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

validate(keyword, values)

Убеждается, что у данного keyword есть только ключи, указанные в values.

validate!(keyword, values)

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

values(keywords)

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

END_OF_DOCUMENT_MARKER

Типы

key()Source

@type key() :: atom()

t()Source

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

t(value)Source

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

value()Source

@type value() :: any()

Функции

delete(keywords, key)Source

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

delete_first(keywords, key)Source

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

drop(keywords, keys)Source

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

equal?(left, right)Source

@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

fetch(keywords, key)Source

@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

fetch!(keywords, key)Source

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

filter(keywords, fun)Source

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

from_keys(keys, value)Source

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

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

Примеры

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

get(keywords, key, default \\ nil)Source

@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

get_and_update(keywords, key, fun)Source

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

get_and_update!(keywords, key, fun)Source

@spec get_and_update!(
  t(),
  key(),
  (value() -> {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, []}

get_lazy(keywords, key, fun)Source

@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

get_values(keywords, key)Source

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

has_key?(keywords, key)Source

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

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

keyword?(term)Source

@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

merge(keywords1, keywords2)Source

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

merge(keywords1, keywords2, fun)Source

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

new()Source

@spec new() :: []

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

Примеры

iex> Keyword.new()
[]

new(pairs)Source

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

new(pairs, transform)Source

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

pop(keywords, key, default \\ nil)Source

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

pop!(keywords, key)Source

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

pop_first(keywords, key, default \\ nil)Source

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

pop_lazy(keywords, key, fun)Source

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

pop_values(keywords, key)Source

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

put(keywords, key, value)Source

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

put_new(keywords, key, value)Source

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

put_new_lazy(keywords, key, fun)Source

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

reject(keywords, fun)Source

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

replace(keywords, key, value)Source

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

replace!(keywords, key, value)Source

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

replace_lazy(keywords, key, fun)Source

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

split(keywords, keys)Source

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

Извлекает все пары ключ-значение, соответствующие заданным 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]}

split_with(keywords, fun)Source

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

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

Переданная функция fun получает каждую пару {key, value} в keywords в качестве единственного аргумента. Возвращает кортеж с первым списком ключевых слов, содержащим все элементы keywords, для которых применение fun дало истинное значение, и вторым списком ключевых слов со всеми элементами, для которых применение fun дало ложное значение (false или nil).

Примеры

iex> Keyword.split_with([a: 1, b: 2, c: 3], fn {_k, v} -> rem(v, 2) == 0 end)
{[b: 2], [a: 1, c: 3]}

iex> Keyword.split_with([a: 1, b: 2, c: 3, b: 4], fn {_k, v} -> rem(v, 2) == 0 end)
{[b: 2, b: 4], [a: 1, c: 3]}

iex> Keyword.split_with([a: 1, b: 2, c: 3, b: 4], fn {k, v} -> k in [:a, :c] and rem(v, 2) == 0 end)
{[], [a: 1, b: 2, c: 3, b: 4]}

iex> Keyword.split_with([], fn {_k, v} -> rem(v, 2) == 0 end)
{[], []}

take(keywords, keys)Source

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

Извлекает все пары ключ-значение, соответствующие заданным 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(keywords)Source

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

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

Примеры

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

update(keywords, key, default, fun)Source

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

update!(keywords, key, fun)Source

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

validate(keyword, values)Source

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

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

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

Если список ключевых слов содержит только заданные ключи, возвращает {:ok, keyword} с применёнными значениями по умолчанию. В противном случае возвращает {:error, invalid_keys} с недопустимыми ключами.

См. также: 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]}

validate!(keyword, values)Source

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

values(keywords)Source

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

Скачать версию ePub

Сгенерировано с помощью ExDoc (v0.32.2) для языка программирования Elixir

© 2012-2024 The Elixir Team
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.16.3/Keyword.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API