BalancedTree v0.1.0 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

Types

A key in the tree

t()

A balanced tree

A value in the tree

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

Gets the value for a specific key in tree

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

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.

Link to this type t() View Source
t() :: %BalancedTree{comparator: term(), root: term()}

A balanced tree.

Link to this type value() View Source
value() :: any()

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]>
Link to this function empty?(tree) View Source
empty?(t()) :: boolean()

Returns true if tree is empty.

Link to this function fetch(tree, key) View Source
fetch(t(), key()) :: {:ok, value()} | :error

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
Link to this function fetch!(tree, key) View Source
fetch!(t(), key()) :: value() | no_return()
Link to this function get(tree, key, default \\ nil) View Source
get(t(), key(), (value() -> {get, value()} | :pop)) :: {get, t()} when get: term()
get(t(), key(), value()) :: value()

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

Link to this function get_and_update(tree, key, fun) View Source

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

Returns a new empty tree.

Examples

iex> BalancedTree.new
#BalancedTree<[]>
Link to this function new(values, opts \\ []) View Source
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]>
Link to this function pop(tree, key, default \\ nil) View Source
pop(t(), key(), value()) :: {value(), t()}

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]>
Link to this function size(tree) View Source
size(t()) :: integer()

Returns the number of elements in tree.

Link to this function to_list(tree) View Source
to_list(t()) :: [{key(), value()}]

Converts tree to a list.

Examples

iex> BalancedTree.to_list(BalancedTree.new([c: 1, b: 2, a: 3]))
[a: 3, b: 2, c: 1]