<refentry id="glib-Balanced-Binary-Trees">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Balanced-Binary-Trees.top_of_page">Balanced Binary Trees</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Balanced Binary Trees</refname>
<refpurpose>a sorted collection of key/value pairs optimized for searching
and traversing in order</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Balanced-Binary-Trees.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <link linkend="GTree">GTree</link>;
<link linkend="GTree">GTree</link>*              <link linkend="g-tree-new">g_tree_new</link>                          (<link linkend="GCompareFunc">GCompareFunc</link> key_compare_func);
<link linkend="GTree">GTree</link>*              <link linkend="g-tree-ref">g_tree_ref</link>                          (<link linkend="GTree">GTree</link> *tree);
<link linkend="void">void</link>                <link linkend="g-tree-unref">g_tree_unref</link>                        (<link linkend="GTree">GTree</link> *tree);
<link linkend="GTree">GTree</link>*              <link linkend="g-tree-new-with-data">g_tree_new_with_data</link>                (<link linkend="GCompareDataFunc">GCompareDataFunc</link> key_compare_func,
                                                         <link linkend="gpointer">gpointer</link> key_compare_data);
<link linkend="GTree">GTree</link>*              <link linkend="g-tree-new-full">g_tree_new_full</link>                     (<link linkend="GCompareDataFunc">GCompareDataFunc</link> key_compare_func,
                                                         <link linkend="gpointer">gpointer</link> key_compare_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> key_destroy_func,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> value_destroy_func);
<link linkend="void">void</link>                <link linkend="g-tree-insert">g_tree_insert</link>                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gpointer">gpointer</link> key,
                                                         <link linkend="gpointer">gpointer</link> value);
<link linkend="void">void</link>                <link linkend="g-tree-replace">g_tree_replace</link>                      (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gpointer">gpointer</link> key,
                                                         <link linkend="gpointer">gpointer</link> value);
<link linkend="gint">gint</link>                <link linkend="g-tree-nnodes">g_tree_nnodes</link>                       (<link linkend="GTree">GTree</link> *tree);
<link linkend="gint">gint</link>                <link linkend="g-tree-height">g_tree_height</link>                       (<link linkend="GTree">GTree</link> *tree);
<link linkend="gpointer">gpointer</link>            <link linkend="g-tree-lookup">g_tree_lookup</link>                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> key);
<link linkend="gboolean">gboolean</link>            <link linkend="g-tree-lookup-extended">g_tree_lookup_extended</link>              (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> lookup_key,
                                                         <link linkend="gpointer">gpointer</link> *orig_key,
                                                         <link linkend="gpointer">gpointer</link> *value);
<link linkend="void">void</link>                <link linkend="g-tree-foreach">g_tree_foreach</link>                      (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="GTraverseFunc">GTraverseFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="void">void</link>                <link linkend="g-tree-traverse">g_tree_traverse</link>                     (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="GTraverseFunc">GTraverseFunc</link> traverse_func,
                                                         <link linkend="GTraverseType">GTraverseType</link> traverse_type,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="gboolean">gboolean</link>            (<link linkend="GTraverseFunc">*GTraverseFunc</link>)                    (<link linkend="gpointer">gpointer</link> key,
                                                         <link linkend="gpointer">gpointer</link> value,
                                                         <link linkend="gpointer">gpointer</link> data);
enum                <link linkend="GTraverseType">GTraverseType</link>;
<link linkend="gpointer">gpointer</link>            <link linkend="g-tree-search">g_tree_search</link>                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="GCompareFunc">GCompareFunc</link> search_func,
                                                         <link linkend="gconstpointer">gconstpointer</link> user_data);
<link linkend="gboolean">gboolean</link>            <link linkend="g-tree-remove">g_tree_remove</link>                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> key);
<link linkend="gboolean">gboolean</link>            <link linkend="g-tree-steal">g_tree_steal</link>                        (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> key);
<link linkend="void">void</link>                <link linkend="g-tree-destroy">g_tree_destroy</link>                      (<link linkend="GTree">GTree</link> *tree);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Balanced-Binary-Trees.description" role="desc">
<title role="desc.title">Description</title>
<para>
The <link linkend="GTree"><type>GTree</type></link> structure and its associated functions provide a sorted collection
of key/value pairs optimized for searching and traversing in order.
</para>
<para>
To create a new <link linkend="GTree"><type>GTree</type></link> use <link linkend="g-tree-new"><function>g_tree_new()</function></link>.
</para>
<para>
To insert a key/value pair into a <link linkend="GTree"><type>GTree</type></link> use <link linkend="g-tree-insert"><function>g_tree_insert()</function></link>.
</para>
<para>
To lookup the value corresponding to a given key, use <link linkend="g-tree-lookup"><function>g_tree_lookup()</function></link> and
<link linkend="g-tree-lookup-extended"><function>g_tree_lookup_extended()</function></link>.
</para>
<para>
To find out the number of nodes in a <link linkend="GTree"><type>GTree</type></link>, use <link linkend="g-tree-nnodes"><function>g_tree_nnodes()</function></link>.
To get the height of a <link linkend="GTree"><type>GTree</type></link>, use <link linkend="g-tree-height"><function>g_tree_height()</function></link>.
</para>
<para>
To traverse a <link linkend="GTree"><type>GTree</type></link>, calling a function for each node visited in the
traversal, use <link linkend="g-tree-foreach"><function>g_tree_foreach()</function></link>.
</para>
<para>
To remove a key/value pair use <link linkend="g-tree-remove"><function>g_tree_remove()</function></link>.
</para>
<para>
To destroy a <link linkend="GTree"><type>GTree</type></link>, use <link linkend="g-tree-destroy"><function>g_tree_destroy()</function></link>.
</para>
</refsect1>

<refsect1 id="glib-Balanced-Binary-Trees.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GTree" role="struct">
<title>GTree</title>
<indexterm zone="GTree"><primary sortas="Tree">GTree</primary></indexterm><programlisting>typedef struct _GTree GTree;</programlisting>
<para>
The <structname>GTree</structname> struct is an opaque data structure representing a
<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
It should be accessed only by using the following functions.
</para></refsect2>
<refsect2 id="g-tree-new" role="function">
<title>g_tree_new ()</title>
<indexterm zone="g-tree-new"><primary sortas="tree_new">g_tree_new</primary></indexterm><programlisting><link linkend="GTree">GTree</link>*              g_tree_new                          (<link linkend="GCompareFunc">GCompareFunc</link> key_compare_func);</programlisting>
<para>
Creates a new <link linkend="GTree"><type>GTree</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>key_compare_func</parameter>&#160;:</term>
<listitem><simpara> the function used to order the nodes in the <link linkend="GTree"><type>GTree</type></link>.
  It should return values similar to the standard <link linkend="strcmp"><function>strcmp()</function></link> function -
  0 if the two arguments are equal, a negative value if the first argument 
  comes before the second, or a positive value if the first argument comes 
  after the second.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-ref" role="function" condition="since:2.22">
<title>g_tree_ref ()</title>
<indexterm zone="g-tree-ref" role="2.22"><primary sortas="tree_ref">g_tree_ref</primary></indexterm><programlisting><link linkend="GTree">GTree</link>*              g_tree_ref                          (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Increments the reference count of <parameter>tree</parameter> by one.  It is safe to call
this function from any thread.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the passed in <link linkend="GTree"><type>GTree</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-tree-unref" role="function" condition="since:2.22">
<title>g_tree_unref ()</title>
<indexterm zone="g-tree-unref" role="2.22"><primary sortas="tree_unref">g_tree_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_tree_unref                        (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Decrements the reference count of <parameter>tree</parameter> 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 <parameter>tree</parameter> will be
released.
</para>
<para>
It is safe to call this function from any thread.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-tree-new-with-data" role="function">
<title>g_tree_new_with_data ()</title>
<indexterm zone="g-tree-new-with-data"><primary sortas="tree_new_with_data">g_tree_new_with_data</primary></indexterm><programlisting><link linkend="GTree">GTree</link>*              g_tree_new_with_data                (<link linkend="GCompareDataFunc">GCompareDataFunc</link> key_compare_func,
                                                         <link linkend="gpointer">gpointer</link> key_compare_data);</programlisting>
<para>
Creates a new <link linkend="GTree"><type>GTree</type></link> with a comparison function that accepts user data.
See <link linkend="g-tree-new"><function>g_tree_new()</function></link> for more details.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>key_compare_func</parameter>&#160;:</term>
<listitem><simpara> <link linkend="qsort"><function>qsort()</function></link>-style comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key_compare_data</parameter>&#160;:</term>
<listitem><simpara> data to pass to comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-new-full" role="function">
<title>g_tree_new_full ()</title>
<indexterm zone="g-tree-new-full"><primary sortas="tree_new_full">g_tree_new_full</primary></indexterm><programlisting><link linkend="GTree">GTree</link>*              g_tree_new_full                     (<link linkend="GCompareDataFunc">GCompareDataFunc</link> key_compare_func,
                                                         <link linkend="gpointer">gpointer</link> key_compare_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> key_destroy_func,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> value_destroy_func);</programlisting>
<para>
Creates a new <link linkend="GTree"><type>GTree</type></link> like <link linkend="g-tree-new"><function>g_tree_new()</function></link> and allows to specify functions 
to free the memory allocated for the key and value that get called when 
removing the entry from the <link linkend="GTree"><type>GTree</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>key_compare_func</parameter>&#160;:</term>
<listitem><simpara> <link linkend="qsort"><function>qsort()</function></link>-style comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key_compare_data</parameter>&#160;:</term>
<listitem><simpara> data to pass to comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key_destroy_func</parameter>&#160;:</term>
<listitem><simpara> a function to free the memory allocated for the key 
  used when removing the entry from the <link linkend="GTree"><type>GTree</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if you don't
  want to supply such a function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value_destroy_func</parameter>&#160;:</term>
<listitem><simpara> a function to free the memory allocated for the 
  value used when removing the entry from the <link linkend="GTree"><type>GTree</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if you 
  don't want to supply such a function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-insert" role="function">
<title>g_tree_insert ()</title>
<indexterm zone="g-tree-insert"><primary sortas="tree_insert">g_tree_insert</primary></indexterm><programlisting><link linkend="void">void</link>                g_tree_insert                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gpointer">gpointer</link> key,
                                                         <link linkend="gpointer">gpointer</link> value);</programlisting>
<para>
Inserts a key/value pair into a <link linkend="GTree"><type>GTree</type></link>. If the given key already exists 
in the <link linkend="GTree"><type>GTree</type></link> its corresponding value is set to the new value. If you 
supplied a value_destroy_func when creating the <link linkend="GTree"><type>GTree</type></link>, the old value is 
freed using that function. If you supplied a <parameter>key_destroy_func</parameter> when 
creating the <link linkend="GTree"><type>GTree</type></link>, the passed key is freed using that function.
</para>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> the value corresponding to the key.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-replace" role="function">
<title>g_tree_replace ()</title>
<indexterm zone="g-tree-replace"><primary sortas="tree_replace">g_tree_replace</primary></indexterm><programlisting><link linkend="void">void</link>                g_tree_replace                      (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gpointer">gpointer</link> key,
                                                         <link linkend="gpointer">gpointer</link> value);</programlisting>
<para>
Inserts a new key and value into a <link linkend="GTree"><type>GTree</type></link> similar to <link linkend="g-tree-insert"><function>g_tree_insert()</function></link>. 
The difference is that if the key already exists in the <link linkend="GTree"><type>GTree</type></link>, it gets 
replaced by the new key. If you supplied a <parameter>value_destroy_func</parameter> when 
creating the <link linkend="GTree"><type>GTree</type></link>, the old value is freed using that function. If you 
supplied a <parameter>key_destroy_func</parameter> when creating the <link linkend="GTree"><type>GTree</type></link>, the old key is 
freed using that function. 
</para>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> the value corresponding to the key.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-nnodes" role="function">
<title>g_tree_nnodes ()</title>
<indexterm zone="g-tree-nnodes"><primary sortas="tree_nnodes">g_tree_nnodes</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_tree_nnodes                       (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Gets the number of nodes in a <link linkend="GTree"><type>GTree</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of nodes in the <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-height" role="function">
<title>g_tree_height ()</title>
<indexterm zone="g-tree-height"><primary sortas="tree_height">g_tree_height</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_tree_height                       (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Gets the height of a <link linkend="GTree"><type>GTree</type></link>.
</para>
<para>
If the <link linkend="GTree"><type>GTree</type></link> contains no nodes, the height is 0.
If the <link linkend="GTree"><type>GTree</type></link> contains only one root node the height is 1.
If the root node has children the height is 2, etc.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the height of the <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-lookup" role="function">
<title>g_tree_lookup ()</title>
<indexterm zone="g-tree-lookup"><primary sortas="tree_lookup">g_tree_lookup</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_tree_lookup                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Gets the value corresponding to the given key. Since a <link linkend="GTree"><type>GTree</type></link> is 
automatically balanced as key/value pairs are added, key lookup is very 
fast.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key to look up.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the value corresponding to the key, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the key was
not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-lookup-extended" role="function">
<title>g_tree_lookup_extended ()</title>
<indexterm zone="g-tree-lookup-extended"><primary sortas="tree_lookup_extended">g_tree_lookup_extended</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_tree_lookup_extended              (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> lookup_key,
                                                         <link linkend="gpointer">gpointer</link> *orig_key,
                                                         <link linkend="gpointer">gpointer</link> *value);</programlisting>
<para>
Looks up a key in the <link linkend="GTree"><type>GTree</type></link>, returning the original key and the
associated value and a <link linkend="gboolean"><type>gboolean</type></link> which is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found. This 
is useful if you need to free the memory allocated for the original key, 
for example before calling <link linkend="g-tree-remove"><function>g_tree_remove()</function></link>.</para>
<variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>lookup_key</parameter>&#160;:</term>
<listitem><simpara> the key to look up.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>orig_key</parameter>&#160;:</term>
<listitem><simpara> returns the original key.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> returns the value associated with the key.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found in the <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-foreach" role="function">
<title>g_tree_foreach ()</title>
<indexterm zone="g-tree-foreach"><primary sortas="tree_foreach">g_tree_foreach</primary></indexterm><programlisting><link linkend="void">void</link>                g_tree_foreach                      (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="GTraverseFunc">GTraverseFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Calls the given function for each of the key/value pairs in the <link linkend="GTree"><type>GTree</type></link>.
The function is passed the key and value of each pair, and the given
<parameter>data</parameter> parameter. The tree is traversed in sorted order.
</para>
<para>
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 <link linkend="GTraverseFunc"><type>GTraverseFunc</type></link> as you walk over 
the tree, then walk the list and remove each item.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call for each node visited. If this function
  returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, the traversal is stopped.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data to pass to the function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-traverse" role="function" condition="deprecated">
<title>g_tree_traverse ()</title>
<indexterm zone="g-tree-traverse" role="deprecated"><primary sortas="tree_traverse">g_tree_traverse</primary></indexterm><programlisting><link linkend="void">void</link>                g_tree_traverse                     (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="GTraverseFunc">GTraverseFunc</link> traverse_func,
                                                         <link linkend="GTraverseType">GTraverseType</link> traverse_type,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<warning><para><literal>g_tree_traverse</literal> 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 <link linkend="g-tree-foreach"><function>g_tree_foreach()</function></link> 
instead. If you really need to visit nodes in a different order, consider
using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.</para></warning>
<para>
Calls the given function for each node in the <link linkend="GTree"><type>GTree</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>traverse_func</parameter>&#160;:</term>
<listitem><simpara> the function to call for each node visited. If this 
  function returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, the traversal is stopped.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>traverse_type</parameter>&#160;:</term>
<listitem><simpara> the order in which nodes are visited, one of <link linkend="G-IN-ORDER--CAPS"><literal>G_IN_ORDER</literal></link>,
  <link linkend="G-PRE-ORDER--CAPS"><literal>G_PRE_ORDER</literal></link> and <link linkend="G-POST-ORDER--CAPS"><literal>G_POST_ORDER</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data to pass to the function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GTraverseFunc" role="function">
<title>GTraverseFunc ()</title>
<indexterm zone="GTraverseFunc"><primary sortas="TraverseFunc">GTraverseFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GTraverseFunc)                    (<link linkend="gpointer">gpointer</link> key,
                                                         <link linkend="gpointer">gpointer</link> value,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <link linkend="g-tree-traverse"><function>g_tree_traverse()</function></link>.
It is passed the key and value of each node, together with
the <parameter>user_data</parameter> parameter passed to <link linkend="g-tree-traverse"><function>g_tree_traverse()</function></link>.
If the function returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, the traversal is stopped.
</para><variablelist role="params">
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara>a key of a <link linkend="GTree"><type>GTree</type></link> node.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the value corresponding to the key.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>user data passed to <link linkend="g-tree-traverse"><function>g_tree_traverse()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE to stop the traversal.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GTraverseType" role="enum">
<title>enum GTraverseType</title>
<indexterm zone="GTraverseType"><primary sortas="TraverseType">GTraverseType</primary></indexterm><programlisting>typedef enum
{
  G_IN_ORDER,
  G_PRE_ORDER,
  G_POST_ORDER,
  G_LEVEL_ORDER
} GTraverseType;
</programlisting>
<para>
Specifies the type of traveral performed by <link linkend="g-tree-traverse"><function>g_tree_traverse()</function></link>,
<link linkend="g-node-traverse"><function>g_node_traverse()</function></link> and <link linkend="g-node-find"><function>g_node_find()</function></link>.
</para><variablelist role="enum">
<varlistentry id="G-IN-ORDER--CAPS" role="constant">
<term><literal>G_IN_ORDER</literal></term>
<listitem><simpara>vists a node's left child first, then the node itself, then its
  right child. This is the one to use if you want the output sorted according
  to the compare function.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-PRE-ORDER--CAPS" role="constant">
<term><literal>G_PRE_ORDER</literal></term>
<listitem><simpara>visits a node, then its children.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-POST-ORDER--CAPS" role="constant">
<term><literal>G_POST_ORDER</literal></term>
<listitem><simpara>visits the node's children, then the node itself.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-LEVEL-ORDER--CAPS" role="constant">
<term><literal>G_LEVEL_ORDER</literal></term>
<listitem><simpara>is not implemented for
  <link linkend="glib-Balanced-Binary-Trees">Balanced Binary Trees</link>.
  For <link linkend="glib-N-ary-Trees">N-ary Trees</link>, it vists the root
  node first, then its children, then its grandchildren, and so on. Note that
  this is less efficient than the other orders.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-search" role="function">
<title>g_tree_search ()</title>
<indexterm zone="g-tree-search"><primary sortas="tree_search">g_tree_search</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_tree_search                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="GCompareFunc">GCompareFunc</link> search_func,
                                                         <link linkend="gconstpointer">gconstpointer</link> user_data);</programlisting>
<para>
Searches a <link linkend="GTree"><type>GTree</type></link> using <parameter>search_func</parameter>.
</para>
<para>
The <parameter>search_func</parameter> is called with a pointer to the key of a key/value pair in 
the tree, and the passed in <parameter>user_data</parameter>. If <parameter>search_func</parameter> returns 0 for a 
key/value pair, then <link linkend="g-tree-search-func"><function>g_tree_search_func()</function></link> will return the value of that 
pair. If <parameter>search_func</parameter> returns -1,  searching will proceed among the 
key/value pairs that have a smaller key; if <parameter>search_func</parameter> returns 1, 
searching will proceed among the key/value pairs that have a larger key.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>search_func</parameter>&#160;:</term>
<listitem><simpara> a function used to search the <link linkend="GTree"><type>GTree</type></link>. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> the data passed as the second argument to the <parameter>search_func</parameter> 
function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the value corresponding to the found key, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the key 
was not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-remove" role="function">
<title>g_tree_remove ()</title>
<indexterm zone="g-tree-remove"><primary sortas="tree_remove">g_tree_remove</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_tree_remove                       (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Removes a key/value pair from a <link linkend="GTree"><type>GTree</type></link>.
</para>
<para>
If the <link linkend="GTree"><type>GTree</type></link> was created using <link linkend="g-tree-new-full"><function>g_tree_new_full()</function></link>, 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 <link linkend="GTree"><type>GTree</type></link>, the function does nothing.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found (prior to 2.8, this function returned 
  nothing)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-steal" role="function">
<title>g_tree_steal ()</title>
<indexterm zone="g-tree-steal"><primary sortas="tree_steal">g_tree_steal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_tree_steal                        (<link linkend="GTree">GTree</link> *tree,
                                                         <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Removes a key and its associated value from a <link linkend="GTree"><type>GTree</type></link> without calling 
the key and value destroy functions.
</para>
<para>
If the key does not exist in the <link linkend="GTree"><type>GTree</type></link>, the function does nothing.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found (prior to 2.8, this function returned 
   nothing)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-tree-destroy" role="function">
<title>g_tree_destroy ()</title>
<indexterm zone="g-tree-destroy"><primary sortas="tree_destroy">g_tree_destroy</primary></indexterm><programlisting><link linkend="void">void</link>                g_tree_destroy                      (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Removes all keys and values from the <link linkend="GTree"><type>GTree</type></link> and decreases its
reference count by one. If keys and/or values are dynamically
allocated, you should either free them first or create the <link linkend="GTree"><type>GTree</type></link>
using <link linkend="g-tree-new-full"><function>g_tree_new_full()</function></link>.  In the latter case the destroy functions
you supplied will be called on all keys and values before destroying
the <link linkend="GTree"><type>GTree</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>tree</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTree"><type>GTree</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
