BalancedTree v0.2.1 BalancedTree View Source
This module provides an implementation of Prof. Arne Andersson’s Balanced Trees. BalancedTree is used to store and retrieve ordered data efficiently.
By default, two keys are considered equal if one is not less than <
or
greater than >
the other. A different comparison function can be specified.
The implementation is largely taken from Erlang :gb_trees
, with minor modifications
to provide an interface similar to Elixir Map
module.
Link to this section Summary
Functions
Deletes the entry for the given key
from tree
Returns true
if tree
is empty
Fetches the value for a specific key
in the given tree
Fetches the value for a specific key
in the given tree
, raising an error
if tree
doesn’t contain key
Gets the value for a specific key
in tree
Gets the value for key
in tree
and updates it, all in one pass
Gets the value fom key
in tree
and updates it. Raises if there is no key
Returns wheter the given key
exists in tree
Maps function fun
to all key-value pairs in tree
Returs the key-value pair associated with the largest key
in tree
Returs the key-value pair associated with the smallest key
in tree
Returns a new empty tree
Creates a new tree from values
Returns and removes the value for key
in tree
Puts the given value
under key
in tree
Returns the number of elements in tree
Converts tree
to a list
Link to this section Types
A key in the tree.
A balanced tree.
A value in the tree.
Link to this section Functions
Deletes the entry for the given key
from tree
.
Examples
iex> BalancedTree.delete(BalancedTree.new([a: 1]), :a)
#BalancedTree<[]>
iex> BalancedTree.delete(BalancedTree.new([a: 1]), :b)
#BalancedTree<[a: 1]>
Returns true
if tree
is empty.
Examples
iex> BalancedTree.empty?(BalancedTree.new())
true
iex> BalancedTree.empty?(BalancedTree.new([a: 1]))
false
Fetches the value for a specific key
in the given tree
.
Examples
iex> BalancedTree.fetch(BalancedTree.new([a: 1]), :a)
{:ok, 1}
iex> BalancedTree.fetch(BalancedTree.new([a: 1]), :b)
:error
Fetches the value for a specific key
in the given tree
, raising an error
if tree
doesn’t contain key
.
Examples
iex> BalancedTree.fetch!(BalancedTree.new([a: 1]), :a)
1
iex> BalancedTree.fetch!(BalancedTree.new([a: 1]), :b)
** (KeyError) key nil not found
Gets the value for a specific key
in tree
.
If key
is present in tree
with value
, then value
is returned.
Otherwise, a default
is returned.
Examples
iex> BalancedTree.get(BalancedTree.new([a: 1]), :b)
nil
iex> BalancedTree.get(BalancedTree.new([a: 1]), :a)
1
iex> BalancedTree.get(BalancedTree.new([a: 1]), :b, 3)
3
Gets the value for key
in tree
and updates it, all in one pass.
Examples
iex> {1, tree} = BalancedTree.get_and_update(BalancedTree.new([a: 1]), :a, fn value ->
...> {value, 2 * value}
...> end)
iex> tree
#BalancedTree<[a: 2]>
iex> {1, tree} = BalancedTree.get_and_update(BalancedTree.new([a: 1]), :a, fn _ ->
...> :pop
...> end)
iex> tree
#BalancedTree<[]>
iex> {nil, tree} = BalancedTree.get_and_update(BalancedTree.new([a: 1]), :b, fn nil ->
...> {nil, 2}
...> end)
iex> tree
#BalancedTree<[a: 1, b: 2]>
Gets the value fom key
in tree
and updates it. Raises if there is no key
.
Examples
iex> {1, tree} = BalancedTree.get_and_update!(BalancedTree.new([a: 1]), :a, fn value ->
...> {value, 2 * value}
...> end)
iex> tree
#BalancedTree<[a: 2]>
iex> {1, tree} = BalancedTree.get_and_update!(BalancedTree.new([a: 1]), :a, fn _ ->
...> :pop
...> end)
iex> tree
#BalancedTree<[]>
iex> BalancedTree.get_and_update!(BalancedTree.new([a: 1]), :b, fn _ ->
...> :pop
...> end)
** (KeyError) key nil not found
Returns wheter the given key
exists in tree
.
Examples
iex> BalancedTree.has_key?(BalancedTree.new([a: 1]), :a)
true
iex> BalancedTree.has_key?(BalancedTree.new([a: 1]), :b)
false
Maps function fun
to all key-value pairs in tree
.
Examples
iex> BalancedTree.map(BalancedTree.new([c: 3, b: 2, a: 1]), fn k, _ -> k end)
#BalancedTree<[a: :a, b: :b, c: :c]>
Returs the key-value pair associated with the largest key
in tree
.
Examples
iex> BalancedTree.max(BalancedTree.new([b: 2, a: 1]))
{:b, 2}
iex> BalancedTree.max(BalancedTree.new([b: 2, a: 1], comparator: &bigger_to_smaller/2))
{:a, 1}
iex> BalancedTree.max(BalancedTree.new())
nil
Returs the key-value pair associated with the smallest key
in tree
.
Examples
iex> BalancedTree.min(BalancedTree.new([b: 2, a: 1]))
{:a, 1}
iex> BalancedTree.min(BalancedTree.new([b: 2, a: 1], comparator: &bigger_to_smaller/2))
{:b, 2}
iex> BalancedTree.min(BalancedTree.new())
nil
new(Enumerable.t(), [{:comparator, (key(), key() -> :lt | :gt | :eq)}]) :: t()
Creates a new tree from values
.
Options
:comparator
function that takes two keys(a, b)
and returns::lt
if a < b:gt
if a > b:eq
if a == b
Examples
iex> BalancedTree.new([{1, :a}, {2, :b}, {3, :c}])
#BalancedTree<[1 => :a, 2 => :b, 3 => :c]>
iex> BalancedTree.new([{1, :a}, {2, :b}, {3, :c}], comparator: &bigger_to_smaller/2)
#BalancedTree<[3 => :c, 2 => :b, 1 => :a]>
Returns and removes the value for key
in tree
.
Examples
iex> {1, tree} = BalancedTree.pop(BalancedTree.new([a: 1]), :a)
iex> tree
#BalancedTree<[]>
iex> {nil, tree} = BalancedTree.pop(BalancedTree.new([a: 1]), :b)
iex> tree
#BalancedTree<[a: 1]>
iex> {3, tree} = BalancedTree.pop(BalancedTree.new([a: 1]), :b, 3)
iex> tree
#BalancedTree<[a: 1]>
Puts the given value
under key
in tree
.
Examples
iex> BalancedTree.put(BalancedTree.new([a: 1]), :b, 2)
#BalancedTree<[a: 1, b: 2]>
iex> BalancedTree.put(BalancedTree.new([a: 1, b: 2]), :b, 3)
#BalancedTree<[a: 1, b: 3]>