Keyword

Introduction #

A keyword is a list of tuples where the first element of the tuple is an atom and the second element can be any value.

A keyword may have duplicated keys so it is not strictly a dictionary. However most of the functions in this module behave exactly as a dictionary and mimic the API defined by the Dict behaviour.

For example, Keyword.get/3 will get the first entry matching the given key, regardless if duplicated entries exist. Similarly, Keyword.put/3 and Keyword.delete/3 ensure all duplicated entries for a given key are removed when invoked.

A handful of functions exist to handle duplicated keys, in particular, Enum.into/2 allows creating new keywords without removing duplicated keys, get_values/2 returns all values for a given key and delete_first/2 deletes just one of the existing entries.

Since a keyword list is simply a list, all the operations defined in Enum and List can be applied.

Source

Types #

key :: atom

value :: any

t :: [{key, value}]

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

Functions #

delete(keywords, key)

(function)

Specs

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]

delete(keywords, key, value)

(function)

Specs

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]

delete_first(keywords, key)

(function)

Specs

  • delete_first(t, key) :: t

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]

drop(keywords, keys)

(function)

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]

equal?(left, right)

(function)

Specs

  • equal?(t, t) :: boolean

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

fetch(keywords, key)

(function)

Specs

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

fetch!(keywords, key)

(function)

Specs

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]

get(keywords, key, default \\ nil)

(function)

Specs

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

get_values(keywords, key)

(function)

Specs

Gets all values for a specific key.

Examples

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

has_key?(keywords, key)

(function)

Specs

  • has_key?(t, key) :: boolean

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

keys(keywords)

(function)

Specs

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]

keyword?(arg1)

(function)

Specs

  • keyword?(term) :: boolean

Checks if the given argument is a keyword list or not.

merge(d1, d2)

(function)

Specs

  • merge(t, t) :: t

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]) |> Enum.sort
[a: 3, b: 2, d: 4]

merge(d1, d2, fun)

(function)

Specs

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]

new()

(function)

Specs

  • new :: t

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

new(pairs)

(function)

Specs

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]

new(pairs, transform)

(function)

Specs

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) |> Enum.sort
[a: :a, b: :b]

pop(keywords, key, default \\ nil)

(function)

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], :b, 3
{3,[a: 1]}

iex> Keyword.pop [a: 1, a: 2], :a
{1,[]}

pop_first(keywords, key, default \\ nil)

(function)

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], :b, 3
{3,[a: 1]}

iex> Keyword.pop_first [a: 1, a: 2], :a
{1,[a: 2]}

put(keywords, key, value)

(function)

Specs

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]

put_new(keywords, key, value)

(function)

Specs

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]

split(keywords, keys)

(function)

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

take(keywords, keys)

(function)

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]

update(list1, key, initial, fun)

(function)

Specs

Updates the key 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]

update!(keywords, key, fun)

(function)

Specs

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]

values(keywords)

(function)

Specs

Returns all values from the keyword list.

Examples

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