Functions
g_tree_ref ()
GTree *
g_tree_ref (GTree *tree);
Increments the reference count of tree
by one.
It is safe to call this function from any thread.
Returns
the passed in GTree
Since: 2.22
g_tree_unref ()
void
g_tree_unref (GTree *tree);
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.
Since: 2.22
g_tree_insert ()
void
g_tree_insert (GTree *tree,
gpointer key,
gpointer 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.
g_tree_replace ()
void
g_tree_replace (GTree *tree,
gpointer key,
gpointer 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.
g_tree_nnodes ()
gint
g_tree_nnodes (GTree *tree);
Gets the number of nodes in a GTree.
Returns
the number of nodes in tree
g_tree_height ()
gint
g_tree_height (GTree *tree);
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.
Returns
the height of tree
g_tree_lookup ()
gpointer
g_tree_lookup (GTree *tree,
gconstpointer 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).
Returns
the value corresponding to the key, or NULL
if the key was not found
g_tree_lookup_extended ()
gboolean
g_tree_lookup_extended (GTree *tree,
gconstpointer lookup_key,
gpointer *orig_key,
gpointer *value);
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().
Returns
TRUE if the key was found in the GTree
g_tree_foreach ()
void
g_tree_foreach (GTree *tree,
GTraverseFunc func,
gpointer user_data);
Calls the given function for each of the key/value pairs in the GTree.
The function is passed the key and value of each pair, and the given
data
parameter. The tree is traversed in sorted order.
The tree may not be modified while iterating over it (you can't
add/remove items). To remove all items matching a predicate, you need
to add each item to a list in your GTraverseFunc as you walk over
the tree, then walk the list and remove each item.
g_tree_traverse ()
void
g_tree_traverse (GTree *tree,
GTraverseFunc traverse_func,
GTraverseType traverse_type,
gpointer user_data);
g_tree_traverse has been deprecated since version 2.2 and should not be used in newly-written code.
The order of a balanced tree is somewhat arbitrary.
If you just want to visit all nodes in sorted order, use
g_tree_foreach() instead. If you really need to visit nodes in
a different order, consider using an n-ary tree.
Calls the given function for each node in the GTree.
g_tree_search ()
gpointer
g_tree_search (GTree *tree,
GCompareFunc search_func,
gconstpointer user_data);
Searches a GTree using search_func
.
The search_func
is called with a pointer to the key of a key/value
pair in the tree, and the passed in user_data
. If search_func
returns
0 for a key/value pair, then the corresponding value is returned as
the result of g_tree_search(). If search_func
returns -1, searching
will proceed among the key/value pairs that have a smaller key; if
search_func
returns 1, searching will proceed among the key/value
pairs that have a larger key.
Returns
the value corresponding to the found key, or NULL
if the key was not found
g_tree_remove ()
gboolean
g_tree_remove (GTree *tree,
gconstpointer 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.
Returns
TRUE if the key was found (prior to 2.8, this function
returned nothing)
g_tree_steal ()
gboolean
g_tree_steal (GTree *tree,
gconstpointer 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.
Returns
TRUE if the key was found (prior to 2.8, this function
returned nothing)
g_tree_destroy ()
void
g_tree_destroy (GTree *tree);
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.