Spec-Zone.ru › Elixir 1.15

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

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

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

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

Примеры

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

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

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

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

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

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

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]

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

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]

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]

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.15.4/Keyword.html

Spec-Zone.ru

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