![]() |
![]() |
![]() |
![]() |
<GTree>
The GTree struct is an opaque data structure representing a [balanced binary tree][glib-Balanced-Binary-Trees]. It should be accessed only by using the following functions.
(define-values () (tree:destroy self))
Removes all keys and values from the GTree and decreases its
reference count by one. If keys and/or values are dynamically
allocated, you should either free them first or create the GTree
using g_tree_new_full()
. In the latter case the destroy functions
you supplied will be called on all keys and values before destroying
the GTree.
(define-values (%return) (tree:height self))
Gets the height of a GTree.
If the GTree contains no nodes, the height is 0. If the GTree contains only one root node the height is 1. If the root node has children the height is 2, etc.
(define-values () (tree:insert self key value))
Inserts a key/value pair into a GTree.
If the given key already exists in the GTree its corresponding value
is set to the new value. If you supplied a value_destroy_func
when
creating the GTree, the old value is freed using that function. If
you supplied a key_destroy_func
when creating the GTree, the passed
key is freed using that function.
The tree is automatically 'balanced' as new key/value pairs are added, so that the distance from the root to every leaf is as small as possible. The cost of maintaining a balanced tree while inserting new key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)).
(define-values (%return) (tree:lookup self key))
Gets the value corresponding to the given key. Since a GTree is automatically balanced as key/value pairs are added, key lookup is O(log n) (where n is the number of key/value pairs in the tree).
(define-values (%return orig-key value) (tree:lookup-extended self lookup-key))
Looks up a key in the GTree, returning the original key and the
associated value. This is useful if you need to free the memory
allocated for the original key, for example before calling
g_tree_remove()
.
(define-values (%return) (tree:ref self))
Increments the reference count of tree
by one.
It is safe to call this function from any thread.
(define-values (%return) (tree:remove? self key))
Removes a key/value pair from a GTree.
If the GTree was created using g_tree_new_full()
, the key and value
are freed using the supplied destroy functions, otherwise you have to
make sure that any dynamically allocated values are freed yourself.
If the key does not exist in the GTree, the function does nothing.
The cost of maintaining a balanced tree while removing a key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)).
(define-values () (tree:replace self key value))
Inserts a new key and value into a GTree similar to g_tree_insert()
.
The difference is that if the key already exists in the GTree, it gets
replaced by the new key. If you supplied a value_destroy_func
when
creating the GTree, the old value is freed using that function. If you
supplied a key_destroy_func
when creating the GTree, the old key is
freed using that function.
The tree is automatically 'balanced' as new key/value pairs are added, so that the distance from the root to every leaf is as small as possible.
(define-values (%return) (tree:steal? self key))
Removes a key and its associated value from a GTree without calling the key and value destroy functions.
If the key does not exist in the GTree, the function does nothing.
(define-values () (tree:unref self))
Decrements the reference count of tree
by one.
If the reference count drops to 0, all keys and values will
be destroyed (if destroy functions were specified) and all
memory allocated by tree
will be released.
It is safe to call this function from any thread.