# View Source gb_trees (stdlib v6.0.1)

General balanced trees.

This module provides Prof. Arne Andersson's General Balanced Trees. These have no storage overhead compared to unbalanced binary trees, and their performance is better than AVL trees.

This module considers two keys as different if and only if they do not compare
equal (`==`

).

## Data Structure

Trees and iterators are built using opaque data structures that should not be pattern-matched from outside this module.

There is no attempt to balance trees after deletions. As deletions do not increase the height of a tree, this should be OK.

The original balance condition `h(T) <= ceil(c * log(|T|))`

has been changed to
the similar (but not quite equivalent) condition `2 ^ h(T) <= |T| ^ c`

. This
should also be OK.

## See Also

# Summary

## Functions

Rebalances `Tree1`

.

Removes the node with key `Key`

from `Tree1`

and returns the new tree. Assumes
that the key is present in the tree, crashes otherwise.

Removes the node with key `Key`

from `Tree1`

if the key is present in the tree,
otherwise does nothing. Returns the new tree.

Returns a new empty tree.

Inserts `Key`

with value `Value`

into `Tree1`

if the key is not present in the
tree, otherwise updates `Key`

to value `Value`

in `Tree1`

. Returns the new tree.

Turns an ordered list `List`

of key-value tuples into a tree. The list must not
contain duplicate keys.

Retrieves the value stored with `Key`

in `Tree`

. Assumes that the key is present
in the tree, crashes otherwise.

Inserts `Key`

with value `Value`

into `Tree1`

and returns the new tree. Assumes
that the key is not present in the tree, crashes otherwise.

Returns `true`

if `Key`

is present in `Tree`

, otherwise `false`

.

Returns `true`

if `Tree`

is an empty tree, othwewise `false`

.

Returns an iterator that can be used for traversing the entries of `Tree`

; see
`next/1`

.

Returns an iterator that can be used for traversing the entries of `Tree`

in
either `ordered`

or `reversed`

direction; see `next/1`

.

Returns an iterator that can be used for traversing the entries of `Tree`

; see
`next/1`

. The difference as compared to the iterator returned by `iterator/1`

is
that the iterator starts with the first key greater than or equal to `Key`

.

Returns an iterator that can be used for traversing the entries of `Tree`

in
either `ordered`

or `reversed`

direction; see `next/1`

. The difference as
compared to the iterator returned by `iterator/2`

is that the iterator starts
with the first key next to or equal to `Key`

.

Returns the keys in `Tree`

as an ordered list.

Returns `{Key2, Value}`

, where `Key2`

is the least key strictly greater than
`Key1`

, `Value`

is the value associated with this key.

Returns `{Key, Value}`

, where `Key`

is the largest key in `Tree`

, and `Value`

is
the value associated with this key. Assumes that the tree is not empty.

Looks up `Key`

in `Tree`

. Returns `{value, Value}`

, or `none`

if `Key`

is not
present.

Maps function F(K, V1) -> V2 to all key-value pairs of tree `Tree1`

. Returns a
new tree `Tree2`

with the same set of keys as `Tree1`

and the new set of values
`V2`

.

Returns `{Key, Value, Iter2}`

, where `Key`

is the next key referred to by
iterator `Iter1`

, and `Iter2`

is the new iterator to be used for traversing the
remaining nodes, or the atom `none`

if no nodes remain.

Returns the number of nodes in `Tree`

.

Returns `{Key2, Value}`

, where `Key2`

is the greatest key strictly less than
`Key1`

, `Value`

is the value associated with this key.

Returns `{Key, Value}`

, where `Key`

is the smallest key in `Tree`

, and `Value`

is the value associated with this key. Assumes that the tree is not empty.

Returns a value `Value`

from node with key `Key`

and new `Tree2`

without the
node with this value. Assumes that the node with key is present in the tree,
crashes otherwise.

Returns a value `Value`

from node with key `Key`

and new `Tree2`

without the
node with this value. Returns `error`

if the node with the key is not present in
the tree.

Returns `{Key, Value, Tree2}`

, where `Key`

is the largest key in `Tree1`

,
`Value`

is the value associated with this key, and `Tree2`

is this tree with the
corresponding node deleted. Assumes that the tree is not empty.

Returns `{Key, Value, Tree2}`

, where `Key`

is the smallest key in `Tree1`

,
`Value`

is the value associated with this key, and `Tree2`

is this tree with the
corresponding node deleted. Assumes that the tree is not empty.

Converts a tree into an ordered list of key-value tuples.

Updates `Key`

to value `Value`

in `Tree1`

and returns the new tree. Assumes that
the key is present in the tree.

Returns the values in `Tree`

as an ordered list, sorted by their corresponding
keys. Duplicates are not removed.

# Types

# Functions

Rebalances `Tree1`

.

Notice that this is rarely necessary, but can be motivated when many nodes have been deleted from the tree without further insertions. Rebalancing can then be forced to minimize lookup times, as deletion does not rebalance the tree.

Removes the node with key `Key`

from `Tree1`

and returns the new tree. Assumes
that the key is present in the tree, crashes otherwise.

Removes the node with key `Key`

from `Tree1`

if the key is present in the tree,
otherwise does nothing. Returns the new tree.

Returns a new empty tree.

Inserts `Key`

with value `Value`

into `Tree1`

if the key is not present in the
tree, otherwise updates `Key`

to value `Value`

in `Tree1`

. Returns the new tree.

-spec from_orddict(List) -> Tree when List :: [{Key, Value}], Tree :: tree(Key, Value).

Turns an ordered list `List`

of key-value tuples into a tree. The list must not
contain duplicate keys.

-spec get(Key, Tree) -> Value when Tree :: tree(Key, Value).

Retrieves the value stored with `Key`

in `Tree`

. Assumes that the key is present
in the tree, crashes otherwise.

Inserts `Key`

with value `Value`

into `Tree1`

and returns the new tree. Assumes
that the key is not present in the tree, crashes otherwise.

Returns `true`

if `Key`

is present in `Tree`

, otherwise `false`

.

Returns `true`

if `Tree`

is an empty tree, othwewise `false`

.

Returns an iterator that can be used for traversing the entries of `Tree`

; see
`next/1`

.

Equivalent to `iterator(Tree, ordered)`

.

-spec iterator(Tree, Order) -> Iter when Tree :: tree(Key, Value), Iter :: iter(Key, Value), Order :: ordered | reversed.

Returns an iterator that can be used for traversing the entries of `Tree`

in
either `ordered`

or `reversed`

direction; see `next/1`

.

The implementation of this is very efficient; traversing the whole tree using
`next/1`

is only slightly slower than getting the list of all
elements using `to_list/1`

and traversing that. The main advantage of the
iterator approach is that it does not require the complete list of all elements
to be built in memory at one time.

Returns an iterator that can be used for traversing the entries of `Tree`

; see
`next/1`

. The difference as compared to the iterator returned by `iterator/1`

is
that the iterator starts with the first key greater than or equal to `Key`

.

Equivalent to `iterator_from(Key, Tree, ordered)`

.

-spec iterator_from(Key, Tree, Order) -> Iter when Tree :: tree(Key, Value), Iter :: iter(Key, Value), Order :: ordered | reversed.

Returns an iterator that can be used for traversing the entries of `Tree`

in
either `ordered`

or `reversed`

direction; see `next/1`

. The difference as
compared to the iterator returned by `iterator/2`

is that the iterator starts
with the first key next to or equal to `Key`

.

Returns the keys in `Tree`

as an ordered list.

-spec larger(Key1, Tree) -> none | {Key2, Value} when Key1 :: Key, Key2 :: Key, Tree :: tree(Key, Value).

Returns `{Key2, Value}`

, where `Key2`

is the least key strictly greater than
`Key1`

, `Value`

is the value associated with this key.

Returns `none`

if no such pair exists.

-spec largest(Tree) -> {Key, Value} when Tree :: tree(Key, Value).

Returns `{Key, Value}`

, where `Key`

is the largest key in `Tree`

, and `Value`

is
the value associated with this key. Assumes that the tree is not empty.

-spec lookup(Key, Tree) -> none | {value, Value} when Tree :: tree(Key, Value).

Looks up `Key`

in `Tree`

. Returns `{value, Value}`

, or `none`

if `Key`

is not
present.

-spec map(Function, Tree1) -> Tree2 when Function :: fun((K :: Key, V1 :: Value1) -> V2 :: Value2), Tree1 :: tree(Key, Value1), Tree2 :: tree(Key, Value2).

Maps function F(K, V1) -> V2 to all key-value pairs of tree `Tree1`

. Returns a
new tree `Tree2`

with the same set of keys as `Tree1`

and the new set of values
`V2`

.

-spec next(Iter1) -> none | {Key, Value, Iter2} when Iter1 :: iter(Key, Value), Iter2 :: iter(Key, Value).

Returns `{Key, Value, Iter2}`

, where `Key`

is the next key referred to by
iterator `Iter1`

, and `Iter2`

is the new iterator to be used for traversing the
remaining nodes, or the atom `none`

if no nodes remain.

-spec size(Tree) -> non_neg_integer() when Tree :: tree().

Returns the number of nodes in `Tree`

.

-spec smaller(Key1, Tree) -> none | {Key2, Value} when Key1 :: Key, Key2 :: Key, Tree :: tree(Key, Value).

Returns `{Key2, Value}`

, where `Key2`

is the greatest key strictly less than
`Key1`

, `Value`

is the value associated with this key.

Returns `none`

if no such pair exists.

-spec smallest(Tree) -> {Key, Value} when Tree :: tree(Key, Value).

Returns `{Key, Value}`

, where `Key`

is the smallest key in `Tree`

, and `Value`

is the value associated with this key. Assumes that the tree is not empty.

-spec take(Key, Tree1) -> {Value, Tree2} when Tree1 :: tree(Key, _), Tree2 :: tree(Key, _), Key :: term(), Value :: term().

Returns a value `Value`

from node with key `Key`

and new `Tree2`

without the
node with this value. Assumes that the node with key is present in the tree,
crashes otherwise.

-spec take_any(Key, Tree1) -> {Value, Tree2} | error when Tree1 :: tree(Key, _), Tree2 :: tree(Key, _), Key :: term(), Value :: term().

Returns a value `Value`

from node with key `Key`

and new `Tree2`

without the
node with this value. Returns `error`

if the node with the key is not present in
the tree.

-spec take_largest(Tree1) -> {Key, Value, Tree2} when Tree1 :: tree(Key, Value), Tree2 :: tree(Key, Value).

Returns `{Key, Value, Tree2}`

, where `Key`

is the largest key in `Tree1`

,
`Value`

is the value associated with this key, and `Tree2`

is this tree with the
corresponding node deleted. Assumes that the tree is not empty.

-spec take_smallest(Tree1) -> {Key, Value, Tree2} when Tree1 :: tree(Key, Value), Tree2 :: tree(Key, Value).

Returns `{Key, Value, Tree2}`

, where `Key`

is the smallest key in `Tree1`

,
`Value`

is the value associated with this key, and `Tree2`

is this tree with the
corresponding node deleted. Assumes that the tree is not empty.

-spec to_list(Tree) -> [{Key, Value}] when Tree :: tree(Key, Value).

Converts a tree into an ordered list of key-value tuples.

Updates `Key`

to value `Value`

in `Tree1`

and returns the new tree. Assumes that
the key is present in the tree.

Returns the values in `Tree`

as an ordered list, sorted by their corresponding
keys. Duplicates are not removed.