OrdMap v0.1.0 OrdMap View Source

A set of functions and a macro for working with ordered maps.
An ordered map is a struct with a list of key-value tuples where key and value can be any value.
It can be serialized to JSON with Poison - you need to add OrdMap Poison encoder to your project dependencies.

Usage

iex> o%{"foo" => "bar"}
%OrdMap{tuples: [{"foo", "bar"}]}

iex> my_ord_map = OrdMap.new([{"foo", 1}, {"bar", 2}])
iex> OrdMap.get(my_ord_map, "bar")
2

iex> my_ord_map = o%{"foo" => o(%{nested: "something"}), "bar" => "two"}
iex> my_ord_map["foo"][:nested]
"something"

iex> my_ord_map = o%{"foo" => 1, "bar" => 2}
iex> Enum.map my_ord_map, fn {key, value} -> {key, value + 1} end
[{"foo", 2}, {"bar", 3}]

Link to this section Summary

Functions

delete(tuples, key)

Deletes the entry in the ord_map/0 having a specific key

fetch(tuples, key)

Fetches the value for a specific key in the given ord_map/0

from_tuples(tuples)

Creates an ord_map/0 from a tuples/0

get(term, key, default \\ nil)

Gets the value for a specific key in ord_map/0

get_and_update(tuples, key, fun)

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

keys(tuples)

Returns all keys from ord_map/0

merge(ord_map1, ord_map2)

Merges two ord_map/0s into one

new()

Creates an empty ord_map/0

new(ord_map)

Creates an ord_map/0 from a Map, from a tuples/0 or from other ord_map/0

o(arg)

Macro transforms Map to ord_map/0 during compilation

pop(term, key, default \\ nil)

Returns and removes the value associated with key in the ord_map/0

put(tuples, key, value)

Puts the given value under key

replace(tuples, key, value)

Alters the value stored under key to value, but only if the entry key already exists in ord_map/0

values(tuples)

Returns all values from ord_map/0

Link to this section Types

key()

key() :: any()

ord_map()

ord_map() :: t()

t()

t() :: %OrdMap{tuples: tuples()}

tuples()

tuples() :: [{key(), value()}]

value()

value() :: any()

Link to this section Functions

delete(tuples, key)

delete(t() | tuples(), key()) :: t()

Deletes the entry in the ord_map/0 having a specific key.

If the key does not exist, returns the ord_map/0 unchanged.

Examples

iex> OrdMap.delete(o(%{"a" => 1, b: 2}), "a")
o%{b: 2}
iex> OrdMap.delete(o(%{b: 2}), :a)
o%{b: 2}

fetch(tuples, key)

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

Fetches the value for a specific key in the given ord_map/0.

If the key does not exist, returns :error.

Examples

iex> ord_map = o%{"a" => 1}
iex> OrdMap.fetch(ord_map, "a")
{:ok, 1}

iex> ord_map = o%{}
iex> OrdMap.fetch(ord_map, "key")
:error

from_tuples(tuples)

from_tuples(tuples()) :: t()

Creates an ord_map/0 from a tuples/0.

(Delegates to function OrdMap.new/1)

Examples

iex> [{:b, 1}, {:a, 2}] |> OrdMap.from_tuples
o%{b: 1, a: 2}

get(term, key, default \\ nil)

get(t() | tuples(), key(), default :: value()) :: value()

Gets the value for a specific key in ord_map/0.

If key is present in ord_map/0 with value value, then value is returned. Otherwise, default is returned (which is nil unless specified otherwise).

Examples

iex> OrdMap.get(o(%{}), :a)
nil
iex> OrdMap.get(o(%{a: 1}), :a)
1
iex> OrdMap.get(o(%{a: 1}), :b)
nil
iex> OrdMap.get(o(%{"a" => 1}), :b, 3)
3
iex> OrdMap.get([{:a, 2}], :a)
2

get_and_update(tuples, key, fun)

get_and_update(t() | tuples(), key(), (value() -> {get, value()} | :pop)) :: {get, t()} when get: term()

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

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 ‘ord_map’ and returned.

The returned value is a tuple with the “get” value returned by fun and a new ‘ord_map’ with the updated value under key.

Examples

iex> OrdMap.get_and_update(o(%{a: 1}), :a, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{1, o%{a: "new value!"}}
iex> OrdMap.get_and_update(o(%{a: 1}), :b, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{nil, o%{a: 1, b: "new value!"}}
iex> OrdMap.get_and_update(o(%{a: 1}), :a, fn _ -> :pop end)
{1, o%{}}
iex> OrdMap.get_and_update(o(%{a: 1}), :b, fn _ -> :pop end)
{nil, o%{a: 1}}

keys(tuples)

keys(t() | tuples()) :: [value()]

Returns all keys from ord_map/0.

Examples

iex> OrdMap.keys(o%{a: 1, b: 2})
[:a, :b]
iex> OrdMap.keys([{"a", 2}, {"b", 3}])
["a", "b"]
iex> OrdMap.keys([])
[]

merge(ord_map1, ord_map2)

merge(t(), t()) :: t()

Merges two ord_map/0s into one.

All keys in ord_map2 will be added to ord_map1, overriding any existing one (i.e., the keys in ord_map2 “have precedence” over the ones in ord_map1).

Examples

iex> OrdMap.merge(o(%{a: 1, b: 2}), o%{a: 3, d: 4})
o%{a: 3, b: 2, d: 4}

new()

new() :: t()

Creates an empty ord_map/0.

(See new/1 for creating ord_map/0 from other types)

Examples

iex> OrdMap.new()
o%{}

new(ord_map)

new(t() | map() | tuples()) :: t()

Creates an ord_map/0 from a Map, from a tuples/0 or from other ord_map/0.

(See new/0 creating an empty ord_map/0)

Examples

iex> OrdMap.new(%{a: 2, b: 1})
o%{a: 2, b: 1}
iex> OrdMap.new([a: 3, b: 4])
o%{a: 3, b: 4}
iex> OrdMap.new(%OrdMap{tuples: [{"a", 5}, {"b", 6}]})
o%{"a" => 5, "b" => 6}
iex> OrdMap.new([])
o%{}

o(arg) (macro)

Macro transforms Map to ord_map/0 during compilation.

Examples

iex> o%{a: 1, b: 2}
%OrdMap{tuples: [a: 1, b: 2]}
iex> o(%{"a" => "x"})
%OrdMap{tuples: [{"a", "x"}]}

pop(term, key, default \\ nil)

pop(t() | tuples(), key(), default :: value()) :: {value(), t()}

Returns and removes the value associated with key in the ord_map/0.

Examples

iex> OrdMap.pop(o(%{"a" => 1}), "a")
{1, o%{}}
iex> OrdMap.pop(o(%{a: 1}), :b)
{nil, o%{a: 1}}
iex> OrdMap.pop(o(%{a: 1}), :b, 3)
{3, o%{a: 1}}

put(tuples, key, value)

put(t() | tuples(), key(), value()) :: t()

Puts the given value under key.

If a previous value is already stored, the value is overridden.

Examples

iex> OrdMap.put(o(%{a: 1}), :b, 2)
o%{a: 1, b: 2}
iex> OrdMap.put(o(%{"a" => 1, b: 2}), "a", 3)
o%{"a" => 3, b: 2}

replace(tuples, key, value)

replace(t() | tuples(), key(), value()) :: t()

Alters the value stored under key to value, but only if the entry key already exists in ord_map/0.

Examples

iex> OrdMap.replace(o(%{a: 1}), :b, 2)
o%{a: 1}
iex> OrdMap.replace(o(%{a: 1, b: 2}), :a, 3)
o%{a: 3, b: 2}
iex> OrdMap.replace([{"c", 5},{"d", 6}], "c", 7)
o%{"c" => 7, "d" => 6}
iex> OrdMap.replace([], "c", 7)
o%{}

values(tuples)

values(t() | tuples()) :: [value()]

Returns all values from ord_map/0.

Examples

iex> OrdMap.values(o%{a: 1, b: 2})
[1, 2]
iex> OrdMap.values([a: 2, b: 3])
[2, 3]
iex> OrdMap.values([])
[]