Module splay_tree

Splay Tree.

Copyright © 2013 Takeru Ohta <phjgt308@gmail.com>

Description

Splay Tree

Note

The keys of the entries in a tree are compared using the == operator (e.g., 1 and 1.0 are regarded as the same keys).

References

Data Types

fold_fn()

fold_fn() = fun((key(), value(), AccIn::term()) -> AccOut::term())

A function that folds the entries in a splay tree.

fold_while_fn()

fold_while_fn() = fun((key(), value(), AccIn::term()) -> {Continue::boolean(), AccOut::term()})

A function that folds the entries in a splay tree.

If the value of Continue is true, the folding will be broken and AccOut will be returned as the resulting value.

key()

key() = any()

The key of an entry in a splay tree.

Note

The keys are compared using the == operator (e.g., 1 and 1.0 are regarded as the same keys).

map_fn()

map_fn() = fun((key(), value()) -> value())

A function for mapping a splay tree to another one.

pred_fn()

pred_fn() = fun((key(), value()) -> boolean())

A predicate function that returns true if the input entry (key and value) satisfies the expected condition.

tree()

abstract datatype: tree(_Key, _Vlaue)

A splay tree.

tree()

abstract datatype: tree()

A splay tree.

update_fn()

update_fn() = fun((value()) -> value())

A function for updating the value of an entry in a splay tree.

value()

value() = any()

The value of an entry in a splay tree.

Function Index

erase/2Erases the entry whose key is equal to Key from the tree.
filter/2Makes a splay tree that contains entries in Tree for which the invocation of Pred returns true.
find/2Finds the value of the entry whose key is equal to Key in the tree.
find_largest/1Finds the entry which has the largest key in the tree.
find_lower_bound/2Finds the smallest entry among those whose key is equal to or greater than Key.
find_smallest/1Finds the entry which has the smallest key in the tree.
find_upper_bound/2Finds the smallest entry among those whose key is greater than Key.
foldl/3Folds the entries in Tree by ascending order.
foldl_while/3Folds the entries in Tree by ascending order.
foldr/3Folds the entries in Tree by descending order.
foldr_while/3Folds the entries in Tree by descending order.
from_list/1Makes a splay tree from the given associated list.
get_value/3Gets the value of the entry whose key is equal to Key in the tree.
is_empty/1Returns true if the tree is empty, otherwise false.
keys/1Returns the keys of the entries in Tree.
lookup/2Lookups the value of the entry whose key is equal to Key in the tree.
map/2Maps Tree to another splay tree.
new/0Makes an empty tree.
size/1Returns the number of entries in the tree.
split/2Splits Tree at the position specified by BorderKey.
store/3Stores the entry in Tree.
take_largest/1Takes the entry which has the largest key out from the tree.
take_smallest/1Takes the entry which has the smallest key out from the tree.
to_list/1Converts Tree` to an associated list. The resulting list is ordered by the key of the entries. == Example == ``` Tree = splay_tree:from_list([{2, b}, {3, c}, {1, a}]). [{1, a}, {2, b}, {3, c}] = splay_tree:to_list(Tree).''.
update/3Updates the value of an entry in the tree.
update/4Updates the value of an entry in the tree.
values/1Returns the values of the entries in Tree.

Function Details

erase/2

erase(Key::key(), Tree::tree()) -> tree()

Erases the entry whose key is equal to Key from the tree.

Example

  Tree0 = splay_tree:from_list([{foo, bar}]).
 
  Tree1 = splay_tree:erase(foo, Tree0).
  error = splay_tree:lookup(foo, Tree1).
 
  Tree1 = splay_tree:erase(foo, Tree1).

filter/2

filter(Pred::pred_fn(), Tree::tree()) -> tree()

Makes a splay tree that contains entries in Tree for which the invocation of Pred returns true.

Example

  Tree0 = splay_tree:from_list([{aaa, bbb}, {111, 222}]).
  Tree1 = splay_tree:filter(fun (K, _) -> is_atom(K) end, Tree0).
  [{aaa, bbb}] = splay_tree:to_list(Tree1).

find/2

find(Key::key(), Tree::tree()) -> {error, tree()} | {{ok, value()}, tree()}

Finds the value of the entry whose key is equal to Key in the tree.

Because splay tree is an amortized data structure, this function partially rebalance Tree and returns the updated tree.

Example

  Tree = splay_tree:from_list([{foo, bar}]).
 
  {{ok, bar}, _} = splay_tree:find(foo, Tree).
  {error, _} = splay_tree:find(baz, Tree).

find_largest/1

find_largest(Tree::tree()) -> {error, tree()} | {{ok, key(), value()}, tree()}

Finds the entry which has the largest key in the tree.

If Tree is empty, {error, Tree} will be returned.

Because splay tree is an amortized data structure, this function partially rebalance Tree and returns the updated tree.

Example

  Tree = splay_tree:from_list([{333, 444}, {111, 222}]).
  {{ok, 333, 444}, _} = splay_tree:find_largest(Tree).

find_lower_bound/2

find_lower_bound(Key::key(), Tree::tree()) -> {error, tree()} | {{ok, key(), value()}, tree()}

Finds the smallest entry among those whose key is equal to or greater than Key.

Because splay tree is an amortized data structure, this function partially rebalance Tree and returns the updated tree.

Example

  Tree = splay_tree:from_list([{1, a}, {2, b}, {3, c}]).
  {{ok, 2, b}, _} = splay_tree:find_lower_bound(2, Tree).
  {{ok, 3, c}, _} = splay_tree:find_lower_bound(2.5, Tree).
  {error, _}      = splay_tree:find_lower_bound(3.1, Tree).

find_smallest/1

find_smallest(Tree::tree()) -> {error, tree()} | {{ok, key(), value()}, tree()}

Finds the entry which has the smallest key in the tree.

If Tree is empty, {error, Tree} will be returned.

Because splay tree is an amortized data structure, this function partially rebalance Tree and returns the updated tree.

Example

  Tree = splay_tree:from_list([{333, 444}, {111, 222}]).
  {{ok, 111, 222}, _} = splay_tree:find_smallest(Tree).

find_upper_bound/2

find_upper_bound(Key::key(), Tree::tree()) -> {error, tree()} | {{ok, key(), value()}, tree()}

Finds the smallest entry among those whose key is greater than Key.

Because splay tree is an amortized data structure, this function partially rebalance Tree and returns the updated tree.

Example

  Tree = splay_tree:from_list([{1, a}, {2, b}, {3, c}]).
  {{ok, 3, c}, _} = splay_tree:find_upper_bound(2, Tree).
  {{ok, 3, c}, _} = splay_tree:find_upper_bound(2.5, Tree).
  {error, _}      = splay_tree:find_upper_bound(3.1, Tree).

foldl/3

foldl(Fun::fold_fn(), Initial::term(), Tree::tree()) -> Result::term()

Folds the entries in Tree by ascending order.

Example

  Tree = splay_tree:from_list([{a, 1}, {b, 2}]).
  [2, 1] = splay_tree:foldl(fun (_, V, Acc) -> [V | Acc] end, [], Tree).

foldl_while/3

foldl_while(Fun::fold_while_fn(), Initial::term(), Tree::tree()) -> Result::term()

Folds the entries in Tree by ascending order.

If Fun returns {false, Result}, the folding will be broken immediately and Result` will be returned as the resulting value. == Example == ``` Tree = splay_tree:from_list([{a, 1}, {b, 2}]). [1] = splay_tree:foldl_while(fun (_, V, Acc) -> {false, [V | Acc]} end, [], Tree).''

foldr/3

foldr(Fun::fold_fn(), Initial::term(), Tree::tree()) -> Result::term()

Folds the entries in Tree by descending order.

Example

  Tree = splay_tree:from_list([{a, 1}, {b, 2}]).
  [1, 2] = splay_tree:foldr(fun (_, V, Acc) -> [V | Acc] end, [], Tree).

foldr_while/3

foldr_while(Fun::fold_while_fn(), Initial::term(), Tree::tree()) -> term()

Folds the entries in Tree by descending order.

If Fun returns {false, Result}, the folding will be broken immediately and Result` will be returned as the resulting value. == Example == ``` Tree = splay_tree:from_list([{a, 1}, {b, 2}]). [2] = splay_tree:foldr_while(fun (_, V, Acc) -> {false, [V | Acc]} end, [], Tree).''

from_list/1

from_list(List::[{key(), value()}]) -> tree()

Makes a splay tree from the given associated list.

Example

  Tree = splay_tree:from_list([{2, b}, {1, a}]).
  {{ok, a}, _} = splay_tree:find(1, Tree).

get_value/3

get_value(Key::key(), Tree::tree(), DefaultValue::value()) -> value()

Gets the value of the entry whose key is equal to Key in the tree.

If there is no entry which has the key, this function will return DefaultValue instead.

Caution

Unlike find/2, this function does not rebalance Tree. So use of this function may cause performance degradation.

Example

  Tree = splay_tree:from_list([{foo, bar}]).
 
  bar = splay_tree:get_value(foo, Tree, qux).
  qux = splay_tree:get_value(baz, Tree, qux).

is_empty/1

is_empty(X1::tree()) -> boolean()

Returns true if the tree is empty, otherwise false.

Example

  Tree = splay_tree:new().
  true = splay_tree:is_empty(Tree).

keys/1

keys(Tree::tree()) -> [key()]

Returns the keys of the entries in Tree.

The resulting list is in ascending order.

Example

  Tree = splay_tree:from_list([{2, b}, {3, c}, {1, a}]).
  [1, 2, 3] = splay_tree:keys(Tree).

lookup/2

lookup(Key::key(), Tree::tree()) -> error | {ok, value()}

Lookups the value of the entry whose key is equal to Key in the tree.

Caution

Unlike find/2, this function does not rebalance Tree. So use of this function may cause performance degradation.

Example

  Tree = splay_tree:from_list([{foo, bar}]).
 
  {ok, bar} = splay_tree:lookup(foo, Tree).
  error = splay_tree:lookup(baz, Tree).

map/2

map(Fun::map_fn(), Tree::tree()) -> tree()

Maps Tree to another splay tree.

Example

  Tree0 = splay_tree:from_list([{1, 2}, {3, 4}]).
  Tree1 = splay_tree:map(fun (K, V) -> K + V end, Tree0).
  [{1, 3}, {3, 7}] = splay_tree:to_list(Tree1).

new/0

new() -> tree()

Makes an empty tree.

Example

  Tree = splay_tree:new().
  true = splay_tree:is_empty(Tree).

size/1

size(Tree::tree()) -> non_neg_integer()

Returns the number of entries in the tree.

Note that this function takes N steps (where N is the number of entries).

Example

  Tree0 = splay_tree:new().
  0 = splay_tree:size(Tree0).
 
  Tree1 = splay_tree:store(foo, bar, Tree1).
  1 = splay_tree:size(Tree1).

split/2

split(BorderKey::key(), Tree::tree()) -> {LeftTree::tree(), RightTree::tree()}

Splits Tree at the position specified by BorderKey.

LeftTree contains the entries whose key is smaller than BorderKey. RightTree contains the entries whose key is equal to or greater than BorderKey.

Example

  Tree = splay_tree:from_list([{1, a}, {2, b}, {3, c}]).
  {Left, Right} = splay_tree:split(2, Tree).
 
  [1] = splay_tree:keys(Left).
  [2, 3] = splay_tree:keys(Right).

store/3

store(Key::key(), Value::value(), Tree::tree()) -> tree()

Stores the entry in Tree.

If there is an entry whose key is equal to Key, its value will be replaced by Value.

Example

  Tree0 = splay_tree:new().
  Tree1 = splay_tree:store(foo, bar, Tree0).
  Tree2 = splay_tree:store(111, 222, Tree1).
 
  [{111, 222}, {foo, bar}] = splay_tree:to_list(Tree2).

take_largest/1

take_largest(Tree::tree()) -> {error, tree()} | {{ok, key(), value()}, tree()}

Takes the entry which has the largest key out from the tree.

If Tree is empty, {error, Tree} will be returned.

Example

  Tree0 = splay_tree:from_list([{333, 444}, {111, 222}]).
  {{ok, 333, 444}, Tree1} = splay_tree:take_largest(Tree0).
  {{ok, 111, 222}, Tree2} = splay_tree:take_largest(Tree1).
  {error,          Tree2} = splay_tree:take_largest(Tree2).

take_smallest/1

take_smallest(Tree::tree()) -> {error, tree()} | {{ok, key(), value()}, tree()}

Takes the entry which has the smallest key out from the tree.

If Tree is empty, {error, Tree} will be returned.

Example

  Tree0 = splay_tree:from_list([{333, 444}, {111, 222}]).
  {{ok, 111, 222}, Tree1} = splay_tree:take_smallest(Tree0).
  {{ok, 333, 444}, Tree2} = splay_tree:take_smallest(Tree1).
  {error,          Tree2} = splay_tree:take_smallest(Tree2).

to_list/1

to_list(Tree::tree()) -> [{key(), value()}]

Converts Tree` to an associated list. The resulting list is ordered by the key of the entries. == Example == ``` Tree = splay_tree:from_list([{2, b}, {3, c}, {1, a}]). [{1, a}, {2, b}, {3, c}] = splay_tree:to_list(Tree).''

update/3

update(Key::key(), Fun::update_fn(), Tree::tree()) -> {ok, tree()} | error

Updates the value of an entry in the tree.

If there is an entry whose key is equal to Key, its value will be updated to Fun(Key, CurrentValue). Otherwise this function will return error.

Example

  Tree0 = splay_tree:from_list([{foo, bar}]).
 
  %% `foo' exists.
  {ok, Tree1} = splay_tree:update(foo, fun (bar) -> baz end, Tree0).
  {{ok, baz}, _} = splay_tree:find(foo, Tree1).
 
  %% `111' does not exist.
  error = splay_tree:update(111, fun (_) -> 222 end, Tree1).

update/4

update(Key::key(), Fun::update_fn(), Initial::value(), Tree::tree()) -> tree()

Updates the value of an entry in the tree.

If there is an entry whose key is equal to Key, its value will be updated to Fun(Key, CurrentValue). Otherwise a new entry whose value is Initial will be inserted to the tree.

Example

  Tree0 = splay_tree:from_list([{foo, bar}]).
 
  %% `foo' exists.
  Tree1 = splay_tree:update(foo, fun (bar) -> baz end, qux, Tree0).
  {{ok, baz}, _} = splay_tree:find(foo, Tree1).
 
  %% `111' does not exist.
  Tree2 = splay_tree:update(111, fun (_) -> 222 end, 333, Tree1).
  {{ok, 333}, _} = splay_tree:find(111, Tree2).

values/1

values(Tree::tree()) -> [value()]

Returns the values of the entries in Tree.

The resulting values are ordered by the associated keys.

Example

  Tree = splay_tree:from_list([{2, a}, {3, b}, {1, c}]).
  [c, a, b] = splay_tree:values(Tree).


Generated by EDoc