Keyword
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
behaves exactly as a dictionary and mimic the API defined
by the Dict behaviour.
For example, Keyword.get will get the first entry matching
the given key, regardless if duplicated entries exist.
Similarly, Keyword.put and Keyword.delete ensure all
duplicated entries for a given key are removed when invoked.
A handful of functions exist to handle duplicated keys, in
particular, from_enum allows creating a new keywords without
removing duplicated keys, get_values returns all values for
a given key and delete_first deletes just one of the existing
entries.
Since a keyword list is simply a list, all the operations defined
in Enum and List can also be applied.
Summary
| delete(keywords, key) | Deletes all entries in the keyword list for a specific |
| delete(keywords, key, value) | Deletes the entry in the keyword list for a |
| delete_first(keywords, key) | Deletes the first entry in the keyword list for a specific |
| drop(dict, keys) | Drops the given keys from the dict. Duplicated keys are preserved in the new keyword list |
| equal?(left, right) | Checks if two keywords are equal. I.e. they contain the same keys and those keys contain the same values |
| fetch!(keywords, key) | Fetches the value for specific |
| fetch(keywords, key) | Fetches the value for a specific |
| from_enum(enum) | Creates a Keyword from an enum. Unlike |
| get(keywords, key, default \\ nil) | Gets the value for a specific |
| get_values(keywords, key) | Gets all values for a specific |
| has_key?(keywords, key) | Returns whether a given |
| keys(keywords) | Returns all keys from the keyword list. Duplicated keys appear duplicated in the final list of keys |
| keyword?(arg1) | Checks if the given argument is a keywords list or not |
| merge(d1, d2) | Merges two keyword lists into one. If they have duplicated entries, the one given as second argument wins |
| merge(d1, d2, fun) | Merges two keyword lists into one. If they have duplicated entries, the given function is invoked to solve conflicts |
| new() | Returns an empty keyword list, i.e. an empty list |
| new(pairs) | Creates a Keyword from an enumerable. Similar to dicts, duplicated entries are removed, the latest one prevails |
| new(pairs, transform) | Creates a Keyword from an enumerable with the help of the transformation function. Duplicated entries are removed, the latest one prevails |
| pop(dict, key, default \\ nil) | Returns the first value associated with |
| pop_first(dict, key, default \\ nil) | Returns the first value associated with |
| put(keywords, key, value) | Puts the given |
| put_new(keywords, key, value) | Puts the given |
| split(dict, keys) | Splits the given keywords in two given the given keys. Duplicated keys are preserved in the split keyword list |
| take(dict, keys) | Takes the given keys from the dict. Duplicated keys are preserved in the new keyword list |
| update!(list1, key, fun) | Updates the |
| update(list1, key, initial, fun) | Updates the |
| values(keywords) | Returns all values from the keyword list |
Functions
Specs:
Deletes all entries in the keyword list for a specific key.
If the key does not exist, returns the keyword list unchanged.
Use delete_first 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]
Specs:
Deletes the entry 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]
Specs:
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 dict. 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, c: 3, d: 4, a: 5]
iex> Keyword.drop(d, [:b, :d])
[a: 1, c: 3, a: 5]
Specs:
Checks if two keywords are equal. I.e. 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
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
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 not found: :b
Specs:
Creates a Keyword from an enum. Unlike Keyword.new
which behaves as a dict, Keyword.from_enum does not remove
duplicated entries.
Specs:
Gets the value for a specific key.
If key does not exist, return 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
Specs:
Gets all values for a specific key.
Examples
iex> Keyword.get_values([a: 1, a: 2], :a)
[1,2]
Specs:
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
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]
Specs:
Merges two keyword lists into one. If they have duplicated entries, the one given as second argument wins.
Examples
iex> Keyword.merge([a: 1, b: 2], [a: 3, d: 4]) |> Enum.sort
[a: 3, b: 2, d: 4]
Specs:
Merges two keyword lists into one. If they have duplicated entries, 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
iex> end)
[a: 4, b: 2, d: 4]
Specs:
Creates a Keyword from an enumerable. Similar to dicts, duplicated entries are removed, the latest one prevails.
Examples
iex> Keyword.new([{:b, 1}, {:a, 2}])
[a: 2, b: 1]
Specs:
Creates a Keyword from an enumerable with the help of the transformation function. Duplicated entries are removed, the latest one prevails.
Examples
iex> Keyword.new([:a, :b], fn (x) -> {x, x} end) |> Enum.sort
[a: :a, b: :b]
Returns the first value associated with key in the keyword
list as well as the keyword list without key.
All duplicated entries 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,[]}
Returns the first value associated with key in the keyword
list as well as the keyword list without that particular ocurrence
of key.
Duplicated entries 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]}
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]
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]
Splits the given keywords in two given the given keys. Duplicated keys are preserved in the split 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 the given keys from the dict. 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]
Specs:
Updates the key with the given function. If the key does
not exist, inserts the given initial value.
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]