docs/reference/glib/html/glib-Balanced-Binary-Trees.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Balanced Binary Trees</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-data-types.html" title="GLib Data Types">
   9 <link rel="prev" href="glib-Byte-Arrays.html" title="Byte Arrays">
  10 <link rel="next" href="glib-N-ary-Trees.html" title="N-ary Trees">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="chapter" href="glib.html" title="GLib Overview">
  14 <link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
  15 <link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
  16 <link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
  17 <link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
  18 <link rel="chapter" href="tools.html" title="GLib Tools">
  19 <link rel="index" href="api-index-full.html" title="Index">
  20 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  21 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  22 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  23 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  24 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  25 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  26 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  27 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  28 <link rel="index" href="api-index-2-16.html" title="Index of new symbols in 2.16">
  29 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  30 <link rel="index" href="api-index-2-20.html" title="Index of new symbols in 2.20">
  31 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  32 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  33 </head>
  34 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  35 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  36 <tr valign="middle">
  37 <td><a accesskey="p" href="glib-Byte-Arrays.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  38 <td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  39 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  40 <th width="100%" align="center">GLib Reference Manual</th>
  41 <td><a accesskey="n" href="glib-N-ary-Trees.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  42 </tr>
  43 <tr><td colspan="5" class="shortcuts">
  44 <a href="#glib-Balanced-Binary-Trees.synopsis" class="shortcut">Top</a>
  45                    |
  46                   <a href="#glib-Balanced-Binary-Trees.description" class="shortcut">Description</a>
  47 </td></tr>
  48 </table>
  49 <div class="refentry" title="Balanced Binary Trees">
  50 <a name="glib-Balanced-Binary-Trees"></a><div class="titlepage"></div>
  51 <div class="refnamediv"><table width="100%"><tr>
  52 <td valign="top">
  53 <h2><span class="refentrytitle"><a name="glib-Balanced-Binary-Trees.top_of_page"></a>Balanced Binary Trees</span></h2>
  54 <p>Balanced Binary Trees — a sorted collection of key/value pairs optimized
  55                     for searching and traversing in order</p>
  56 </td>
  57 <td valign="top" align="right"></td>
  58 </tr></table></div>
  59 <div class="refsynopsisdiv" title="Synopsis">
  60 <a name="glib-Balanced-Binary-Trees.synopsis"></a><h2>Synopsis</h2>
  61 <pre class="synopsis">
  62 #include &lt;glib.h&gt;
  63
  64                     <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree">GTree</a>;
  65 <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new" title="g_tree_new ()">g_tree_new</a>                          (<a class="link" href="glib-Doubly-Linked-Lists.html#GCompareFunc" title="GCompareFunc ()"><span class="returnvalue">GCompareFunc</span></a> key_compare_func);
  66 <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-ref" title="g_tree_ref ()">g_tree_ref</a>                          (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);
  67 <span class="returnvalue">void</span>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-unref" title="g_tree_unref ()">g_tree_unref</a>                        (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);
  68 <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new-with-data" title="g_tree_new_with_data ()">g_tree_new_with_data</a>                (<a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="returnvalue">GCompareDataFunc</span></a> key_compare_func,
  69                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key_compare_data);
  70 <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new-full" title="g_tree_new_full ()">g_tree_new_full</a>                     (<a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="returnvalue">GCompareDataFunc</span></a> key_compare_func,
  71                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key_compare_data,
  72                                                          <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="returnvalue">GDestroyNotify</span></a> key_destroy_func,
  73                                                          <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="returnvalue">GDestroyNotify</span></a> value_destroy_func);
  74 <span class="returnvalue">void</span>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-insert" title="g_tree_insert ()">g_tree_insert</a>                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
  75                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key,
  76                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> value);
  77 <span class="returnvalue">void</span>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-replace" title="g_tree_replace ()">g_tree_replace</a>                      (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
  78                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key,
  79                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> value);
  80 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-nnodes" title="g_tree_nnodes ()">g_tree_nnodes</a>                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);
  81 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-height" title="g_tree_height ()">g_tree_height</a>                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);
  82 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-lookup" title="g_tree_lookup ()">g_tree_lookup</a>                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
  83                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> key);
  84 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-lookup-extended" title="g_tree_lookup_extended ()">g_tree_lookup_extended</a>              (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
  85                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> lookup_key,
  86                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> *orig_key,
  87                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> *value);
  88 <span class="returnvalue">void</span>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-foreach" title="g_tree_foreach ()">g_tree_foreach</a>                      (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
  89                                                          <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseFunc" title="GTraverseFunc ()"><span class="returnvalue">GTraverseFunc</span></a> func,
  90                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> user_data);
  91 <span class="returnvalue">void</span>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-traverse" title="g_tree_traverse ()">g_tree_traverse</a>                     (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
  92                                                          <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseFunc" title="GTraverseFunc ()"><span class="returnvalue">GTraverseFunc</span></a> traverse_func,
  93                                                          <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseType" title="enum GTraverseType"><span class="returnvalue">GTraverseType</span></a> traverse_type,
  94                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> user_data);
  95 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            (<a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseFunc" title="GTraverseFunc ()">*GTraverseFunc</a>)                    (<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key,
  96                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> value,
  97                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> data);
  98 enum                <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseType" title="enum GTraverseType">GTraverseType</a>;
  99 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-search" title="g_tree_search ()">g_tree_search</a>                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 100                                                          <a class="link" href="glib-Doubly-Linked-Lists.html#GCompareFunc" title="GCompareFunc ()"><span class="returnvalue">GCompareFunc</span></a> search_func,
 101                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> user_data);
 102 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-remove" title="g_tree_remove ()">g_tree_remove</a>                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 103                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> key);
 104 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-steal" title="g_tree_steal ()">g_tree_steal</a>                        (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 105                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> key);
 106 <span class="returnvalue">void</span>                <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-destroy" title="g_tree_destroy ()">g_tree_destroy</a>                      (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);
 107 </pre>
 108 </div>
 109 <div class="refsect1" title="Description">
 110 <a name="glib-Balanced-Binary-Trees.description"></a><h2>Description</h2>
 111 <p>
 112 The <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> structure and its associated functions provide a sorted
 113 collection of key/value pairs optimized for searching and traversing
 114 in order.
 115 </p>
 116 <p>
 117 To create a new <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new" title="g_tree_new ()"><code class="function">g_tree_new()</code></a>.
 118 </p>
 119 <p>
 120 To insert a key/value pair into a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-insert" title="g_tree_insert ()"><code class="function">g_tree_insert()</code></a>.
 121 </p>
 122 <p>
 123 To lookup the value corresponding to a given key, use
 124 <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-lookup" title="g_tree_lookup ()"><code class="function">g_tree_lookup()</code></a> and <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-lookup-extended" title="g_tree_lookup_extended ()"><code class="function">g_tree_lookup_extended()</code></a>.
 125 </p>
 126 <p>
 127 To find out the number of nodes in a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-nnodes" title="g_tree_nnodes ()"><code class="function">g_tree_nnodes()</code></a>. To
 128 get the height of a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-height" title="g_tree_height ()"><code class="function">g_tree_height()</code></a>.
 129 </p>
 130 <p>
 131 To traverse a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, calling a function for each node visited in
 132 the traversal, use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-foreach" title="g_tree_foreach ()"><code class="function">g_tree_foreach()</code></a>.
 133 </p>
 134 <p>
 135 To remove a key/value pair use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-remove" title="g_tree_remove ()"><code class="function">g_tree_remove()</code></a>.
 136 </p>
 137 <p>
 138 To destroy a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-destroy" title="g_tree_destroy ()"><code class="function">g_tree_destroy()</code></a>.</p>
 139 </div>
 140 <div class="refsect1" title="Details">
 141 <a name="glib-Balanced-Binary-Trees.details"></a><h2>Details</h2>
 142 <div class="refsect2" title="GTree">
 143 <a name="GTree"></a><h3>GTree</h3>
 144 <pre class="programlisting">typedef struct _GTree GTree;</pre>
 145 <p>
 146 The <span class="structname">GTree</span> struct is an opaque data
 147 structure representing a <a class="link" href="glib-Balanced-Binary-Trees.html" title="Balanced Binary Trees">Balanced Binary Tree</a>. It
 148 should be accessed only by using the following functions.</p>
 149 </div>
 150 <hr>
 151 <div class="refsect2" title="g_tree_new ()">
 152 <a name="g-tree-new"></a><h3>g_tree_new ()</h3>
 153 <pre class="programlisting"><a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              g_tree_new                          (<a class="link" href="glib-Doubly-Linked-Lists.html#GCompareFunc" title="GCompareFunc ()"><span class="returnvalue">GCompareFunc</span></a> key_compare_func);</pre>
 154 <p>
 155 Creates a new <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.</p>
 156 <div class="variablelist"><table border="0">
 157 <col align="left" valign="top">
 158 <tbody>
 159 <tr>
 160 <td><p><span class="term"><em class="parameter"><code>key_compare_func</code></em> :</span></p></td>
 161 <td> the function used to order the nodes in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 162   It should return values similar to the standard <code class="function">strcmp()</code> function -
 163   0 if the two arguments are equal, a negative value if the first argument
 164   comes before the second, or a positive value if the first argument comes
 165   after the second.
 166 </td>
 167 </tr>
 168 <tr>
 169 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 170 <td> a new <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 171 </td>
 172 </tr>
 173 </tbody>
 174 </table></div>
 175 </div>
 176 <hr>
 177 <div class="refsect2" title="g_tree_ref ()">
 178 <a name="g-tree-ref"></a><h3>g_tree_ref ()</h3>
 179 <pre class="programlisting"><a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              g_tree_ref                          (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);</pre>
 180 <p>
 181 Increments the reference count of <em class="parameter"><code>tree</code></em> by one.  It is safe to call
 182 this function from any thread.</p>
 183 <div class="variablelist"><table border="0">
 184 <col align="left" valign="top">
 185 <tbody>
 186 <tr>
 187 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 188 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 189 </td>
 190 </tr>
 191 <tr>
 192 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 193 <td> the passed in <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 194
 195 </td>
 196 </tr>
 197 </tbody>
 198 </table></div>
 199 <p class="since">Since 2.22</p>
 200 </div>
 201 <hr>
 202 <div class="refsect2" title="g_tree_unref ()">
 203 <a name="g-tree-unref"></a><h3>g_tree_unref ()</h3>
 204 <pre class="programlisting"><span class="returnvalue">void</span>                g_tree_unref                        (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);</pre>
 205 <p>
 206 Decrements the reference count of <em class="parameter"><code>tree</code></em> by one.  If the reference count
 207 drops to 0, all keys and values will be destroyed (if destroy
 208 functions were specified) and all memory allocated by <em class="parameter"><code>tree</code></em> will be
 209 released.
 210 </p>
 211 <p>
 212 It is safe to call this function from any thread.</p>
 213 <div class="variablelist"><table border="0">
 214 <col align="left" valign="top">
 215 <tbody><tr>
 216 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 217 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 218 </td>
 219 </tr></tbody>
 220 </table></div>
 221 <p class="since">Since 2.22</p>
 222 </div>
 223 <hr>
 224 <div class="refsect2" title="g_tree_new_with_data ()">
 225 <a name="g-tree-new-with-data"></a><h3>g_tree_new_with_data ()</h3>
 226 <pre class="programlisting"><a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              g_tree_new_with_data                (<a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="returnvalue">GCompareDataFunc</span></a> key_compare_func,
 227                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key_compare_data);</pre>
 228 <p>
 229 Creates a new <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> with a comparison function that accepts user data.
 230 See <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new" title="g_tree_new ()"><code class="function">g_tree_new()</code></a> for more details.</p>
 231 <div class="variablelist"><table border="0">
 232 <col align="left" valign="top">
 233 <tbody>
 234 <tr>
 235 <td><p><span class="term"><em class="parameter"><code>key_compare_func</code></em> :</span></p></td>
 236 <td> <code class="function">qsort()</code>-style comparison function.
 237 </td>
 238 </tr>
 239 <tr>
 240 <td><p><span class="term"><em class="parameter"><code>key_compare_data</code></em> :</span></p></td>
 241 <td> data to pass to comparison function.
 242 </td>
 243 </tr>
 244 <tr>
 245 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 246 <td> a new <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 247 </td>
 248 </tr>
 249 </tbody>
 250 </table></div>
 251 </div>
 252 <hr>
 253 <div class="refsect2" title="g_tree_new_full ()">
 254 <a name="g-tree-new-full"></a><h3>g_tree_new_full ()</h3>
 255 <pre class="programlisting"><a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a>*              g_tree_new_full                     (<a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="returnvalue">GCompareDataFunc</span></a> key_compare_func,
 256                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key_compare_data,
 257                                                          <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="returnvalue">GDestroyNotify</span></a> key_destroy_func,
 258                                                          <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="returnvalue">GDestroyNotify</span></a> value_destroy_func);</pre>
 259 <p>
 260 Creates a new <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> like <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new" title="g_tree_new ()"><code class="function">g_tree_new()</code></a> and allows to specify functions
 261 to free the memory allocated for the key and value that get called when
 262 removing the entry from the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.</p>
 263 <div class="variablelist"><table border="0">
 264 <col align="left" valign="top">
 265 <tbody>
 266 <tr>
 267 <td><p><span class="term"><em class="parameter"><code>key_compare_func</code></em> :</span></p></td>
 268 <td> <code class="function">qsort()</code>-style comparison function.
 269 </td>
 270 </tr>
 271 <tr>
 272 <td><p><span class="term"><em class="parameter"><code>key_compare_data</code></em> :</span></p></td>
 273 <td> data to pass to comparison function.
 274 </td>
 275 </tr>
 276 <tr>
 277 <td><p><span class="term"><em class="parameter"><code>key_destroy_func</code></em> :</span></p></td>
 278 <td> a function to free the memory allocated for the key
 279   used when removing the entry from the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if you don't
 280   want to supply such a function.
 281 </td>
 282 </tr>
 283 <tr>
 284 <td><p><span class="term"><em class="parameter"><code>value_destroy_func</code></em> :</span></p></td>
 285 <td> a function to free the memory allocated for the
 286   value used when removing the entry from the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if you
 287   don't want to supply such a function.
 288 </td>
 289 </tr>
 290 <tr>
 291 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 292 <td> a new <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 293 </td>
 294 </tr>
 295 </tbody>
 296 </table></div>
 297 </div>
 298 <hr>
 299 <div class="refsect2" title="g_tree_insert ()">
 300 <a name="g-tree-insert"></a><h3>g_tree_insert ()</h3>
 301 <pre class="programlisting"><span class="returnvalue">void</span>                g_tree_insert                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 302                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key,
 303                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> value);</pre>
 304 <p>
 305 Inserts a key/value pair into a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>. If the given key already exists
 306 in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> its corresponding value is set to the new value. If you
 307 supplied a value_destroy_func when creating the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, the old value is
 308 freed using that function. If you supplied a <em class="parameter"><code>key_destroy_func</code></em> when
 309 creating the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, the passed key is freed using that function.
 310 </p>
 311 <p>
 312 The tree is automatically 'balanced' as new key/value pairs are added,
 313 so that the distance from the root to every leaf is as small as possible.</p>
 314 <div class="variablelist"><table border="0">
 315 <col align="left" valign="top">
 316 <tbody>
 317 <tr>
 318 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 319 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 320 </td>
 321 </tr>
 322 <tr>
 323 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
 324 <td> the key to insert.
 325 </td>
 326 </tr>
 327 <tr>
 328 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 329 <td> the value corresponding to the key.
 330 </td>
 331 </tr>
 332 </tbody>
 333 </table></div>
 334 </div>
 335 <hr>
 336 <div class="refsect2" title="g_tree_replace ()">
 337 <a name="g-tree-replace"></a><h3>g_tree_replace ()</h3>
 338 <pre class="programlisting"><span class="returnvalue">void</span>                g_tree_replace                      (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 339                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key,
 340                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> value);</pre>
 341 <p>
 342 Inserts a new key and value into a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> similar to <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-insert" title="g_tree_insert ()"><code class="function">g_tree_insert()</code></a>.
 343 The difference is that if the key already exists in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, it gets
 344 replaced by the new key. If you supplied a <em class="parameter"><code>value_destroy_func</code></em> when
 345 creating the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, the old value is freed using that function. If you
 346 supplied a <em class="parameter"><code>key_destroy_func</code></em> when creating the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, the old key is
 347 freed using that function.
 348 </p>
 349 <p>
 350 The tree is automatically 'balanced' as new key/value pairs are added,
 351 so that the distance from the root to every leaf is as small as possible.</p>
 352 <div class="variablelist"><table border="0">
 353 <col align="left" valign="top">
 354 <tbody>
 355 <tr>
 356 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 357 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 358 </td>
 359 </tr>
 360 <tr>
 361 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
 362 <td> the key to insert.
 363 </td>
 364 </tr>
 365 <tr>
 366 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 367 <td> the value corresponding to the key.
 368 </td>
 369 </tr>
 370 </tbody>
 371 </table></div>
 372 </div>
 373 <hr>
 374 <div class="refsect2" title="g_tree_nnodes ()">
 375 <a name="g-tree-nnodes"></a><h3>g_tree_nnodes ()</h3>
 376 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_tree_nnodes                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);</pre>
 377 <p>
 378 Gets the number of nodes in a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.</p>
 379 <div class="variablelist"><table border="0">
 380 <col align="left" valign="top">
 381 <tbody>
 382 <tr>
 383 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 384 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 385 </td>
 386 </tr>
 387 <tr>
 388 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 389 <td> the number of nodes in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 390 </td>
 391 </tr>
 392 </tbody>
 393 </table></div>
 394 </div>
 395 <hr>
 396 <div class="refsect2" title="g_tree_height ()">
 397 <a name="g-tree-height"></a><h3>g_tree_height ()</h3>
 398 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_tree_height                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);</pre>
 399 <p>
 400 Gets the height of a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 401 </p>
 402 <p>
 403 If the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> contains no nodes, the height is 0.
 404 If the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> contains only one root node the height is 1.
 405 If the root node has children the height is 2, etc.</p>
 406 <div class="variablelist"><table border="0">
 407 <col align="left" valign="top">
 408 <tbody>
 409 <tr>
 410 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 411 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 412 </td>
 413 </tr>
 414 <tr>
 415 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 416 <td> the height of the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 417 </td>
 418 </tr>
 419 </tbody>
 420 </table></div>
 421 </div>
 422 <hr>
 423 <div class="refsect2" title="g_tree_lookup ()">
 424 <a name="g-tree-lookup"></a><h3>g_tree_lookup ()</h3>
 425 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_tree_lookup                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 426                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> key);</pre>
 427 <p>
 428 Gets the value corresponding to the given key. Since a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> is
 429 automatically balanced as key/value pairs are added, key lookup is very
 430 fast.</p>
 431 <div class="variablelist"><table border="0">
 432 <col align="left" valign="top">
 433 <tbody>
 434 <tr>
 435 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 436 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 437 </td>
 438 </tr>
 439 <tr>
 440 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
 441 <td> the key to look up.
 442 </td>
 443 </tr>
 444 <tr>
 445 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 446 <td> the value corresponding to the key, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if the key was
 447 not found.
 448 </td>
 449 </tr>
 450 </tbody>
 451 </table></div>
 452 </div>
 453 <hr>
 454 <div class="refsect2" title="g_tree_lookup_extended ()">
 455 <a name="g-tree-lookup-extended"></a><h3>g_tree_lookup_extended ()</h3>
 456 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_tree_lookup_extended              (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 457                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> lookup_key,
 458                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> *orig_key,
 459                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> *value);</pre>
 460 <p>
 461 Looks up a key in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, returning the original key and the
 462 associated value and a <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> which is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the key was found. This
 463 is useful if you need to free the memory allocated for the original key,
 464 for example before calling <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-remove" title="g_tree_remove ()"><code class="function">g_tree_remove()</code></a>.</p>
 465 <div class="variablelist"><table border="0">
 466 <col align="left" valign="top">
 467 <tbody>
 468 <tr>
 469 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 470 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 471 </td>
 472 </tr>
 473 <tr>
 474 <td><p><span class="term"><em class="parameter"><code>lookup_key</code></em> :</span></p></td>
 475 <td> the key to look up.
 476 </td>
 477 </tr>
 478 <tr>
 479 <td><p><span class="term"><em class="parameter"><code>orig_key</code></em> :</span></p></td>
 480 <td> returns the original key.
 481 </td>
 482 </tr>
 483 <tr>
 484 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 485 <td> returns the value associated with the key.
 486 </td>
 487 </tr>
 488 <tr>
 489 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 490 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the key was found in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 491 </td>
 492 </tr>
 493 </tbody>
 494 </table></div>
 495 </div>
 496 <hr>
 497 <div class="refsect2" title="g_tree_foreach ()">
 498 <a name="g-tree-foreach"></a><h3>g_tree_foreach ()</h3>
 499 <pre class="programlisting"><span class="returnvalue">void</span>                g_tree_foreach                      (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 500                                                          <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseFunc" title="GTraverseFunc ()"><span class="returnvalue">GTraverseFunc</span></a> func,
 501                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> user_data);</pre>
 502 <p>
 503 Calls the given function for each of the key/value pairs in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 504 The function is passed the key and value of each pair, and the given
 505 <em class="parameter"><code>data</code></em> parameter. The tree is traversed in sorted order.
 506 </p>
 507 <p>
 508 The tree may not be modified while iterating over it (you can't
 509 add/remove items). To remove all items matching a predicate, you need
 510 to add each item to a list in your <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseFunc" title="GTraverseFunc ()"><span class="type">GTraverseFunc</span></a> as you walk over
 511 the tree, then walk the list and remove each item.</p>
 512 <div class="variablelist"><table border="0">
 513 <col align="left" valign="top">
 514 <tbody>
 515 <tr>
 516 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 517 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 518 </td>
 519 </tr>
 520 <tr>
 521 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 522 <td> the function to call for each node visited. If this function
 523   returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, the traversal is stopped.
 524 </td>
 525 </tr>
 526 <tr>
 527 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 528 <td> user data to pass to the function.
 529 </td>
 530 </tr>
 531 </tbody>
 532 </table></div>
 533 </div>
 534 <hr>
 535 <div class="refsect2" title="g_tree_traverse ()">
 536 <a name="g-tree-traverse"></a><h3>g_tree_traverse ()</h3>
 537 <pre class="programlisting"><span class="returnvalue">void</span>                g_tree_traverse                     (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 538                                                          <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseFunc" title="GTraverseFunc ()"><span class="returnvalue">GTraverseFunc</span></a> traverse_func,
 539                                                          <a class="link" href="glib-Balanced-Binary-Trees.html#GTraverseType" title="enum GTraverseType"><span class="returnvalue">GTraverseType</span></a> traverse_type,
 540                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> user_data);</pre>
 541 <div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 542 <h3 class="title">Warning</h3>
 543 <p><code class="literal">g_tree_traverse</code> 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
 544 just want to visit all nodes in sorted order, use <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-foreach" title="g_tree_foreach ()"><code class="function">g_tree_foreach()</code></a>
 545 instead. If you really need to visit nodes in a different order, consider
 546 using an <a class="link" href="glib-N-ary-Trees.html" title="N-ary Trees">N-ary Tree</a>.</p>
 547 </div>
 548 <p>
 549 Calls the given function for each node in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.</p>
 550 <div class="variablelist"><table border="0">
 551 <col align="left" valign="top">
 552 <tbody>
 553 <tr>
 554 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 555 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 556 </td>
 557 </tr>
 558 <tr>
 559 <td><p><span class="term"><em class="parameter"><code>traverse_func</code></em> :</span></p></td>
 560 <td> the function to call for each node visited. If this
 561   function returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, the traversal is stopped.
 562 </td>
 563 </tr>
 564 <tr>
 565 <td><p><span class="term"><em class="parameter"><code>traverse_type</code></em> :</span></p></td>
 566 <td> the order in which nodes are visited, one of <a class="link" href="glib-Balanced-Binary-Trees.html#G-IN-ORDER:CAPS"><code class="literal">G_IN_ORDER</code></a>,
 567   <a class="link" href="glib-Balanced-Binary-Trees.html#G-PRE-ORDER:CAPS"><code class="literal">G_PRE_ORDER</code></a> and <a class="link" href="glib-Balanced-Binary-Trees.html#G-POST-ORDER:CAPS"><code class="literal">G_POST_ORDER</code></a>.
 568 </td>
 569 </tr>
 570 <tr>
 571 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 572 <td> user data to pass to the function.
 573 </td>
 574 </tr>
 575 </tbody>
 576 </table></div>
 577 </div>
 578 <hr>
 579 <div class="refsect2" title="GTraverseFunc ()">
 580 <a name="GTraverseFunc"></a><h3>GTraverseFunc ()</h3>
 581 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            (*GTraverseFunc)                    (<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> key,
 582                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> value,
 583                                                          <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> data);</pre>
 584 <p>
 585 Specifies the type of function passed to <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-traverse" title="g_tree_traverse ()"><code class="function">g_tree_traverse()</code></a>. It is
 586 passed the key and value of each node, together with the <em class="parameter"><code>user_data</code></em>
 587 parameter passed to <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-traverse" title="g_tree_traverse ()"><code class="function">g_tree_traverse()</code></a>. If the function returns
 588 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, the traversal is stopped.</p>
 589 <div class="variablelist"><table border="0">
 590 <col align="left" valign="top">
 591 <tbody>
 592 <tr>
 593 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
 594 <td> a key of a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> node.
 595 </td>
 596 </tr>
 597 <tr>
 598 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 599 <td> the value corresponding to the key.
 600 </td>
 601 </tr>
 602 <tr>
 603 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 604 <td> user data passed to <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-traverse" title="g_tree_traverse ()"><code class="function">g_tree_traverse()</code></a>.
 605 </td>
 606 </tr>
 607 <tr>
 608 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 609 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> to stop the traversal.
 610 </td>
 611 </tr>
 612 </tbody>
 613 </table></div>
 614 </div>
 615 <hr>
 616 <div class="refsect2" title="enum GTraverseType">
 617 <a name="GTraverseType"></a><h3>enum GTraverseType</h3>
 618 <pre class="programlisting">typedef enum
 619 {
 620   G_IN_ORDER,
 621   G_PRE_ORDER,
 622   G_POST_ORDER,
 623   G_LEVEL_ORDER
 624 } GTraverseType;
 625 </pre>
 626 <p>
 627 Specifies the type of traveral performed by <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-traverse" title="g_tree_traverse ()"><code class="function">g_tree_traverse()</code></a>,
 628 <a class="link" href="glib-N-ary-Trees.html#g-node-traverse" title="g_node_traverse ()"><code class="function">g_node_traverse()</code></a> and <a class="link" href="glib-N-ary-Trees.html#g-node-find" title="g_node_find ()"><code class="function">g_node_find()</code></a>.</p>
 629 <div class="variablelist"><table border="0">
 630 <col align="left" valign="top">
 631 <tbody>
 632 <tr>
 633 <td><p><a name="G-IN-ORDER:CAPS"></a><span class="term"><code class="literal">G_IN_ORDER</code></span></p></td>
 634 <td> vists a node's left child first, then the node itself,
 635              then its right child. This is the one to use if you
 636              want the output sorted according to the compare
 637              function.
 638 </td>
 639 </tr>
 640 <tr>
 641 <td><p><a name="G-PRE-ORDER:CAPS"></a><span class="term"><code class="literal">G_PRE_ORDER</code></span></p></td>
 642 <td> visits a node, then its children.
 643 </td>
 644 </tr>
 645 <tr>
 646 <td><p><a name="G-POST-ORDER:CAPS"></a><span class="term"><code class="literal">G_POST_ORDER</code></span></p></td>
 647 <td> visits the node's children, then the node itself.
 648 </td>
 649 </tr>
 650 <tr>
 651 <td><p><a name="G-LEVEL-ORDER:CAPS"></a><span class="term"><code class="literal">G_LEVEL_ORDER</code></span></p></td>
 652 <td> is not implemented for <a class="link" href="glib-Balanced-Binary-Trees.html" title="Balanced Binary Trees">Balanced Binary
 653                 Trees</a>.  For <a class="link" href="glib-N-ary-Trees.html" title="N-ary Trees">N-ary Trees</a>, it
 654                 vists the root node first, then its children, then
 655                 its grandchildren, and so on. Note that this is less
 656                 efficient than the other orders.
 657 </td>
 658 </tr>
 659 </tbody>
 660 </table></div>
 661 </div>
 662 <hr>
 663 <div class="refsect2" title="g_tree_search ()">
 664 <a name="g-tree-search"></a><h3>g_tree_search ()</h3>
 665 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_tree_search                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 666                                                          <a class="link" href="glib-Doubly-Linked-Lists.html#GCompareFunc" title="GCompareFunc ()"><span class="returnvalue">GCompareFunc</span></a> search_func,
 667                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> user_data);</pre>
 668 <p>
 669 Searches a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> using <em class="parameter"><code>search_func</code></em>.
 670 </p>
 671 <p>
 672 The <em class="parameter"><code>search_func</code></em> is called with a pointer to the key of a key/value pair in
 673 the tree, and the passed in <em class="parameter"><code>user_data</code></em>. If <em class="parameter"><code>search_func</code></em> returns 0 for a
 674 key/value pair, then <code class="function">g_tree_search_func()</code> will return the value of that
 675 pair. If <em class="parameter"><code>search_func</code></em> returns -1,  searching will proceed among the
 676 key/value pairs that have a smaller key; if <em class="parameter"><code>search_func</code></em> returns 1,
 677 searching will proceed among the key/value pairs that have a larger key.</p>
 678 <div class="variablelist"><table border="0">
 679 <col align="left" valign="top">
 680 <tbody>
 681 <tr>
 682 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 683 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 684 </td>
 685 </tr>
 686 <tr>
 687 <td><p><span class="term"><em class="parameter"><code>search_func</code></em> :</span></p></td>
 688 <td> a function used to search the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 689 </td>
 690 </tr>
 691 <tr>
 692 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 693 <td> the data passed as the second argument to the <em class="parameter"><code>search_func</code></em>
 694 function.
 695 </td>
 696 </tr>
 697 <tr>
 698 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 699 <td> the value corresponding to the found key, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if the key
 700 was not found.
 701 </td>
 702 </tr>
 703 </tbody>
 704 </table></div>
 705 </div>
 706 <hr>
 707 <div class="refsect2" title="g_tree_remove ()">
 708 <a name="g-tree-remove"></a><h3>g_tree_remove ()</h3>
 709 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_tree_remove                       (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 710                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> key);</pre>
 711 <p>
 712 Removes a key/value pair from a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 713 </p>
 714 <p>
 715 If the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> was created using <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new-full" title="g_tree_new_full ()"><code class="function">g_tree_new_full()</code></a>, the key and value
 716 are freed using the supplied destroy functions, otherwise you have to
 717 make sure that any dynamically allocated values are freed yourself.
 718 If the key does not exist in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, the function does nothing.</p>
 719 <div class="variablelist"><table border="0">
 720 <col align="left" valign="top">
 721 <tbody>
 722 <tr>
 723 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 724 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 725 </td>
 726 </tr>
 727 <tr>
 728 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
 729 <td> the key to remove.
 730 </td>
 731 </tr>
 732 <tr>
 733 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 734 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the key was found (prior to 2.8, this function returned
 735   nothing)
 736 </td>
 737 </tr>
 738 </tbody>
 739 </table></div>
 740 </div>
 741 <hr>
 742 <div class="refsect2" title="g_tree_steal ()">
 743 <a name="g-tree-steal"></a><h3>g_tree_steal ()</h3>
 744 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_tree_steal                        (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree,
 745                                                          <a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="returnvalue">gconstpointer</span></a> key);</pre>
 746 <p>
 747 Removes a key and its associated value from a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> without calling
 748 the key and value destroy functions.
 749 </p>
 750 <p>
 751 If the key does not exist in the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>, the function does nothing.</p>
 752 <div class="variablelist"><table border="0">
 753 <col align="left" valign="top">
 754 <tbody>
 755 <tr>
 756 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 757 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 758 </td>
 759 </tr>
 760 <tr>
 761 <td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
 762 <td> the key to remove.
 763 </td>
 764 </tr>
 765 <tr>
 766 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 767 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the key was found (prior to 2.8, this function returned
 768    nothing)
 769 </td>
 770 </tr>
 771 </tbody>
 772 </table></div>
 773 </div>
 774 <hr>
 775 <div class="refsect2" title="g_tree_destroy ()">
 776 <a name="g-tree-destroy"></a><h3>g_tree_destroy ()</h3>
 777 <pre class="programlisting"><span class="returnvalue">void</span>                g_tree_destroy                      (<a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="returnvalue">GTree</span></a> *tree);</pre>
 778 <p>
 779 Removes all keys and values from the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a> and decreases its
 780 reference count by one. If keys and/or values are dynamically
 781 allocated, you should either free them first or create the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>
 782 using <a class="link" href="glib-Balanced-Binary-Trees.html#g-tree-new-full" title="g_tree_new_full ()"><code class="function">g_tree_new_full()</code></a>.  In the latter case the destroy functions
 783 you supplied will be called on all keys and values before destroying
 784 the <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.</p>
 785 <div class="variablelist"><table border="0">
 786 <col align="left" valign="top">
 787 <tbody><tr>
 788 <td><p><span class="term"><em class="parameter"><code>tree</code></em> :</span></p></td>
 789 <td> a <a class="link" href="glib-Balanced-Binary-Trees.html#GTree" title="GTree"><span class="type">GTree</span></a>.
 790 </td>
 791 </tr></tbody>
 792 </table></div>
 793 </div>
 794 </div>
 795 </div>
 796 <div class="footer">
 797 <hr>
 798           Generated by GTK-Doc V1.13</div>
 799 </body>
 800 </html>