Deletes the entries in the keyword list for a specific key.

If the key does not exist, returns the keyword list unchanged. Use delete_first/2 to delete just the first entry in case of duplicated keys.

Examples

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]

Deletes the entries in the keyword list for a key with value.

If no key with value exists, returns the keyword list unchanged.

Examples

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([b: 2], :a, 5)
[b: 2]

Deletes the first entry in the keyword list for a specific key.

If the key does not exist, returns the keyword list unchanged.

Examples

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

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

Drops the given keys from the keyword list.

Duplicated keys are preserved in the new keyword list.

Examples

iex> d = [a: 1, b: 2, c: 3, d: 4]
iex> Keyword.drop(d, [:b, :d])
[a: 1, c: 3]

iex> d = [a: 1, b: 2, b: 3, c: 3, d: 4, a: 5]
iex> Keyword.drop(d, [:b, :d])
[a: 1, c: 3, a: 5]

Checks if two keywords are equal.

Two keywords are considered to be equal if they contain the same keys and those keys contain the same values.

Examples

iex> Keyword.equal?([a: 1, b: 2], [b: 2, a: 1])
true

Fetches the value for a specific key and returns it in a tuple.

If the key does not exist, returns :error.

Examples

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

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

Fetches the value for specific key.

If key does not exist, a KeyError is raised.

Examples

iex> Keyword.fetch!([a: 1], :a)
1

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

Gets the value for a specific key.

If key does not exist, return the default value (nil if no default value).

If duplicated entries exist, the first one is returned. Use get_values/2 to retrieve all entries.

Examples

iex> Keyword.get([a: 1], :a)
1

iex> Keyword.get([a: 1], :b)
nil

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

Gets the value from key and updates it, all in one pass.

This fun argument receives the value of key (or nil if key is not present) and must return a two-elements tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under key.

The returned value is a tuple with the “get” value returned by fun and a new keyword list with the updated value under key.

Examples

iex> Keyword.get_and_update [a: 1], :a, fn(current_value) ->
...>   {current_value, "new value!"}
...> end
{1, [a: "new value!"]}

Gets the value for a specific key.

If key does not exist, lazily evaluates fun and returns its result.

This is useful if the default value is very expensive to calculate or generally difficult to set-up and tear-down again.

If duplicated entries exist, the first one is returned. Use get_values/2 to retrieve all entries.

Examples

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

Gets all values for a specific key.

Examples

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

Returns whether a given key exists in the given keywords.

Examples

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

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

Returns all keys from the keyword list.

Duplicated keys appear duplicated in the final list of keys.

Examples

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

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

Returns true if term is a keyword list; otherwise returns false.

Merges two keyword lists into one.

If they have duplicated keys, the one given in the second argument wins.

Examples

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

Merges two keyword lists into one.

If they have duplicated keys, the given function is invoked to solve conflicts.

Examples

iex> Keyword.merge([a: 1, b: 2], [a: 3, d: 4], fn (_k, v1, v2) ->
...>  v1 + v2
...> end)
[a: 4, b: 2, d: 4]

Returns an empty keyword list, i.e. an empty list.

Creates a keyword from an enumerable.

Duplicated entries are removed, the latest one prevails. Unlike Enum.into(enumerable, []), Keyword.new(enumerable) guarantees the keys are unique.

Examples

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

Creates a keyword from an enumerable via the transformation function.

Duplicated entries are removed, the latest one prevails. Unlike Enum.into(enumerable, [], fun), Keyword.new(enumerable, fun) guarantees the keys are unique.

Examples

iex> Keyword.new([:a, :b], fn (x) -> {x, x} end)
[b: :b, a: :a]

Returns the first value associated with key in the keyword list as well as the keyword list without key.

All duplicated keys are removed. See pop_first/3 for removing only the first entry.

Examples

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

Returns the first value associated with key in the keyword list as well as the keyword list without that particular occurrence of key.

Duplicated keys are not removed.

Examples

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

Returns the first value associated with key in the keyword list as well as the keyword list without key.

This is useful if the default value is very expensive to calculate or generally difficult to set-up and tear-down again.

All duplicated keys are removed. See pop_first/3 for removing only the first entry.

Examples

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

Puts the given value under key.

If a previous value is already stored, all entries are removed and the value is overridden.

Examples

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]

Puts the given value under key unless the entry key already exists.

Examples

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]

Evaluates fun and puts the result under key in keyword list unless key is already present.

This is useful if the value is very expensive to calculate or generally difficult to set-up and tear-down again.

Examples

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]

Takes all entries corresponding to the given keys and extracts them into a separate keyword list.

Returns a tuple with the new list and the old list with removed keys.

Keys for which there are no entires in the keyword list are ignored.

Entries with duplicated keys end up in the same keyword list.

Examples

iex> d = [a: 1, b: 2, c: 3, d: 4]
iex> Keyword.split(d, [:a, :c, :e])
{[a: 1, c: 3], [b: 2, d: 4]}

iex> d = [a: 1, b: 2, c: 3, d: 4, a: 5]
iex> Keyword.split(d, [:a, :c, :e])
{[a: 1, c: 3, a: 5], [b: 2, d: 4]}

Takes all entries corresponding to the given keys and returns them in a new keyword list.

Duplicated keys are preserved in the new keyword list.

Examples

iex> d = [a: 1, b: 2, c: 3, d: 4]
iex> Keyword.take(d, [:a, :c, :e])
[a: 1, c: 3]

iex> d = [a: 1, b: 2, c: 3, d: 4, a: 5]
iex> Keyword.take(d, [:a, :c, :e])
[a: 1, c: 3, a: 5]

Updates the key in keywords with the given function.

If the key does not exist, inserts the given initial value.

If there are duplicated keys, they are all removed and only the first one is updated.

Examples

iex> Keyword.update([a: 1], :a, 13, &(&1 * 2))
[a: 2]

iex> Keyword.update([a: 1], :b, 11, &(&1 * 2))
[a: 1, b: 11]

Updates the key with the given function.

If the key does not exist, raises KeyError.

If there are duplicated keys, they are all removed and only the first one is updated.

Examples

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

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

Returns all values from the keyword list.

Examples

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