aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/gb_trees.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/gb_trees.xml')
-rw-r--r--lib/stdlib/doc/src/gb_trees.xml245
1 files changed, 144 insertions, 101 deletions
diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml
index 5d1f27c014..9a49d66820 100644
--- a/lib/stdlib/doc/src/gb_trees.xml
+++ b/lib/stdlib/doc/src/gb_trees.xml
@@ -29,277 +29,320 @@
<rev></rev>
</header>
<module>gb_trees</module>
- <modulesummary>General Balanced Trees</modulesummary>
+ <modulesummary>General balanced trees.</modulesummary>
<description>
- <p>An efficient implementation of Prof. Arne Andersson's General
+ <p>This module provides Prof. Arne Andersson's General
Balanced Trees. These have no storage overhead compared to
- unbalanced binary trees, and their performance is in general
+ unbalanced binary trees, and their performance is
better than AVL trees.</p>
+
<p>This module considers two keys as different if and only if
they do not compare equal (<c>==</c>).</p>
</description>
<section>
- <title>Data structure</title>
- <p>Data structure:</p>
+ <title>Data Structure</title>
<code type="none">
-
-- {Size, Tree}, where `Tree' is composed of nodes of the form:
- - {Key, Value, Smaller, Bigger}, and the "empty tree" node:
- - nil.</code>
- <p>There is no attempt to balance trees after deletions. Since
+{Size, Tree}</code>
+
+ <p><c>Tree</c> is composed of nodes of the form <c>{Key, Value, Smaller,
+ Bigger}</c> and the "empty tree" node <c>nil</c>.</p>
+
+ <p>There is no attempt to balance trees after deletions. As
deletions do not increase the height of a tree, this should be OK.</p>
- <p>Original balance condition <em>h(T) &lt;= ceil(c * log(|T|))</em>
+
+ <p>The original balance condition <em>h(T) &lt;= ceil(c * log(|T|))</em>
has been changed to the similar (but not quite equivalent)
condition <em>2 ^ h(T) &lt;= |T| ^ c</em>. This should also be OK.</p>
- <p>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).</p>
</section>
<datatypes>
<datatype>
<name name="tree" n_vars="2"/>
- <desc><p>A GB tree.</p></desc>
+ <desc><p>A general balanced tree.</p></desc>
</datatype>
<datatype>
<name name="tree" n_vars="0"/>
</datatype>
<datatype>
<name name="iter" n_vars="2"/>
- <desc><p>A GB tree iterator.</p></desc>
+ <desc><p>A general balanced tree iterator.</p></desc>
</datatype>
<datatype>
<name name="iter" n_vars="0"/>
</datatype>
</datatypes>
+
<funcs>
<func>
<name name="balance" arity="1"/>
- <fsummary>Rebalance a tree</fsummary>
+ <fsummary>Rebalance a tree.</fsummary>
<desc>
- <p>Rebalances <c><anno>Tree1</anno></c>. Note that this is rarely necessary,
- but may be motivated when a large number of nodes have been
+ <p>Rebalances <c><anno>Tree1</anno></c>. Notice that this is
+ rarely necessary,
+ but can be motivated when many 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.</p>
+ can then be forced to minimize lookup times, as
+ deletion does not rebalance the tree.</p>
</desc>
</func>
+
<func>
<name name="delete" arity="2"/>
- <fsummary>Remove a node from a tree</fsummary>
+ <fsummary>Remove a node from a tree.</fsummary>
<desc>
- <p>Removes the node with key <c><anno>Key</anno></c> from <c><anno>Tree1</anno></c>;
- returns new tree. Assumes that the key is present in the tree,
- crashes otherwise.</p>
+ <p>Removes the node with key <c><anno>Key</anno></c> from
+ <c><anno>Tree1</anno></c> and returns the new tree. Assumes that the
+ key is present in the tree, crashes otherwise.</p>
</desc>
</func>
+
<func>
<name name="delete_any" arity="2"/>
- <fsummary>Remove a (possibly non-existing) node from a tree</fsummary>
+ <fsummary>Remove a (possibly non-existing) node from a tree.</fsummary>
<desc>
- <p>Removes the node with key <c><anno>Key</anno></c> from <c><anno>Tree1</anno></c> if
- the key is present in the tree, otherwise does nothing;
- returns new tree.</p>
+ <p>Removes the node with key <c><anno>Key</anno></c> from
+ <c><anno>Tree1</anno></c> if
+ the key is present in the tree, otherwise does nothing.
+ Returns the new tree.</p>
</desc>
</func>
+
<func>
<name name="empty" arity="0"/>
- <fsummary>Return an empty tree</fsummary>
+ <fsummary>Return an empty tree.</fsummary>
<desc>
- <p>Returns a new empty tree</p>
+ <p>Returns a new empty tree.</p>
</desc>
</func>
+
<func>
<name name="enter" arity="3"/>
- <fsummary>Insert or update key with value in a tree</fsummary>
+ <fsummary>Insert or update key with value in a tree.</fsummary>
<desc>
- <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> into <c><anno>Tree1</anno></c> if
- the key is not present in the tree, otherwise updates
- <c><anno>Key</anno></c> to value <c><anno>Value</anno></c> in <c><anno>Tree1</anno></c>. Returns the
+ <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c>
+ into <c><anno>Tree1</anno></c> if the key is not present in the tree,
+ otherwise updates <c><anno>Key</anno></c> to value
+ <c><anno>Value</anno></c> in <c><anno>Tree1</anno></c>. Returns the
new tree.</p>
</desc>
</func>
+
<func>
<name name="from_orddict" arity="1"/>
- <fsummary>Make a tree from an orddict</fsummary>
+ <fsummary>Make a tree from an orddict.</fsummary>
<desc>
- <p>Turns an ordered list <c><anno>List</anno></c> of key-value tuples into a
- tree. The list must not contain duplicate keys.</p>
+ <p>Turns an ordered list <c><anno>List</anno></c> of key-value tuples
+ into a tree. The list must not contain duplicate keys.</p>
</desc>
</func>
+
<func>
<name name="get" arity="2"/>
- <fsummary>Look up a key in a tree, if present</fsummary>
+ <fsummary>Look up a key in a tree, if present.</fsummary>
<desc>
- <p>Retrieves the value stored with <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>.
+ <p>Retrieves the value stored with <c><anno>Key</anno></c> in
+ <c><anno>Tree</anno></c>.
Assumes that the key is present in the tree, crashes
otherwise.</p>
</desc>
</func>
+
<func>
<name name="insert" arity="3"/>
- <fsummary>Insert a new key and value in a tree</fsummary>
+ <fsummary>Insert a new key and value in a tree.</fsummary>
<desc>
- <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> into <c><anno>Tree1</anno></c>;
+ <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c>
+ into <c><anno>Tree1</anno></c> and
returns the new tree. Assumes that the key is not present in
the tree, crashes otherwise.</p>
</desc>
</func>
+
<func>
<name name="is_defined" arity="2"/>
- <fsummary>Test for membership of a tree</fsummary>
+ <fsummary>Test for membership of a tree.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Key</anno></c> is present in <c><anno>Tree</anno></c>,
- otherwise <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Key</anno></c> is present in
+ <c><anno>Tree</anno></c>, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="is_empty" arity="1"/>
- <fsummary>Test for empty tree</fsummary>
+ <fsummary>Test for empty tree.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Tree</anno></c> is an empty tree, and
- <c>false</c> otherwise.</p>
+ <p>Returns <c>true</c> if <c><anno>Tree</anno></c> is an empty tree,
+ othwewise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="iterator" arity="1"/>
- <fsummary>Return an iterator for a tree</fsummary>
+ <fsummary>Return an iterator for a tree.</fsummary>
<desc>
<p>Returns an iterator that can be used for traversing the
- entries of <c><anno>Tree</anno></c>; see <c>next/1</c>. The implementation
+ entries of <c><anno>Tree</anno></c>; see
+ <seealso marker="#next/1"><c>next/1</c></seealso>. The implementation
of this is very efficient; traversing the whole tree using
<c>next/1</c> is only slightly slower than getting the list
- of all elements using <c>to_list/1</c> and traversing that.
+ of all elements using
+ <seealso marker="#to_list/1"><c>to_list/1</c></seealso>
+ 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.</p>
</desc>
</func>
+
<func>
<name name="iterator_from" arity="2"/>
- <fsummary>Return an iterator for a tree starting from specified key</fsummary>
+ <fsummary>Return an iterator for a tree starting from a specified key.
+ </fsummary>
<desc>
<p>Returns an iterator that can be used for traversing the
- entries of <c><anno>Tree</anno></c>; see <c>next/1</c>.
- The difference as compared to the iterator returned by
- <c>iterator/1</c> is that the first key greater than
- or equal to <c><anno>Key</anno></c> is returned.</p>
+ entries of <c><anno>Tree</anno></c>; see
+ <seealso marker="#next/1"><c>next/1</c></seealso>.
+ The difference as compared to the iterator returned by
+ <seealso marker="#iterator/1"><c>iterator/1</c></seealso>
+ is that the first key greater than
+ or equal to <c><anno>Key</anno></c> is returned.</p>
</desc>
</func>
+
<func>
<name name="keys" arity="1"/>
- <fsummary>Return a list of the keys in a tree</fsummary>
+ <fsummary>Return a list of the keys in a tree.</fsummary>
<desc>
<p>Returns the keys in <c><anno>Tree</anno></c> as an ordered list.</p>
</desc>
</func>
+
<func>
<name name="largest" arity="1"/>
- <fsummary>Return largest key and value</fsummary>
+ <fsummary>Return largest key and value.</fsummary>
<desc>
- <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where <c><anno>Key</anno></c> is the largest
- key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is the value associated
- with this key. Assumes that the tree is nonempty.</p>
+ <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where
+ <c><anno>Key</anno></c> is the largest
+ key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is
+ the value associated
+ with this key. Assumes that the tree is not empty.</p>
</desc>
</func>
+
<func>
<name name="lookup" arity="2"/>
- <fsummary>Look up a key in a tree</fsummary>
+ <fsummary>Look up a key in a tree.</fsummary>
<desc>
- <p>Looks up <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>; returns
- <c>{value, <anno>Value</anno>}</c>, or <c>none</c> if <c><anno>Key</anno></c> is not
- present.</p>
+ <p>Looks up <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>.
+ Returns <c>{value, <anno>Value</anno>}</c>, or <c>none</c> if
+ <c><anno>Key</anno></c> is not present.</p>
</desc>
</func>
+
<func>
<name name="map" arity="2"/>
- <fsummary>Return largest key and value</fsummary>
- <desc><p>Maps the function F(<anno>K</anno>, <anno>V1</anno>) -> <anno>V2</anno> to all key-value pairs
- of the tree <c><anno>Tree1</anno></c> and returns a new tree <c><anno>Tree2</anno></c> with the same set of keys
- as <c><anno>Tree1</anno></c> and the new set of values <c><anno>V2</anno></c>.</p>
+ <fsummary>Return largest key and value.</fsummary>
+ <desc>
+ <p>Maps function F(<anno>K</anno>, <anno>V1</anno>) -> <anno>V2</anno>
+ to all key-value pairs of tree <c><anno>Tree1</anno></c>. Returns a
+ new tree <c><anno>Tree2</anno></c> with the same set of keys as
+ <c><anno>Tree1</anno></c> and the new set of values
+ <c><anno>V2</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="next" arity="1"/>
- <fsummary>Traverse a tree with an iterator</fsummary>
+ <fsummary>Traverse a tree with an iterator.</fsummary>
<desc>
- <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Iter2</anno>}</c> where <c><anno>Key</anno></c> is the
- smallest key referred to by the iterator <c><anno>Iter1</anno></c>, and
+ <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>,
+ <anno>Iter2</anno>}</c>, where <c><anno>Key</anno></c> is the
+ smallest key referred to by iterator <c><anno>Iter1</anno></c>, and
<c><anno>Iter2</anno></c> is the new iterator to be used for
traversing the remaining nodes, or the atom <c>none</c> if no
nodes remain.</p>
</desc>
</func>
+
<func>
<name name="size" arity="1"/>
- <fsummary>Return the number of nodes in a tree</fsummary>
+ <fsummary>Return the number of nodes in a tree.</fsummary>
<desc>
<p>Returns the number of nodes in <c><anno>Tree</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="smallest" arity="1"/>
- <fsummary>Return smallest key and value</fsummary>
+ <fsummary>Return smallest key and value.</fsummary>
<desc>
- <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where <c><anno>Key</anno></c> is the smallest
- key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is the value associated
- with this key. Assumes that the tree is nonempty.</p>
+ <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where
+ <c><anno>Key</anno></c> is the smallest
+ key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is
+ the value associated
+ with this key. Assumes that the tree is not empty.</p>
</desc>
</func>
+
<func>
<name name="take_largest" arity="1"/>
- <fsummary>Extract largest key and value</fsummary>
+ <fsummary>Extract largest key and value.</fsummary>
<desc>
- <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the
- largest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c> is the value
- associated with this key, and <c><anno>Tree2</anno></c> is this tree with
- the corresponding node deleted. Assumes that the tree is
- nonempty.</p>
+ <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>,
+ <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the
+ largest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c>
+ is the value associated with this key, and <c><anno>Tree2</anno></c>
+ is this tree with the corresponding node deleted. Assumes that the
+ tree is not empty.</p>
</desc>
</func>
+
<func>
<name name="take_smallest" arity="1"/>
- <fsummary>Extract smallest key and value</fsummary>
+ <fsummary>Extract smallest key and value.</fsummary>
<desc>
- <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the
- smallest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c> is the value
- associated with this key, and <c><anno>Tree2</anno></c> is this tree with
- the corresponding node deleted. Assumes that the tree is
- nonempty.</p>
+ <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>,
+ <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the
+ smallest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c>
+ is the value associated with this key, and <c><anno>Tree2</anno></c>
+ is this tree with the corresponding node deleted. Assumes that the
+ tree is not empty.</p>
</desc>
</func>
+
<func>
<name name="to_list" arity="1"/>
- <fsummary>Convert a tree into a list</fsummary>
+ <fsummary>Convert a tree into a list.</fsummary>
<desc>
<p>Converts a tree into an ordered list of key-value tuples.</p>
</desc>
</func>
+
<func>
<name name="update" arity="3"/>
- <fsummary>Update a key to new value in a tree</fsummary>
+ <fsummary>Update a key to new value in a tree.</fsummary>
<desc>
- <p>Updates <c><anno>Key</anno></c> to value <c><anno>Value</anno></c> in <c><anno>Tree1</anno></c>;
- returns the new tree. Assumes that the key is present in the
- tree.</p>
+ <p>Updates <c><anno>Key</anno></c> to value <c><anno>Value</anno></c>
+ in <c><anno>Tree1</anno></c> and
+ returns the new tree. Assumes that the key is present in the tree.</p>
</desc>
</func>
+
<func>
<name name="values" arity="1"/>
- <fsummary>Return a list of the values in a tree</fsummary>
+ <fsummary>Return a list of the values in a tree.</fsummary>
<desc>
- <p>Returns the values in <c><anno>Tree</anno></c> as an ordered list, sorted
- by their corresponding keys. Duplicates are not removed.</p>
+ <p>Returns the values in <c><anno>Tree</anno></c> as an ordered list,
+ sorted by their corresponding keys. Duplicates are not removed.</p>
</desc>
</func>
</funcs>
<section>
- <title>SEE ALSO</title>
- <p><seealso marker="gb_sets">gb_sets(3)</seealso>,
- <seealso marker="dict">dict(3)</seealso></p>
+ <title>See Also</title>
+ <p><seealso marker="dict"><c>dict(3)</c></seealso>,
+ <seealso marker="gb_sets"><c>gb_sets(3)</c></seealso></p>
</section>
</erlref>