docs/reference/glib/tmpl/trees-binary.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Balanced Binary Trees
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a sorted collection of key/value pairs optimised for searching
   6 and traversing in order.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 The #GTree structure and its associated functions provide a sorted collection
  11 of key/value pairs optimised for searching and traversing in order.
  12 </para>
  13 <para>
  14 To create a new #GTree use g_tree_new().
  15 </para>
  16 <para>
  17 To insert a key/value pair into a #GTree use g_tree_insert().
  18 </para>
  19 <para>
  20 To lookup the value corresponding to a given key, use g_tree_lookup() and
  21 g_tree_lookup_extended().
  22 </para>
  23 <para>
  24 To find out the number of nodes in a #GTree, use g_tree_nnodes().
  25 To get the height of a #GTree, use g_tree_height().
  26 </para>
  27 <para>
  28 To traverse a #GTree, calling a function for each node visited in the
  29 traversal, use g_tree_foreach().
  30 </para>
  31 <para>
  32 To remove a key/value pair use g_tree_remove().
  33 </para>
  34 <para>
  35 To destroy a #GTree, use g_tree_destroy().
  36 </para>
  37
  38 <!-- ##### SECTION See_Also ##### -->
  39 <para>
  40
  41 </para>
  42
  43 <!-- ##### STRUCT GTree ##### -->
  44 <para>
  45 The #GTree struct is an opaque data structure representing a
  46 <link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
  47 It should be accessed only by using the following functions.
  48 </para>
  49
  50
  51 <!-- ##### FUNCTION g_tree_new ##### -->
  52 <para>
  53
  54 </para>
  55
  56 @key_compare_func:
  57 @Returns:
  58
  59
  60 <!-- ##### FUNCTION g_tree_new_with_data ##### -->
  61 <para>
  62
  63 </para>
  64
  65 @key_compare_func:
  66 @key_compare_data:
  67 @Returns:
  68
  69
  70 <!-- ##### FUNCTION g_tree_new_full ##### -->
  71 <para>
  72
  73 </para>
  74
  75 @key_compare_func:
  76 @key_compare_data:
  77 @key_destroy_func:
  78 @value_destroy_func:
  79 @Returns:
  80
  81
  82 <!-- ##### FUNCTION g_tree_insert ##### -->
  83 <para>
  84
  85 </para>
  86
  87 @tree:
  88 @key:
  89 @value:
  90
  91
  92 <!-- ##### FUNCTION g_tree_replace ##### -->
  93 <para>
  94
  95 </para>
  96
  97 @tree:
  98 @key:
  99 @value:
 100
 101
 102 <!-- ##### FUNCTION g_tree_nnodes ##### -->
 103 <para>
 104
 105 </para>
 106
 107 @tree:
 108 @Returns:
 109
 110
 111 <!-- ##### FUNCTION g_tree_height ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @tree:
 117 @Returns:
 118
 119
 120 <!-- ##### FUNCTION g_tree_lookup ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @tree:
 126 @key:
 127 @Returns:
 128
 129
 130 <!-- ##### FUNCTION g_tree_lookup_extended ##### -->
 131
 132
 133 @tree:
 134 @lookup_key:
 135 @orig_key:
 136 @value:
 137 @Returns:
 138
 139
 140 <!-- ##### FUNCTION g_tree_foreach ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @tree:
 146 @func:
 147 @user_data:
 148
 149
 150 <!-- ##### FUNCTION g_tree_traverse ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @tree:
 156 @traverse_func:
 157 @traverse_type:
 158 @user_data:
 159
 160
 161 <!-- ##### USER_FUNCTION GTraverseFunc ##### -->
 162 <para>
 163 Specifies the type of function passed to g_tree_traverse().
 164 It is passed the key and value of each node, together with
 165 the @user_data parameter passed to g_tree_traverse().
 166 If the function returns %TRUE, the traversal is stopped.
 167 </para>
 168
 169 @key: a key of a #GTree node.
 170 @value: the value corresponding to the key.
 171 @data: user data passed to g_tree_traverse().
 172 @Returns: %TRUE to stop the traversal.
 173
 174
 175 <!-- ##### ENUM GTraverseType ##### -->
 176 <para>
 177 Specifies the type of traveral performed by g_tree_traverse(),
 178 g_node_traverse() and g_node_find().
 179 </para>
 180
 181 @G_IN_ORDER: vists a node's left child first, then the node itself, then its
 182   right child. This is the one to use if you want the output sorted according
 183   to the compare function.
 184 @G_PRE_ORDER: visits a node, then its children.
 185 @G_POST_ORDER: visits the node's children, then the node itself.
 186 @G_LEVEL_ORDER: is not implemented for
 187   <link linkend="glib-Balanced-Binary-Trees">Balanced Binary Trees</link>.
 188   For <link linkend="glib-N-ary-Trees">N-ary Trees</link>, it vists the root
 189   node first, then its children, then its grandchildren, and so on. Note that
 190   this is less efficient than the other orders.
 191
 192 <!-- ##### FUNCTION g_tree_search ##### -->
 193 <para>
 194
 195 </para>
 196
 197 @tree:
 198 @search_func:
 199 @user_data:
 200 @Returns:
 201
 202
 203 <!-- ##### FUNCTION g_tree_remove ##### -->
 204 <para>
 205
 206 </para>
 207
 208 @tree:
 209 @key:
 210
 211
 212 <!-- ##### FUNCTION g_tree_steal ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @tree:
 218 @key:
 219
 220
 221 <!-- ##### FUNCTION g_tree_destroy ##### -->
 222 <para>
 223
 224 </para>
 225
 226 @tree:
 227
 228