Proplist v1.1.0 → Overview → Proplist

Proplist

Summary
Types
Functions

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.

Source

Summary

delete(proplist, prop)	Deletes the entries in the proplist list for a specific `prop`
delete(proplist, prop, value)	Deletes the entries in the proplist list for a `prop` with `value`
delete_first(proplist, prop)	Deletes the first entry in the proplist list for a specific `prop`
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 `prop`
fetch(proplist, prop)	Fetches the value for a specific `prop` and returns it in a tuple
get(proplist, prop, default \\ nil)	Gets the value for a specific `prop`
get_and_update(proplist, prop, fun)	Gets the value from `prop` and updates it, all in one pass
get_lazy(proplist, prop, fun)	Gets the value for a specific `prop`
get_values(proplist, prop)	Gets all values for a specific `prop`
has_prop?(proplist, prop)	Returns whether a given `prop` exists in the given `proplist`
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 `prop` in the proplist list as well as the proplist list without `prop`
pop_first(proplist, prop, default \\ nil)	Returns the first value associated with `prop` in the proplist list as well as the proplist list without that particular occurrence of `prop`
pop_lazy(proplist, prop, fun)	Returns the first value associated with `prop` in the proplist as well as the proplist without `prop`
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 `value` under `prop`
put_new(proplist, prop, value)	Puts the given `value` under `prop` unless the entry `prop` already exists
put_new_lazy(proplist, prop, fun)	Evaluates `fun` and puts the result under `prop` in proplist unless `prop` is already present
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 `prop` with the given function
update(list, prop, initial, fun)	Updates the `prop` with the given function
values(proplist)	Returns all values from the proplist list

Types

prop :: binary

value :: any

t :: [{prop, value}]

t(value) :: [{prop, value}]

Functions

delete(proplist, prop)

(function) # ↑

Specs:

delete(t, prop) :: t

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}]

Source

delete(proplist, prop, value)

(function) # ↑

Specs:

delete(t, prop, value) :: t

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}]

Source

delete_first(proplist, prop)

(function) # ↑

Specs:

delete_first(t, prop) :: t

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}]

Source

drop(proplist, props)

(function) # ↑

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}]

Source

equal?(left, right)

(function) # ↑

Specs:

equal?(t, t) :: boolean

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}])
true

Source

fetch(proplist, prop)

(function) # ↑

Specs:

fetch(t, prop) :: {:ok, value} | :error

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")
:error

Source

fetch!(proplist, prop)

(function) # ↑

Specs:

fetch!(t, prop) :: value | no_return

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}]

Source

get(proplist, prop, default \\ nil)

(function) # ↑

Specs:

get(t, prop, value) :: value

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)
3

Source

get_and_update(proplist, prop, fun)

(function) # ↑

Specs:

get_and_update(t, prop, (value -> {value, value})) :: {value, t}

Gets the value from prop and updates it, all in one pass.

This fun argument receives the value of prop (or nil if prop is not present) and must return a two-elements tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under prop.

The returned value is a tuple with the “get” value returned by fun and a new proplist with the updated value under prop.

Examples

iex> Proplist.get_and_update [{"a", 1}], "a", fn(current_value) ->
...>   {current_value, current_value + 1}
...> end
{1, [{"a", 2}]}

Source

get_lazy(proplist, prop, fun)

(function) # ↑

Specs:

get_lazy(t, prop, (() -> value)) :: value

Gets the value for a specific prop.

If prop does not exist, lazily evaluates fun and returns its result.

If duplicated entries exist, the first one is returned. Use get_values/2 to retrieve all entries.

Examples

iex> proplist = [{"a", 1}]
iex> fun = fn ->
...>   :result
...> end
iex> Proplist.get_lazy(proplist, "a", fun)
1
iex> Proplist.get_lazy(proplist, "b", fun)
:result

Source

get_values(proplist, prop)

(function) # ↑

Specs:

get_values(t, prop) :: [value]

Gets all values for a specific prop.

Examples

iex> Proplist.get_values([{"a", 1}, {"a", 2}], "a")
[1,2]

Source

has_prop?(proplist, prop)

(function) # ↑

Specs:

has_prop?(t, prop) :: boolean

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")
false

Source

merge(d1, d2)

(function) # ↑

Specs:

merge(t, t) :: t

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}]

Source

merge(d1, d2, fun)

(function) # ↑

Specs:

merge(t, t, (prop, value, value -> value)) :: t

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}]

Source

new()

(function) # ↑

Specs:

new :: t

Returns an empty property list, i.e. an empty list.

Source

new(pairs)

(function) # ↑

Specs:

new(Enum.t) :: t

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}]

Source

new(pairs, transform)

(function) # ↑

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"}]

Source

pop(proplist, prop, default \\ nil)

(function) # ↑

Specs:

pop(t, prop, value) :: {value, t}

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,[]}

Source

pop_first(proplist, prop, default \\ nil)

(function) # ↑

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}]}

Source

pop_lazy(proplist, prop, fun)

(function) # ↑

Specs:

pop_lazy(t, prop, (() -> value)) :: {value, t}

Returns the first value associated with prop in the proplist as well as the proplist without prop.

All duplicated props are removed. See pop_first/3 for removing only the first entry.

Examples

iex> proplist = [{"a", 1}]
iex> fun = fn ->
...>   :result
...> end
iex> Proplist.pop_lazy(proplist, "a", fun)
{1, []}
iex> Proplist.pop_lazy(proplist, "b", fun)
{:result, [{"a", 1}]}

Source

proplist?(arg1)

(function) # ↑

Specs:

proplist?(term) :: boolean

Checks if the given argument is a proplist list or not.

Source

props(proplist)

(function) # ↑

Specs:

props(t) :: [prop]

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"]

Source

put(proplist, prop, value)

(function) # ↑

Specs:

put(t, prop, value) :: t

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}]

Source

put_new(proplist, prop, value)

(function) # ↑

Specs:

put_new(t, prop, value) :: t

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}]

Source

put_new_lazy(proplist, prop, fun)

(function) # ↑

Specs:

put_new_lazy(t, prop, (() -> value)) :: t

Evaluates fun and puts the result under prop in proplist unless prop is already present.

Examples

iex> proplist = [{"a", 1}]
iex> fun = fn ->
...>   3
...> end
iex> Proplist.put_new_lazy(proplist, "a", fun)
[{"a", 1}]
iex> Proplist.put_new_lazy(proplist, "b", fun)
[{"b", 3}, {"a", 1}]

Source

split(proplist, props)

(function) # ↑

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}]}

Source

take(proplist, props)

(function) # ↑

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}]

Source

update(list, prop, initial, fun)

(function) # ↑

Specs:

update(t, prop, value, (value -> value)) :: t

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}]

Source

update!(proplist, prop, fun)

(function) # ↑

Specs:

update!(t, prop, (value -> value)) :: t | no_return

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}]

Source

values(proplist)

(function) # ↑

Specs:

values(t) :: [value]

Returns all values from the proplist list.

Examples

iex> Proplist.values([{"a", 1}, {"b", 2}])
[1,2]

Source