From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/gb_trees.xml | 216 +++++++++++++--------------------------- 1 file changed, 67 insertions(+), 149 deletions(-) (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 index 94f40c28bd..65c866efbe 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -4,7 +4,7 @@
- 20012010 + 20012011 Ericsson AB. All Rights Reserved. @@ -57,20 +57,22 @@ trees. Behaviour is logarithmic (as it should be).

-
- DATA TYPES - -gb_tree() = a GB tree -
+ + + gb_tree() +

A GB tree.

 + + + +

A GB tree iterator.

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

Rebalances Tree1. Note that this is rarely necessary, +

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 @@ -78,139 +80,97 @@ gb_tree() = a GB 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; +

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 +

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 +

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 + 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 +

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. +

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 +

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; +

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, +

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 +

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 + 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. @@ -220,141 +180,99 @@ gb_tree() = a GB tree - 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.

+

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 +

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.

+

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 +

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.

+

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 +

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 +

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 +

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; +

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 +

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

 -- cgit v1.2.3