Proplist
A proplist is a list of tuples where the first element of the tuple is a binary and the second element can be any value.
A proplist may have duplicated props 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, Proplist.get/3 will get the first entry matching
the given prop, regardless if duplicated entries exist.
Similarly, Proplist.put/3 and Proplist.delete/3 ensure all
duplicated entries for a given prop are removed when invoked.
A handful of functions exist to handle duplicated props, in
particular, Enum.into/2 allows creating new proplist without
removing duplicated props, get_values/2 returns all values for
a given prop and delete_first/2 deletes just one of the existing
entries.
Since a proplist list is simply a list, all the operations defined
in Enum and List can be applied.
Summary
| delete(proplist, prop) | Deletes the entries in the proplist list for a specific |
| delete(proplist, prop, value) | Deletes the entries in the proplist list for a |
| delete_first(proplist, prop) | Deletes the first entry in the proplist list for a specific |
| drop(proplist, props) | Drops the given props from the proplist list |
| equal?(left, right) | Checks if two proplists are equal |
| fetch!(proplist, prop) | Fetches the value for specific |
| fetch(proplist, prop) | Fetches the value for a specific |
| get(proplist, prop, default \\ nil) | Gets the value for a specific |
| get_values(proplist, prop) | Gets all values for a specific |
| has_prop?(proplist, prop) | Returns whether a given |
| merge(d1, d2) | Merges two proplist lists into one |
| merge(d1, d2, fun) | Merges two proplist lists into one |
| new() | Returns an empty property list, i.e. an empty list |
| new(pairs) | Creates a proplist from an enumerable |
| new(pairs, transform) | Creates a proplist from an enumerable via the transformation function |
| pop(proplist, prop, default \\ nil) | Returns the first value associated with |
| pop_first(proplist, prop, default \\ nil) | Returns the first value associated with |
| proplist?(arg1) | Checks if the given argument is a proplist list or not |
| props(proplist) | Returns all props from the proplist list |
| put(proplist, prop, value) | Puts the given |
| put_new(proplist, prop, value) | Puts the given |
| split(proplist, props) | Takes all entries corresponding to the given props and extracts them into a separate proplist list |
| take(proplist, props) | Takes all entries corresponding to the given props and returns them in a new proplist list |
| update!(proplist, prop, fun) | Updates the |
| update(list1, prop, initial, fun) | Updates the |
| values(proplist) | Returns all values from the proplist list |
Types
prop :: binary
value :: any
Functions
Specs:
Deletes the entries in the proplist list for a specific prop.
If the prop does not exist, returns the proplist list unchanged.
Use delete_first/2 to delete just the first entry in case of
duplicated props.
Examples
iex> Proplist.delete([{"a", 1}, {"b", 2}], "a")
[{"b", 2}]
iex> Proplist.delete([{"a", 1}, {"b", 2}, {"a", 3}], "a")
[{"b", 2}]
iex> Proplist.delete([{"b", 2}], "a")
[{"b", 2}]Specs:
Deletes the entries in the proplist list for a prop with value.
If no prop with value exists, returns the proplist list unchanged.
Examples
iex> Proplist.delete([{"a", 1}, {"b", 2}], "a", 1)
[{"b", 2}]
iex> Proplist.delete([{"a", 1}, {"b", 2}, {"a", 3}], "a", 3)
[{"a", 1}, {"b", 2}]
iex> Proplist.delete([{"b", 2}], "a", 5)
[{"b", 2}]Specs:
Deletes the first entry in the proplist list for a specific prop.
If the prop does not exist, returns the proplist list unchanged.
Examples
iex> Proplist.delete_first([{"a", 1}, {"b", 2}, {"a", 3}], "a")
[{"b", 2}, {"a", 3}]
iex> Proplist.delete_first([{"b", 2}], "a")
[{"b", 2}]Drops the given props from the proplist list.
Duplicated props are preserved in the new proplist list.
Examples
iex> d = [{"a", 1}, {"b", 2}, {"c", 3}, {"d", 4}]
iex> Proplist.drop(d, ["b", "d"])
[{"a", 1}, {"c", 3}]
iex> d = [{"a", 1}, {"b", 2}, {"c", 3}, {"d", 4}, {"e", 5}]
iex> Proplist.drop(d, ["b", "d"])
[{"a", 1}, {"c", 3}, {"e", 5}]Specs:
Checks if two proplists are equal.
Two proplists are considered to be equal if they contain the same props and those props contain the same values.
Examples
iex> Proplist.equal?([{"a", 1}, {"b", 2}], [{"b", 2}, {"a", 1}])
trueSpecs:
Fetches the value for a specific prop and returns it in a tuple.
If the prop does not exist, returns :error.
Examples
iex> Proplist.fetch([{"a", 1}], "a")
{:ok, 1}
iex> Proplist.fetch([{"a", 1}], "b")
:errorSpecs:
Fetches the value for specific prop.
If prop does not exist, a KeyError is raised.
Examples
iex> Proplist.fetch!([{"a", 1}], "a")
1
iex> Proplist.fetch!([{"a", 1}], "b")
** (KeyError) key "b" not found in: [{"a", 1}]Specs:
Gets the value for a specific prop.
If prop 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> Proplist.get([{"a", 1}], "a")
1
iex> Proplist.get([{"a", 1}], "b")
nil
iex> Proplist.get([{"a", 1}], "b", 3)
3Specs:
Gets all values for a specific prop.
Examples
iex> Proplist.get_values([{"a", 1}, {"a", 2}], "a")
[1,2]Specs:
Returns whether a given prop exists in the given proplist.
Examples
iex> Proplist.has_prop?([{"a", 1}], "a")
true
iex> Proplist.has_prop?([{"a", 1}], "b")
falseSpecs:
Merges two proplist lists into one.
If they have duplicated props, the one given in the second argument wins.
Examples
iex> Proplist.merge([{"a", 1}, {"b", 2}], [{"a", 3}, {"d", 4}]) |> Enum.sort
[{"a", 3}, {"b", 2}, {"d", 4}]Specs:
Merges two proplist lists into one.
If they have duplicated props, the given function is invoked to solve conflicts.
Examples
iex> Proplist.merge([{"a", 1}, {"b", 2}], [{"a", 3}, {"d", 4}], fn (_k, v1, v2) ->
...> v1 + v2
...> end)
[{"a", 4}, {"b", 2}, {"d", 4}]Specs:
- new :: t
Returns an empty property list, i.e. an empty list.
Specs:
Creates a proplist from an enumerable.
Duplicated entries are removed, the latest one prevails.
Unlike Enum.into(enumerable, []),
Proplist.new(enumerable) guarantees the props are unique.
Examples
iex> Proplist.new([{"b", 1}, {"a", 2}])
[{"a", 2}, {"b", 1}]Creates a proplist from an enumerable via the transformation function.
Duplicated entries are removed, the latest one prevails.
Unlike Enum.into(enumerable, [], fun),
Proplist.new(enumerable, fun) guarantees the props are unique.
Examples
iex> Proplist.new(["a", "b"], fn (x) -> {x, x} end) |> Enum.sort
[{"a", "a"}, {"b", "b"}]Returns the first value associated with prop in the proplist
list as well as the proplist list without prop.
All duplicated props are removed. See pop_first/3 for
removing only the first entry.
Examples
iex> Proplist.pop [{"a", 1}], "a"
{1,[]}
iex> Proplist.pop [{"a", 1}], "b"
{nil,[{"a", 1}]}
iex> Proplist.pop [{"a", 1}], "b", 3
{3,[{"a", 1}]}
iex> Proplist.pop [{"a", 1}], "b", 3
{3,[{"a", 1}]}
iex> Proplist.pop [{"a", 1}, {"a", 2}], "a"
{1,[]}Returns the first value associated with prop in the proplist
list as well as the proplist list without that particular occurrence
of prop.
Duplicated props are not removed.
Examples
iex> Proplist.pop_first [{"a", 1}], "a"
{1,[]}
iex> Proplist.pop_first [{"a", 1}], "b"
{nil,[{"a", 1}]}
iex> Proplist.pop_first [{"a", 1}], "b", 3
{3,[{"a", 1}]}
iex> Proplist.pop_first [{"a", 1}], "b", 3
{3,[{"a", 1}]}
iex> Proplist.pop_first [{"a", 1}, {"a", 2}], "a"
{1,[{"a", 2}]}Specs:
- proplist?(term) :: boolean
Checks if the given argument is a proplist list or not.
Specs:
Returns all props from the proplist list.
Duplicated props appear duplicated in the final list of props.
Examples
iex> Proplist.props([{"a", 1}, {"b", 2}])
["a", "b"]
iex> Proplist.props([{"a", 1}, {"b", 2}, {"a", 3}])
["a", "b", "a"]Specs:
Puts the given value under prop.
If a previous value is already stored, all entries are removed and the value is overridden.
Examples
iex> Proplist.put([{"a", 1}, {"b", 2}], "a", 3)
[{"a", 3}, {"b", 2}]
iex> Proplist.put([{"a", 1}, {"b", 2}, {"a", 4}], "a", 3)
[{"a", 3}, {"b", 2}]Specs:
Puts the given value under prop unless the entry prop
already exists.
Examples
iex> Proplist.put_new([{"a", 1}], "b", 2)
[{"b", 2}, {"a", 1}]
iex> Proplist.put_new([{"a", 1}, {"b", 2}], "a", 3)
[{"a", 1}, {"b", 2}]Takes all entries corresponding to the given props and extracts them into a separate proplist list.
Returns a tuple with the new list and the old list with removed props.
Keys for which there are no entires in the proplist list are ignored.
Entries with duplicated props end up in the same proplist list.
Examples
iex> d = [{"a", 1}, {"b", 2}, {"c", 3}, {"d", 4}]
iex> Proplist.split(d, ["a", "c", "e"])
{[{"a", 1}, {"c", 3}], [{"b", 2}, {"d", 4}]}
iex> d = [{"a", 1}, {"b", 2}, {"c", 3}, {"d", 4}, {"e", 5}]
iex> Proplist.split(d, ["a", "c", "e"])
{[{"a", 1}, {"c", 3}, {"e", 5}], [{"b", 2}, {"d", 4}]}Takes all entries corresponding to the given props and returns them in a new proplist list.
Duplicated props are preserved in the new proplist list.
Examples
iex> d = [{"a", 1}, {"b", 2}, {"c", 3}, {"d", 4}]
iex> Proplist.take(d, ["a", "c", "e"])
[{"a", 1}, {"c", 3}]
iex> d = [{"a", 1}, {"b", 2}, {"c", 3}, {"d", 4}, {"e", 5}]
iex> Proplist.take(d, ["a", "c", "e"])
[{"a", 1}, {"c", 3}, {"e", 5}]Specs:
Updates the prop with the given function.
If the prop does not exist, inserts the given initial value.
If there are duplicated props, they are all removed and only the first one is updated.
Examples
iex> Proplist.update([{"a", 1}], "a", 13, &(&1 * 2))
[{"a", 2}]
iex> Proplist.update([{"a", 1}], "b", 11, &(&1 * 2))
[{"a", 1}, {"b", 11}]Specs:
Updates the prop with the given function.
If the prop does not exist, raises KeyError.
If there are duplicated props, they are all removed and only the first one is updated.
Examples
iex> Proplist.update!([{"a", 1}], "a", &(&1 * 2))
[{"a", 2}]
iex> Proplist.update!([{"a", 1}], "b", &(&1 * 2))
** (KeyError) key "b" not found in: [{"a", 1}]Specs:
Returns all values from the proplist list.
Examples
iex> Proplist.values([{"a", 1}, {"b", 2}])
[1,2]