v1.9.4

A keyword list 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.

For example, the following is a keyword list:

[{:exit_on_close,true},{:active,:once},{:packet_size,1024}]

Elixir provides a special and more concise syntax for keyword lists
that looks like this:

[exit_on_close:true,active::once,packet_size:1024]

This is also the syntax that Elixir uses to inspect keyword lists:

iex> [{:active,:once}][active::once]

The two syntaxes are completely equivalent. Like atoms, keywords
must be composed of Unicode characters such as letters, numbers,
underscore, and @. If the keyword has a character that does not
belong to the category above, such as spaces, you can wrap it in
quotes:

iex> ["exit on close":true]["exit on close":true]

Wrapping a keyword in quotes does not make it a string. Keywords are
always atoms. If you use quotes when all characters are a valid part
of a keyword without quotes, Elixir will warn.

Note that when keyword lists are passed as the last argument to a function,
if the short-hand syntax is used then the square brackets around the keyword list
can be omitted as well. For example, the following:

String.split("1-0","-",trim:true,parts:2)

is equivalent to:

String.split("1-0","-",[trim:true,parts:2])

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.
Note that operations that require keys to be found in the keyword
list (like Keyword.get/3) need to traverse the list in order
to find keys, so these operations may be slower than their map
counterparts.

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.

Most of the functions in this module work in linear time. This means
that, the time it takes to perform an operation grows at the same
rate as the length of the list.

get_and_update(keywords, key, fun)

Specs

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.

get_and_update!(keywords, key, fun)

Specs

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

pop(keywords, key, default \\ nil)

Specs

Returns the first value for key and removes all associated entries in the keyword list.

It returns a tuple where the first element is the first value for key and the
second element is a keyword list with all entries associated with key removed.
If the key is not present in the keyword list, {default, keyword_list} is
returned.

If you don't want to remove all the entries associated with key use pop_first/3
instead, that function will remove only the first entry.