Elixir v1.4.5 Keyword View Source
A set of functions for working with keywords.
A keyword is a list of two-element 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 key-value store. However most of the functions in this module
behave exactly as a dictionary so they work similarly to
the functions you would find in the Map
module.
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.
The functions in Keyword do not guarantee any property when
it comes to ordering. However, since a keyword list is simply a
list, all the operations defined in Enum
and List
can be
applied too, especially when ordering is required.
Link to this section Summary
Functions
Deletes the entries in the keyword list for a specific key
Deletes the entries in the keyword list for a key
with value
Deletes the first entry in the keyword list for a specific key
Drops the given keys from the keyword list
Checks if two keywords are equal
Fetches the value for a specific key
and returns it in a tuple
Fetches the value for specific key
Gets the value for a specific key
Gets the value from key
and updates it, all in one pass
Gets the value from key
and updates it. Raises if there is no key
Gets the value for a specific key
Gets all values for a specific key
Returns whether a given key
exists in the given keywords
Returns all keys from the keyword list
Returns true
if term
is a keyword list; otherwise returns false
Merges two keyword lists into one
Merges two keyword lists into one
Returns an empty keyword list, i.e. an empty list
Creates a keyword from an enumerable
Creates a keyword from an enumerable via the transformation function
Returns and removes all values associated with key
in the keyword list
Returns and removes the first value associated with key
in the keyword list
Lazily returns and removes all values associated with key
in the keyword list
Puts the given value
under key
Puts the given value
under key
unless the entry key
already exists
Evaluates fun
and puts the result under key
in keyword list unless key
is already present
Takes all entries corresponding to the given keys and extracts them into a separate keyword list
Takes all entries corresponding to the given keys and returns them in a new keyword list
Returns the keyword list itself
Updates the key
in keywords
with the given function
Updates the key
with the given function
Returns all values from the keyword list
Link to this section Types
Link to this section Functions
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([a: 1], :a, 5)
[a: 1]
iex> Keyword.delete([a: 1], :b, 5)
[a: 1]
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> 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]
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
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
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)
nil
iex> Keyword.get([a: 1], :a)
1
iex> Keyword.get([a: 1], :b)
nil
iex> Keyword.get([a: 1], :b, 3)
3
With duplicated keys:
iex> Keyword.get([a: 1, a: 2], :a, 3)
1
iex> Keyword.get([a: 1, a: 2], :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-element 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 fun
may also
return :pop
, implying the current value shall be removed from the
keyword list and returned.
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!"]}
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]}
Gets the value from key
and updates it. Raises if there is no key
.
This fun
argument receives the value of key
and must return a
two-element 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!"]}
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, []}
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 setup and teardown 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
...> 13
...> end
iex> Keyword.get_lazy(keyword, :a, fun)
1
iex> Keyword.get_lazy(keyword, :b, fun)
13
Gets all values for a specific key
.
Examples
iex> Keyword.get_values([], :a)
[]
iex> Keyword.get_values([a: 1], :a)
[1]
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
.
Examples
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
Merges two keyword lists into one.
All keys, including duplicated keys, given in keywords2
will be added
to keywords1
, overriding any existing one.
There are no guarantees about the order of keys in the returned keyword.
Examples
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]
Merges two keyword lists into one.
All keys, including duplicated keys, given in keywords2
will be added
to keywords1
. The given function will be invoked to solve conflicts.
If keywords2
has duplicate keys, the given function will be invoked
for each matching pair in keywords1
.
There are no guarantees about the order of keys in the returned keyword.
Examples
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]
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}])
[b: 1, a: 2]
iex> Keyword.new([{:a, 1}, {:a, 2}, {:a, 3}])
[a: 3]
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)
[a: :a, b: :b]
Returns and removes all values associated with key
in the keyword list.
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 and removes the first value associated with key
in the keyword list.
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]}
Lazily returns and removes all values associated with key
in the keyword list.
This is useful if the default value is very expensive to calculate or generally difficult to setup and teardown 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
...> 13
...> end
iex> Keyword.pop_lazy(keyword, :a, fun)
{1, []}
iex> Keyword.pop_lazy(keyword, :b, fun)
{13, [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)
[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]
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 setup and teardown 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 entries in the keyword list are ignored.
Entries with duplicated keys end up in the same keyword list.
Examples
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]}
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> 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]
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, a: 2], :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, a: 2], :a, &(&1 * 2))
[a: 2]
iex> Keyword.update!([a: 1], :b, &(&1 * 2))
** (KeyError) key :b not found in: [a: 1]