keyword (ex_stdlib v0.3.0)
View SourceA keyword list is a list of two-element tuples where the first element is an atom (the key) and the second element is any term (the value).
Keyword lists provide a convenient way to associate keys with values and are commonly used for options and configuration parameters.
This module provides functions for working with keyword lists, following the semantics of Elixir's Keyword module. Keys may appear more than once: getters return the first occurrence, while functions that set a key (put/3, replace/3, update/4...) leave a single entry for it.
Where Elixir uses nil for a missing value, this module uses undefined. Elixir's raising (!) variants are either provided under a different arity (update/3, fetch/3) or left out.
Examples:
Options = [{port, 8080}, {host, "localhost"}, {ssl, true}],
8080 = keyword:get(Options, port, 3000),
[{timeout, 5000} | Options] = keyword:put(Options, timeout, 5000),
{ok, [{port, 80}, {host, "a"}]} = keyword:validate([{host, "a"}], [host, {port, 80}]).Summary
Functions
Deletes all entries with the given key.
Deletes the first entry with the given key.
Drops all entries with the given keys.
Checks if two keyword lists contain the same keys with the same values, regardless of order.
Fetches the first value for the given key, as {ok, Value} or error.
Fetches the first value for the given key, calling error(ErrorReason) if it is missing.
Keeps the entries for which Fun({Key, Value}) returns true.
Builds a keyword list from the given keys, all with the same value.
Gets the first value associated with the given key, or undefined.
Gets the first value associated with the given key, or Default.
Gets the value under the given key and updates it, in one pass.
Gets the first value associated with the given key. If the key is missing, Fun is called and its result returned. Useful when the default is expensive to compute.
Gets all values associated with the given key, in order.
Checks if the given key exists in the keyword list.
Intersects two keyword lists, keeping the keys of the first list that are also in the second, with the values of the second list.
Intersects two keyword lists, resolving values with Fun(Key, Value1, Value2).
Returns all keys, in order, including duplicates.
Checks if the given term is a keyword list.
Merges two keyword lists into one.
Merges two keyword lists, resolving conflicts with Fun.
Creates a new empty keyword list.
Creates a keyword list from a list of pairs, removing duplicated keys (the last one prevails). For compatibility, bare atoms are accepted and get the value nil (see from_keys/2).
Creates a keyword list from a list, applying Fun to each element to get a {Key, Value} pair. Duplicated keys are removed (the last one prevails).
Returns the first value for the given key and removes all its entries, or {undefined, Keywords} if the key is missing.
Returns the first value for the given key and removes all its entries, or {Default, Keywords} if the key is missing.
Returns the first value for the given key and removes only that entry, or error if the key is missing.
Returns the first value for the given key and removes only that entry, or {Default, Keywords} if the key is missing.
Like pop/3, but the default is computed by Fun only when the key is missing.
Returns all values for the given key and removes all its entries.
Puts the given value under the given key.
Puts the given value under the given key, unless the key already exists.
Like put_new/3, but the value is computed by Fun only if the key does not exist.
Removes the entries for which Fun({Key, Value}) returns true.
Puts a value under the given key only if the key already exists.
Like replace/3, but the new value is computed by applying Fun to the current value.
Splits the keyword list into {Taken, Rest}, where Taken holds the entries with the given keys.
Splits the keyword list into {True, False} according to Fun, which receives each {Key, Value} pair.
Takes all entries with the given keys, in their original order.
Returns the keyword list itself.
Updates the value under the given key by applying Fun to it.
Updates the value under the given key by applying Fun to it.
Ensures the keyword list only has the keys given in Values.
Returns all values, in order.
Types
Functions
Deletes all entries with the given key.
Deletes the first entry with the given key.
Drops all entries with the given keys.
Checks if two keyword lists contain the same keys with the same values, regardless of order.
Fetches the first value for the given key, as {ok, Value} or error.
Fetches the first value for the given key, calling error(ErrorReason) if it is missing.
Keeps the entries for which Fun({Key, Value}) returns true.
Builds a keyword list from the given keys, all with the same value.
Gets the first value associated with the given key, or undefined.
Gets the first value associated with the given key, or Default.
-spec get_and_update(keyword(), key(), fun((value() | undefined) -> {term(), value()} | pop)) -> {term(), keyword()}.
Gets the value under the given key and updates it, in one pass.
Fun receives the current value (or undefined if the key is missing) and returns either {Get, NewValue} or pop. With {Get, NewValue}, the result is {Get, NewKeywords} where the first entry is updated in place (or {Key, NewValue} is prepended if the key was missing) and other entries for the key are removed. With pop, the result is {CurrentValue, KeywordsWithoutKey}.
Gets the first value associated with the given key. If the key is missing, Fun is called and its result returned. Useful when the default is expensive to compute.
Gets all values associated with the given key, in order.
Checks if the given key exists in the keyword list.
Intersects two keyword lists, keeping the keys of the first list that are also in the second, with the values of the second list.
Intersects two keyword lists, resolving values with Fun(Key, Value1, Value2).
Returns all keys, in order, including duplicates.
Checks if the given term is a keyword list.
Merges two keyword lists into one.
Entries of the first list whose key appears in the second list are removed, then the second list is appended. Duplicate keys within the second list are kept.
[{b, 2}, {a, 3}, {d, 4}] = keyword:merge([{a, 1}, {b, 2}], [{a, 3}, {d, 4}]).Merges two keyword lists, resolving conflicts with Fun.
For each key of the second list that exists in the first one, Fun(Key, Value1, Value2) gives the merged value.
-spec new() -> keyword().
Creates a new empty keyword list.
Creates a keyword list from a list of pairs, removing duplicated keys (the last one prevails). For compatibility, bare atoms are accepted and get the value nil (see from_keys/2).
Creates a keyword list from a list, applying Fun to each element to get a {Key, Value} pair. Duplicated keys are removed (the last one prevails).
Returns the first value for the given key and removes all its entries, or {undefined, Keywords} if the key is missing.
Returns the first value for the given key and removes all its entries, or {Default, Keywords} if the key is missing.
Returns the first value for the given key and removes only that entry, or error if the key is missing.
Returns the first value for the given key and removes only that entry, or {Default, Keywords} if the key is missing.
Like pop/3, but the default is computed by Fun only when the key is missing.
Returns all values for the given key and removes all its entries.
Puts the given value under the given key.
Any existing entries for the key are removed and the new entry is added to the front of the list.
Puts the given value under the given key, unless the key already exists.
Like put_new/3, but the value is computed by Fun only if the key does not exist.
Removes the entries for which Fun({Key, Value}) returns true.
Puts a value under the given key only if the key already exists.
The first entry is replaced in place and any other entries for the key are removed. If the key does not exist, the list is returned unchanged.
Like replace/3, but the new value is computed by applying Fun to the current value.
Splits the keyword list into {Taken, Rest}, where Taken holds the entries with the given keys.
Splits the keyword list into {True, False} according to Fun, which receives each {Key, Value} pair.
Takes all entries with the given keys, in their original order.
Returns the keyword list itself.
Updates the value under the given key by applying Fun to it.
Other entries for the key are removed. Raises {badkey, Key} if the key does not exist (Elixir's update!/3).
Updates the value under the given key by applying Fun to it.
Other entries for the key are removed. If the key does not exist, {Key, Default} is appended to the end of the list (Fun is not called).
Ensures the keyword list only has the keys given in Values.
Values is a list of allowed keys, either bare atoms or {Key, Default} tuples. Returns {ok, Keywords} with the defaults of missing keys added, or {error, BadKeys} listing the keys that are not allowed, or that are given more than once while declared at most once in Values.
{ok, [{two, 2}, {one, 1}]} = keyword:validate([{one, 1}], [one, {two, 2}]),
{error, [three]} = keyword:validate([{three, 3}], [one, two]).Returns all values, in order.