From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/gb_trees.xml | 367 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 367 insertions(+) create mode 100644 lib/stdlib/doc/src/gb_trees.xml (limited to 'lib/stdlib/doc/src/gb_trees.xml') diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml new file mode 100644 index 0000000000..2bf18138c0 --- /dev/null +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -0,0 +1,367 @@ + + + + +
+ + 20012009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + gb_trees + + + + +
+ gb_trees + General Balanced Trees + +

An efficient implementation of Prof. Arne Andersson's General + Balanced Trees. These have no storage overhead compared to + unbalanced binary trees, and their performance is in general + better than AVL trees.

+ + +
+ Data structure +

Data structure:

+ + +- {Size, Tree}, where `Tree' is composed of nodes of the form: + - {Key, Value, Smaller, Bigger}, and the "empty tree" node: + - nil. +

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

+

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.

+

Performance is comparable to the AVL trees in the Erlang book + (and faster in general due to less overhead); the difference is + that deletion works for these trees, but not for the book's + trees. Behaviour is logarithmic (as it should be).

+
+ +
+ DATA TYPES + +gb_tree() = a GB tree +
+ + + balance(Tree1) -> Tree2 + Rebalance a tree + + Tree1 = Tree2 = gb_tree() + + +

Rebalances Tree1. Note that this is rarely necessary, + but may be motivated when a large number of nodes have been + deleted from the tree without further insertions. Rebalancing + could then be forced in order to minimise lookup times, since + deletion only does not rebalance the tree.

+ + + + delete(Key, Tree1) -> Tree2 + Remove a node from a tree + + Key = term() + Tree1 = Tree2 = gb_tree() + + +

Removes the node with key Key from Tree1; + returns new tree. Assumes that the key is present in the tree, + crashes otherwise.

+ + + + delete_any(Key, Tree1) -> Tree2 + Remove a (possibly non-existing) node from a tree + + Key = term() + Tree1 = Tree2 = gb_tree() + + +

Removes the node with key Key from Tree1 if + the key is present in the tree, otherwise does nothing; + returns new tree.

+ + + + empty() -> Tree + Return an empty tree + + Tree = gb_tree() + + +

Returns a new empty tree

+ + + + enter(Key, Val, Tree1) -> Tree2 + Insert or update key with value in a tree + + Key = Val = term() + Tree1 = Tree2 = gb_tree() + + +

Inserts Key with value Val into Tree1 if + the key is not present in the tree, otherwise updates + Key to value Val in Tree1. Returns the + new tree.

+ + + + from_orddict(List) -> Tree + Make a tree from an orddict + + List = [{Key, Val}] +  Key = Val = term() + Tree = gb_tree() + + +

Turns an ordered list List of key-value tuples into a + tree. The list must not contain duplicate keys.

+ + + + get(Key, Tree) -> Val + Look up a key in a tree, if present + + Key = Val = term() + Tree = gb_tree() + + +

Retrieves the value stored with Key in Tree. + Assumes that the key is present in the tree, crashes + otherwise.

+ + + + lookup(Key, Tree) -> {value, Val} | none + Look up a key in a tree + + Key = Val = term() + Tree = gb_tree() + + +

Looks up Key in Tree; returns + {value, Val}, or none if Key is not + present.

+ + + + insert(Key, Val, Tree1) -> Tree2 + Insert a new key and value in a tree + + Key = Val = term() + Tree1 = Tree2 = gb_tree() + + +

Inserts Key with value Val into Tree1; + returns the new tree. Assumes that the key is not present in + the tree, crashes otherwise.

+ + + + is_defined(Key, Tree) -> bool() + Test for membership of a tree + + Tree = gb_tree() + + +

Returns true if Key is present in Tree, + otherwise false.

+ + + + is_empty(Tree) -> bool() + Test for empty tree + + Tree = gb_tree() + + +

Returns true if Tree is an empty tree, and + false otherwise.

+ + + + iterator(Tree) -> Iter + Return an iterator for a tree + + Tree = gb_tree() + Iter = term() + + +

Returns an iterator that can be used for traversing the + entries of Tree; 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.

+ + + + keys(Tree) -> [Key] + Return a list of the keys in a tree + + Tree = gb_tree() + Key = term() + + +

Returns the keys in Tree as an ordered list.

+ + + + largest(Tree) -> {Key, Val} + Return largest key and value + + Tree = gb_tree() + Key = Val = term() + + +

Returns {Key, Val}, where Key is the largest + key in Tree, and Val is the value associated + with this key. Assumes that the tree is nonempty.

+ + + + map(Function, Tree1) -> Tree2 + Return largest key and value + + Function = fun(K, V1) -> V2 + Tree1 = Tree2 = gb_tree() + +

maps the function F(K, V1) -> V2 to all key-value pairs + of the tree Tree1 and returns a new tree Tree2 with the same set of keys + as Tree1 and the new set of values V2.

+ + + + next(Iter1) -> {Key, Val, Iter2} | none + Traverse a tree with an iterator + + Iter1 = Iter2 = Key = Val = term() + + +

Returns {Key, Val, Iter2} where Key is the + smallest key referred to by the iterator Iter1, and + Iter2 is the new iterator to be used for + traversing the remaining nodes, or the atom none if no + nodes remain.

+ + + + size(Tree) -> int() + Return the number of nodes in a tree + + Tree = gb_tree() + + +

Returns the number of nodes in Tree.

+ + + + smallest(Tree) -> {Key, Val} + Return smallest key and value + + Tree = gb_tree() + Key = Val = term() + + +

Returns {Key, Val}, where Key is the smallest + key in Tree, and Val is the value associated + with this key. Assumes that the tree is nonempty.

+ + + + take_largest(Tree1) -> {Key, Val, Tree2} + Extract largest key and value + + Tree1 = Tree2 = gb_tree() + Key = Val = term() + + +

Returns {Key, Val, Tree2}, where Key is the + largest key in Tree1, Val is the value + associated with this key, and Tree2 is this tree with + the corresponding node deleted. Assumes that the tree is + nonempty.

+ + + + take_smallest(Tree1) -> {Key, Val, Tree2} + Extract smallest key and value + + Tree1 = Tree2 = gb_tree() + Key = Val = term() + + +

Returns {Key, Val, Tree2}, where Key is the + smallest key in Tree1, Val is the value + associated with this key, and Tree2 is this tree with + the corresponding node deleted. Assumes that the tree is + nonempty.

+ + + + to_list(Tree) -> [{Key, Val}] + Convert a tree into a list + + Tree = gb_tree() + Key = Val = term() + + +

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

+ + + + update(Key, Val, Tree1) -> Tree2 + Update a key to new value in a tree + + Key = Val = term() + Tree1 = Tree2 = gb_tree() + + +

Updates Key to value Val in Tree1; + returns the new tree. Assumes that the key is present in the + tree.

+ + + + values(Tree) -> [Val] + Return a list of the values in a tree + + Tree = gb_tree() + Val = term() + + +

Returns the values in Tree as an ordered list, sorted + by their corresponding keys. Duplicates are not removed.

+ + + + +
+ SEE ALSO +

gb_sets(3), + dict(3)

+
+ + -- cgit v1.2.3