1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>gb_trees</title>
32
<module>gb_trees</module>
33
<modulesummary>General Balanced Trees</modulesummary>
35
<p>An efficient implementation of Prof. Arne Andersson's General
36
Balanced Trees. These have no storage overhead compared to
37
unbalaced binary trees, and their performance is in general
38
better than AVL trees.</p>
42
<title>Data structure</title>
43
<p>Data structure:</p>
46
- {Size, Tree}, where `Tree' is composed of nodes of the form:
47
- {Key, Value, Smaller, Bigger}, and the "empty tree" node:
49
<p>There is no attempt to balance trees after deletions. Since
50
deletions do not increase the height of a tree, this should be OK.</p>
51
<p>Original balance condition <em>h(T) <= ceil(c * log(|T|))</em>
52
has been changed to the similar (but not quite equivalent)
53
condition <em>2 ^ h(T) <= |T| ^ c</em>. This should also be OK.</p>
54
<p>Performance is comparable to the AVL trees in the Erlang book
55
(and faster in general due to less overhead); the difference is
56
that deletion works for these trees, but not for the book's
57
trees. Behaviour is logaritmic (as it should be).</p>
61
<title>DATA TYPES</title>
63
gb_tree() = a GB tree</code>
67
<name>balance(Tree1) -> Tree2</name>
68
<fsummary>Rebalance a tree</fsummary>
70
<v>Tree1 = Tree2 = gb_tree()</v>
73
<p>Rebalances <c>Tree1</c>. Note that this is rarely necessary,
74
but may be motivated when a large number of nodes have been
75
deleted from the tree without further insertions. Rebalancing
76
could then be forced in order to minimise lookup times, since
77
deletion only does not rebalance the tree.</p>
81
<name>delete(Key, Tree1) -> Tree2</name>
82
<fsummary>Remove a node from a tree</fsummary>
85
<v>Tree1 = Tree2 = gb_tree()</v>
88
<p>Removes the node with key <c>Key</c> from <c>Tree1</c>;
89
returns new tree. Assumes that the key is present in the tree,
90
crashes otherwise.</p>
94
<name>delete_any(Key, Tree1) -> Tree2</name>
95
<fsummary>Remove a (possibly non-existing) node from a tree</fsummary>
98
<v>Tree1 = Tree2 = gb_tree()</v>
101
<p>Removes the node with key <c>Key</c> from <c>Tree1</c> if
102
the key is present in the tree, otherwise does nothing;
103
returns new tree.</p>
107
<name>empty() -> Tree</name>
108
<fsummary>Return an empty tree</fsummary>
110
<v>Tree = gb_tree()</v>
113
<p>Returns a new empty tree</p>
117
<name>enter(Key, Val, Tree1) -> Tree2</name>
118
<fsummary>Insert or update key with value in a tree</fsummary>
120
<v>Key = Val = term()</v>
121
<v>Tree1 = Tree2 = gb_tree()</v>
124
<p>Inserts <c>Key</c> with value <c>Val</c> into <c>Tree1</c> if
125
the key is not present in the tree, otherwise updates
126
<c>Key</c> to value <c>Val</c> in <c>Tree1</c>. Returns the
131
<name>from_orddict(List) -> Tree</name>
132
<fsummary>Make a tree from an orddict</fsummary>
134
<v>List = [{Key, Val}]</v>
135
<v> Key = Val = term()</v>
136
<v>Tree = gb_tree()</v>
139
<p>Turns an ordered list <c>List</c> of key-value tuples into a
140
tree. The list must not contain duplicate keys.</p>
144
<name>get(Key, Tree) -> Val</name>
145
<fsummary>Look up a key in a tree, if present</fsummary>
147
<v>Key = Val = term()</v>
148
<v>Tree = gb_tree()</v>
151
<p>Retrieves the value stored with <c>Key</c> in <c>Tree</c>.
152
Assumes that the key is present in the tree, crashes
157
<name>lookup(Key, Tree) -> {value, Val} | none</name>
158
<fsummary>Look up a key in a tree</fsummary>
160
<v>Key = Val = term()</v>
161
<v>Tree = gb_tree()</v>
164
<p>Looks up <c>Key</c> in <c>Tree</c>; returns
165
<c>{value, Val}</c>, or <c>none</c> if <c>Key</c> is not
170
<name>insert(Key, Val, Tree1) -> Tree2</name>
171
<fsummary>Insert a new key and value in a tree</fsummary>
173
<v>Key = Val = term()</v>
174
<v>Tree1 = Tree2 = gb_tree()</v>
177
<p>Inserts <c>Key</c> with value <c>Val</c> into <c>Tree1</c>;
178
returns the new tree. Assumes that the key is not present in
179
the tree, crashes otherwise.</p>
183
<name>is_defined(Key, Tree) -> bool()</name>
184
<fsummary>Test for membership of a tree</fsummary>
186
<v>Tree = gb_tree()</v>
189
<p>Returns <c>true</c> if <c>Key</c> is present in <c>Tree</c>,
190
otherwise <c>false</c>.</p>
194
<name>is_empty(Tree) -> bool()</name>
195
<fsummary>Test for empty tree</fsummary>
197
<v>Tree = gb_tree()</v>
200
<p>Returns <c>true</c> if <c>Tree</c> is an empty tree, and
201
<c>false</c> otherwise.</p>
205
<name>iterator(Tree) -> Iter</name>
206
<fsummary>Return an iterator for a tree</fsummary>
208
<v>Tree = gb_tree()</v>
212
<p>Returns an iterator that can be used for traversing the
213
entries of <c>Tree</c>; see <c>next/1</c>. The implementation
214
of this is very efficient; traversing the whole tree using
215
<c>next/1</c> is only slightly slower than getting the list
216
of all elements using <c>to_list/1</c> and traversing that.
217
The main advantage of the iterator approach is that it does
218
not require the complete list of all elements to be built in
219
memory at one time.</p>
223
<name>keys(Tree) -> [Key]</name>
224
<fsummary>Return a list of the keys in a tree</fsummary>
226
<v>Tree = gb_tree()</v>
230
<p>Returns the keys in <c>Tree</c> as an ordered list.</p>
234
<name>largest(Tree) -> {Key, Val}</name>
235
<fsummary>Return largest key and value</fsummary>
237
<v>Tree = gb_tree()</v>
238
<v>Key = Val = term()</v>
241
<p>Returns <c>{Key, Val}</c>, where <c>Key</c> is the largest
242
key in <c>Tree</c>, and <c>Val</c> is the value associated
243
with this key. Assumes that the tree is nonempty.</p>
247
<name>next(Iter1) -> {Key, Val, Iter2} | none</name>
248
<fsummary>Traverse a tree with an iterator</fsummary>
250
<v>Iter1 = Iter2 = Key = Val = term()</v>
253
<p>Returns <c>{Key, Val, Iter2}</c> where <c>Key</c> is the
254
smallest key referred to by the iterator <c>Iter1</c>, and
255
<c>Iter2</c> is the new iterator to be used for
256
traversing the remaining nodes, or the atom <c>none</c> if no
261
<name>size(Tree) -> int()</name>
262
<fsummary>Return the number of nodes in a tree</fsummary>
264
<v>Tree = gb_tree()</v>
267
<p>Returns the number of nodes in <c>Tree</c>.</p>
271
<name>smallest(Tree) -> {Key, Val}</name>
272
<fsummary>Return smallest key and value</fsummary>
274
<v>Tree = gb_tree()</v>
275
<v>Key = Val = term()</v>
278
<p>Returns <c>{Key, Val}</c>, where <c>Key</c> is the smallest
279
key in <c>Tree</c>, and <c>Val</c> is the value associated
280
with this key. Assumes that the tree is nonempty.</p>
284
<name>take_largest(Tree1) -> {Key, Val, Tree2}</name>
285
<fsummary>Extract largest key and value</fsummary>
287
<v>Tree1 = Tree2 = gb_tree()</v>
288
<v>Key = Val = term()</v>
291
<p>Returns <c>{Key, Val, Tree2}</c>, where <c>Key</c> is the
292
largest key in <c>Tree1</c>, <c>Val</c> is the value
293
associated with this key, and <c>Tree2</c> is this tree with
294
the corresponding node deleted. Assumes that the tree is
299
<name>take_smallest(Tree1) -> {Key, Val, Tree2}</name>
300
<fsummary>Extract smallest key and value</fsummary>
302
<v>Tree1 = Tree2 = gb_tree()</v>
303
<v>Key = Val = term()</v>
306
<p>Returns <c>{Key, Val, Tree2}</c>, where <c>Key</c> is the
307
smallest key in <c>Tree1</c>, <c>Val</c> is the value
308
associated with this key, and <c>Tree2</c> is this tree with
309
the corresponding node deleted. Assumes that the tree is
314
<name>to_list(Tree) -> [{Key, Val}]</name>
315
<fsummary>Convert a tree into a list</fsummary>
317
<v>Tree = gb_tree()</v>
318
<v>Key = Val = term()</v>
321
<p>Converts a tree into an ordered list of key-value tuples.</p>
325
<name>update(Key, Val, Tree1) -> Tree2</name>
326
<fsummary>Update a key to new value in a tree</fsummary>
328
<v>Key = Val = term()</v>
329
<v>Tree1 = Tree2 = gb_tree()</v>
332
<p>Updates <c>Key</c> to value <c>Val</c> in <c>Tree1</c>;
333
returns the new tree. Assumes that the key is present in the
338
<name>values(Tree) -> [Val]</name>
339
<fsummary>Return a list of the values in a tree</fsummary>
341
<v>Tree = gb_tree()</v>
345
<p>Returns the values in <c>Tree</c> as an ordered list, sorted
346
by their corresponding keys. Duplicates are not removed.</p>
352
<title>SEE ALSO</title>
353
<p><seealso marker="gb_sets">gb_sets(3)</seealso>,
354
<seealso marker="dict">dict(3)</seealso></p>