<GTree>

<GTree>

Description

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.

Functions

destroy

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

Parameters

tree

a GTree

Passed as self

height

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

Parameters

tree

a GTree

Passed as self

insert

(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)).

Parameters

tree

a GTree

Passed as self

key

the key to insert

Passed as key

value

the value corresponding to the key

Passed as value

lookup

(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).

Parameters

tree

a GTree

Passed as self

key

the key to look up

Passed as key

lookup-extended

(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().

Parameters

tree

a GTree

Passed as self

lookup_key

the key to look up

Passed as lookup-key

orig_key

returns the original key

Passed as orig-key

value

returns the value associated with the key

Passed as value

nnodes

(define-values (%return) (tree:nnodes self))

Gets the number of nodes in a GTree.

Parameters

tree

a GTree

Passed as self

ref

(define-values (%return) (tree:ref self))

Increments the reference count of tree by one.

It is safe to call this function from any thread.

Parameters

tree

a GTree

Passed as self

remove?

(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)).

Parameters

tree

a GTree

Passed as self

key

the key to remove

Passed as key

remove-all

(define-values () (tree:remove-all self))

Undocumented

Parameters

tree

Passed as self

replace

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

Parameters

tree

a GTree

Passed as self

key

the key to insert

Passed as key

value

the value corresponding to the key

Passed as value

steal?

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

Parameters

tree

a GTree

Passed as self

key

the key to remove

Passed as key

unref

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

Parameters

tree

a GTree

Passed as self

tree:new-full

(define-values
  (%return)
  (tree:new-full
    key-compare-func
    key-compare-data
    key-destroy-func
    value-destroy-func))

Undocumented

Parameters

key_compare_func

Passed as key-compare-func

key_compare_data

Passed as key-compare-data

key_destroy_func

Passed as key-destroy-func

value_destroy_func

Passed as value-destroy-func