<refentry id="glib-Balanced-Binary-Trees">
<refmeta>
<refentrytitle>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><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <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-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);
void        <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);
void        <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);
void        <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);
void        <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);
void        <link linkend="g-tree-remove">g_tree_remove</link>                   (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="gconstpointer">gconstpointer</link> key);
void        <link linkend="g-tree-steal">g_tree_steal</link>                    (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="gconstpointer">gconstpointer</link> key);
void        <link linkend="g-tree-destroy">g_tree_destroy</link>                  (<link linkend="GTree">GTree</link> *tree);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The <link linkend="GTree">GTree</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">GTree</link> use <link linkend="g-tree-new">g_tree_new</link>().
</para>
<para>
To insert a key/value pair into a <link linkend="GTree">GTree</link> use <link linkend="g-tree-insert">g_tree_insert</link>().
</para>
<para>
To lookup the value corresponding to a given key, use <link linkend="g-tree-lookup">g_tree_lookup</link>() and
<link linkend="g-tree-lookup-extended">g_tree_lookup_extended</link>().
</para>
<para>
To find out the number of nodes in a <link linkend="GTree">GTree</link>, use <link linkend="g-tree-nnodes">g_tree_nnodes</link>().
To get the height of a <link linkend="GTree">GTree</link>, use <link linkend="g-tree-height">g_tree_height</link>().
</para>
<para>
To traverse a <link linkend="GTree">GTree</link>, calling a function for each node visited in the
traversal, use <link linkend="g-tree-foreach">g_tree_foreach</link>().
</para>
<para>
To remove a key/value pair use <link linkend="g-tree-remove">g_tree_remove</link>().
</para>
<para>
To destroy a <link linkend="GTree">GTree</link>, use <link linkend="g-tree-destroy">g_tree_destroy</link>().
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GTree">struct GTree</title>
<programlisting>struct 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>
<title><anchor id="g-tree-new">g_tree_new ()</title>
<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">GTree</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key_compare_func</parameter>&nbsp;:</entry>
<entry> the function used to order the nodes in the <link linkend="GTree">GTree</link>.
  It should return values similar to the standard 
  <function><link linkend="strcmp">strcmp</link>()</function> 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.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-new-with-data">g_tree_new_with_data ()</title>
<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">GTree</link> with a comparison function that accepts user data.
See <link linkend="g-tree-new">g_tree_new</link>() for more details.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key_compare_func</parameter>&nbsp;:</entry>
<entry> <function><link linkend="qsort">qsort</link>()</function>-style comparison function.
</entry></row>
<row><entry align="right"><parameter>key_compare_data</parameter>&nbsp;:</entry>
<entry> data to pass to comparison function.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-new-full">g_tree_new_full ()</title>
<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">GTree</link> like <link linkend="g-tree-new">g_tree_new</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">GTree</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key_compare_func</parameter>&nbsp;:</entry>
<entry> <function><link linkend="qsort">qsort</link>()</function>-style comparison function.
</entry></row>
<row><entry align="right"><parameter>key_compare_data</parameter>&nbsp;:</entry>
<entry> data to pass to comparison function.
</entry></row>
<row><entry align="right"><parameter>key_destroy_func</parameter>&nbsp;:</entry>
<entry> a function to free the memory allocated for the key 
  used when removing the entry from the <link linkend="GTree">GTree</link> or <literal>NULL</literal> if you don't
  want to supply such a function.
</entry></row>
<row><entry align="right"><parameter>value_destroy_func</parameter>&nbsp;:</entry>
<entry> a function to free the memory allocated for the 
  value used when removing the entry from the <link linkend="GTree">GTree</link> or <literal>NULL</literal> if you 
  don't want to supply such a function.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-insert">g_tree_insert ()</title>
<programlisting>void        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">GTree</link>. If the given key already exists 
in the <link linkend="GTree">GTree</link> its corresponding value is set to the new value. If you 
supplied a value_destroy_func when creating the <link linkend="GTree">GTree</link>, the old value is 
freed using that function. If you supplied a <parameter>key_destroy_func</parameter> when 
creating the <link linkend="GTree">GTree</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="Gtree">Gtree</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to insert.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> the value corresponding to the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-replace">g_tree_replace ()</title>
<programlisting>void        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">GTree</link> similar to <link linkend="g-tree-insert">g_tree_insert</link>(). 
The difference is that if the key already exists in the <link linkend="GTree">GTree</link>, it gets 
replaced by the new key. If you supplied a <parameter>value_destroy_func</parameter> when 
creating the <link linkend="GTree">GTree</link>, the old value is freed using that function. If you 
supplied a <parameter>key_destroy_func</parameter> when creating the <link linkend="GTree">GTree</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="Gtree">Gtree</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to insert.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> the value corresponding to the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-nnodes">g_tree_nnodes ()</title>
<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">GTree</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the number of nodes in the <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-height">g_tree_height ()</title>
<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">GTree</link>.
</para>
<para>
If the <link linkend="GTree">GTree</link> contains no nodes, the height is 0.
If the <link linkend="GTree">GTree</link> contains only one root node the height is 1.
If the root node has children the height is 2, etc.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the height of the <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-lookup">g_tree_lookup ()</title>
<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">GTree</link> is 
automatically balanced as key/value pairs are added, key lookup is very 
fast.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to look up.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the value corresponding to the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-lookup-extended">g_tree_lookup_extended ()</title>
<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">GTree</link>, returning the original key and the
associated value and a <link linkend="gboolean">gboolean</link> which is <literal>TRUE</literal> 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">g_tree_remove</link>().</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><parameter>lookup_key</parameter>&nbsp;:</entry>
<entry> the key to look up.
</entry></row>
<row><entry align="right"><parameter>orig_key</parameter>&nbsp;:</entry>
<entry> returns the original key.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> returns the value associated with the key.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the key was found in the <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-foreach">g_tree_foreach ()</title>
<programlisting>void        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">GTree</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">GTraverseFunc</link> as you walk over 
the tree, then walk the list and remove each item.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry> the function to call for each node visited. If this function
  returns <literal>TRUE</literal>, the traversal is stopped.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to the function.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-traverse">g_tree_traverse ()</title>
<programlisting>void        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> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Calls the given function for each node in the <link linkend="GTree">GTree</link>. This function is
deprecated, since 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">g_tree_foreach</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>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><parameter>traverse_func</parameter>&nbsp;:</entry>
<entry> the function to call for each node visited. If this 
  function returns <literal>TRUE</literal>, the traversal is stopped.
</entry></row>
<row><entry align="right"><parameter>traverse_type</parameter>&nbsp;:</entry>
<entry> the order in which nodes are visited, one of <literal>G_IN_ORDER</literal>,
  <literal>G_PRE_ORDER</literal> and <literal>G_POST_ORDER</literal>.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to the function.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GTraverseFunc">GTraverseFunc ()</title>
<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">g_tree_traverse</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">g_tree_traverse</link>().
If the function returns <literal>TRUE</literal>, the traversal is stopped.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry>a key of a <link linkend="GTree">GTree</link> node.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>the value corresponding to the key.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>user data passed to <link linkend="g-tree-traverse">g_tree_traverse</link>().
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> to stop the traversal.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GTraverseType">enum GTraverseType</title>
<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">g_tree_traverse</link>(),
<link linkend="g-node-traverse">g_node_traverse</link>() and <link linkend="g-node-find">g_node_find</link>().
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_IN_ORDER</literal></entry>
<entry>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.
</entry>
</row>
<row>
<entry><literal>G_PRE_ORDER</literal></entry>
<entry>visits a node, then its children.
</entry>
</row>
<row>
<entry><literal>G_POST_ORDER</literal></entry>
<entry>visits the node's children, then the node itself.
</entry>
</row>
<row>
<entry><literal>G_LEVEL_ORDER</literal></entry>
<entry>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.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-search">g_tree_search ()</title>
<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">GTree</link> using an alternative form of the comparison function.
</para>
<para>
This function is not as useful as it sounds.
It allows you to use a different function for performing the lookup of
a key. However, since the tree is ordered according to the <parameter>key_compare_func</parameter>
function passed to <link linkend="g-tree-new">g_tree_new</link>(), the function you pass to <link linkend="g-tree-search">g_tree_search</link>() 
must return exactly the same value as would be returned by the comparison 
function, for each pair of tree nodes, or the search will not work.
</para>
<para>
To search for a specific value, you can use <link linkend="g-tree-foreach">g_tree_foreach</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><parameter>search_func</parameter>&nbsp;:</entry>
<entry> the comparison function used to search the <link linkend="GTree">GTree</link>. 
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> the data passed as the second argument to the <parameter>search_func</parameter> 
function.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the value corresponding to the found key, or <literal>NULL</literal> if the key 
is not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-remove">g_tree_remove ()</title>
<programlisting>void        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">GTree</link>.
</para>
<para>
If the <link linkend="GTree">GTree</link> was created using <link linkend="g-tree-new-full">g_tree_new_full</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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="Gtree">Gtree</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to remove.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-steal">g_tree_steal ()</title>
<programlisting>void        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">GTree</link> without calling 
the key and value destroy functions.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="Gtree">Gtree</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to remove.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-destroy">g_tree_destroy ()</title>
<programlisting>void        g_tree_destroy                  (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Destroys the <link linkend="GTree">GTree</link>. If keys and/or values are dynamically allocated, you 
should either free them first or create the <link linkend="GTree">GTree</link> using <link linkend="g-tree-new-full">g_tree_new_full</link>().
In the latter case the destroy functions you supplied will be called on 
all keys and values before destroying the <link linkend="GTree">GTree</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>
