1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GLib Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GLib at ftp://ftp.gtk.org/pub/gtk/.
36 typedef struct _GTreeNode GTreeNode;
41 GCompareDataFunc key_compare;
42 GDestroyNotify key_destroy_func;
43 GDestroyNotify value_destroy_func;
44 gpointer key_compare_data;
49 gint balance; /* height (left) - height (right) */
50 GTreeNode *left; /* left subtree */
51 GTreeNode *right; /* right subtree */
52 gpointer key; /* key for this node */
53 gpointer value; /* value stored at this node */
57 static GTreeNode* g_tree_node_new (gpointer key,
59 static void g_tree_node_destroy (GTreeNode *node,
60 GDestroyNotify key_destroy_func,
61 GDestroyNotify value_destroy_func);
62 static GTreeNode* g_tree_node_insert (GTree *tree,
68 static GTreeNode* g_tree_node_remove (GTree *tree,
72 static GTreeNode* g_tree_node_balance (GTreeNode *node);
73 static GTreeNode* g_tree_node_remove_leftmost (GTreeNode *node,
74 GTreeNode **leftmost);
75 static GTreeNode* g_tree_node_restore_left_balance (GTreeNode *node,
77 static GTreeNode* g_tree_node_restore_right_balance (GTreeNode *node,
79 static GTreeNode* g_tree_node_lookup (GTreeNode *node,
80 GCompareDataFunc compare,
83 static gint g_tree_node_count (GTreeNode *node);
84 static gint g_tree_node_pre_order (GTreeNode *node,
85 GTraverseFunc traverse_func,
87 static gint g_tree_node_in_order (GTreeNode *node,
88 GTraverseFunc traverse_func,
90 static gint g_tree_node_post_order (GTreeNode *node,
91 GTraverseFunc traverse_func,
93 static gpointer g_tree_node_search (GTreeNode *node,
94 GCompareFunc search_func,
96 static gint g_tree_node_height (GTreeNode *node);
97 static GTreeNode* g_tree_node_rotate_left (GTreeNode *node);
98 static GTreeNode* g_tree_node_rotate_right (GTreeNode *node);
99 static void g_tree_node_check (GTreeNode *node);
102 G_LOCK_DEFINE_STATIC (g_tree_global);
103 static GMemChunk *node_mem_chunk = NULL;
104 static GTreeNode *node_free_list = NULL;
108 g_tree_node_new (gpointer key,
113 G_LOCK (g_tree_global);
116 node = node_free_list;
117 node_free_list = node->right;
122 node_mem_chunk = g_mem_chunk_new ("GLib GTreeNode mem chunk",
127 node = g_chunk_new (GTreeNode, node_mem_chunk);
129 G_UNLOCK (g_tree_global);
141 g_tree_node_destroy (GTreeNode *node,
142 GDestroyNotify key_destroy_func,
143 GDestroyNotify value_destroy_func)
147 g_tree_node_destroy (node->right,
148 key_destroy_func, value_destroy_func);
149 g_tree_node_destroy (node->left,
150 key_destroy_func, value_destroy_func);
152 if (key_destroy_func)
153 key_destroy_func (node->key);
154 if (value_destroy_func)
155 value_destroy_func (node->value);
157 #ifdef ENABLE_GC_FRIENDLY
161 #endif /* ENABLE_GC_FRIENDLY */
163 G_LOCK (g_tree_global);
164 node->right = node_free_list;
165 node_free_list = node;
166 G_UNLOCK (g_tree_global);
172 * @key_compare_func: the function used to order the nodes in the #GTree.
173 * It should return values similar to the standard strcmp() function -
174 * 0 if the two arguments are equal, a negative value if the first argument
175 * comes before the second, or a positive value if the first argument comes
178 * Creates a new #GTree.
180 * Return value: a new #GTree.
183 g_tree_new (GCompareFunc key_compare_func)
185 g_return_val_if_fail (key_compare_func != NULL, NULL);
187 return g_tree_new_full ((GCompareDataFunc) key_compare_func, NULL,
192 * g_tree_new_with_data:
193 * @key_compare_func: qsort()-style comparison function.
194 * @key_compare_data: data to pass to comparison function.
196 * Creates a new #GTree with a comparison function that accepts user data.
197 * See g_tree_new() for more details.
199 * Return value: a new #GTree.
202 g_tree_new_with_data (GCompareDataFunc key_compare_func,
203 gpointer key_compare_data)
205 g_return_val_if_fail (key_compare_func != NULL, NULL);
207 return g_tree_new_full (key_compare_func, key_compare_data,
213 * @key_compare_func: qsort()-style comparison function.
214 * @key_compare_data: data to pass to comparison function.
215 * @key_destroy_func: a function to free the memory allocated for the key
216 * used when removing the entry from the #GTree or %NULL if you don't
217 * want to supply such a function.
218 * @value_destroy_func: a function to free the memory allocated for the
219 * value used when removing the entry from the #GTree or %NULL if you
220 * don't want to supply such a function.
222 * Creates a new #GTree like g_tree_new() and allows to specify functions
223 * to free the memory allocated for the key and value that get called when
224 * removing the entry from the #GTree.
226 * Return value: a new #GTree.
229 g_tree_new_full (GCompareDataFunc key_compare_func,
230 gpointer key_compare_data,
231 GDestroyNotify key_destroy_func,
232 GDestroyNotify value_destroy_func)
236 g_return_val_if_fail (key_compare_func != NULL, NULL);
238 tree = g_new (GTree, 1);
240 tree->key_compare = key_compare_func;
241 tree->key_destroy_func = key_destroy_func;
242 tree->value_destroy_func = value_destroy_func;
243 tree->key_compare_data = key_compare_data;
252 * Destroys the #GTree. If keys and/or values are dynamically allocated, you
253 * should either free them first or create the #GTree using g_tree_new_full().
254 * In the latter case the destroy functions you supplied will be called on
255 * all keys and values before destroying the #GTree.
258 g_tree_destroy (GTree *tree)
260 g_return_if_fail (tree != NULL);
262 g_tree_node_destroy (tree->root,
263 tree->key_destroy_func,
264 tree->value_destroy_func);
272 * @key: the key to insert.
273 * @value: the value corresponding to the key.
275 * Inserts a key/value pair into a #GTree. If the given key already exists
276 * in the #GTree its corresponding value is set to the new value. If you
277 * supplied a value_destroy_func when creating the #GTree, the old value is
278 * freed using that function. If you supplied a @key_destroy_func when
279 * creating the #GTree, the passed key is freed using that function.
281 * The tree is automatically 'balanced' as new key/value pairs are added,
282 * so that the distance from the root to every leaf is as small as possible.
285 g_tree_insert (GTree *tree,
291 g_return_if_fail (tree != NULL);
294 tree->root = g_tree_node_insert (tree,
303 * @key: the key to insert.
304 * @value: the value corresponding to the key.
306 * Inserts a new key and value into a #GTree similar to g_tree_insert().
307 * The difference is that if the key already exists in the #GTree, it gets
308 * replaced by the new key. If you supplied a @value_destroy_func when
309 * creating the #GTree, the old value is freed using that function. If you
310 * supplied a @key_destroy_func when creating the #GTree, the old key is
311 * freed using that function.
313 * The tree is automatically 'balanced' as new key/value pairs are added,
314 * so that the distance from the root to every leaf is as small as possible.
317 g_tree_replace (GTree *tree,
323 g_return_if_fail (tree != NULL);
326 tree->root = g_tree_node_insert (tree,
335 * @key: the key to remove.
337 * Removes a key/value pair from a #GTree.
339 * If the #GTree was created using g_tree_new_full(), the key and value
340 * are freed using the supplied destroy functions, otherwise you have to
341 * make sure that any dynamically allocated values are freed yourself.
344 g_tree_remove (GTree *tree,
347 g_return_if_fail (tree != NULL);
349 tree->root = g_tree_node_remove (tree, tree->root, key, TRUE);
355 * @key: the key to remove.
357 * Removes a key and its associated value from a #GTree without calling
358 * the key and value destroy functions.
361 g_tree_steal (GTree *tree,
364 g_return_if_fail (tree != NULL);
366 tree->root = g_tree_node_remove (tree, tree->root, key, FALSE);
372 * @key: the key to look up.
374 * Gets the value corresponding to the given key. Since a #GTree is
375 * automatically balanced as key/value pairs are added, key lookup is very
378 * Return value: the value corresponding to the key.
381 g_tree_lookup (GTree *tree,
386 g_return_val_if_fail (tree != NULL, NULL);
388 node = g_tree_node_lookup (tree->root,
389 tree->key_compare, tree->key_compare_data, key);
391 return node ? node->value : NULL;
395 * g_tree_lookup_extended:
397 * @lookup_key: the key to look up.
398 * @orig_key: returns the original key.
399 * @value: returns the value associated with the key.
401 * Looks up a key in the #GTree, returning the original key and the
402 * associated value and a #gboolean which is %TRUE if the key was found. This
403 * is useful if you need to free the memory allocated for the original key,
404 * for example before calling g_tree_remove().
406 * Return value: %TRUE if the key was found in the #GTree.
409 g_tree_lookup_extended (GTree *tree,
410 gconstpointer lookup_key,
416 g_return_val_if_fail (tree != NULL, FALSE);
418 node = g_tree_node_lookup (tree->root,
419 tree->key_compare, tree->key_compare_data, lookup_key);
424 *orig_key = node->key;
426 *value = node->value;
436 * @func: the function to call for each node visited. If this function
437 * returns %TRUE, the traversal is stopped.
438 * @user_data: user data to pass to the function.
440 * Calls the given function for each of the key/value pairs in the #GTree.
441 * The function is passed the key and value of each pair, and the given
442 * @data parameter. The tree is traversed in sorted order.
444 * The tree may not be modified while iterating over it (you can't
445 * add/remove items). To remove all items matching a predicate, you need
446 * to add each item to a list in your #GTraverseFunc as you walk over
447 * the tree, then walk the list and remove each item.
450 g_tree_foreach (GTree *tree,
454 g_return_if_fail (tree != NULL);
459 g_tree_node_in_order (tree->root, func, user_data);
465 * @traverse_func: the function to call for each node visited. If this
466 * function returns %TRUE, the traversal is stopped.
467 * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
468 * %G_PRE_ORDER and %G_POST_ORDER.
469 * @user_data: user data to pass to the function.
471 * Calls the given function for each node in the #GTree.
473 * Deprecated: The order of a balanced tree is somewhat arbitrary. If you
474 * just want to visit all nodes in sorted order, use g_tree_foreach()
475 * instead. If you really need to visit nodes in a different order, consider
476 * using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
479 g_tree_traverse (GTree *tree,
480 GTraverseFunc traverse_func,
481 GTraverseType traverse_type,
484 g_return_if_fail (tree != NULL);
489 switch (traverse_type)
492 g_tree_node_pre_order (tree->root, traverse_func, user_data);
496 g_tree_node_in_order (tree->root, traverse_func, user_data);
500 g_tree_node_post_order (tree->root, traverse_func, user_data);
504 g_warning ("g_tree_traverse(): traverse type G_LEVEL_ORDER isn't implemented.");
512 * @search_func: a function used to search the #GTree.
513 * @user_data: the data passed as the second argument to the @search_func
516 * Searches a #GTree using @search_func.
518 * The @search_func is called with a pointer to the key of a key/value pair in the tree,
519 * and the passed in @user_data. If @search_func returns 0 for a key/value pair, then
520 * g_tree_search_func() will return the value of that pair. If @search_func returns -1,
521 * searching will proceed among the key/value pairs that have a smaller key; if @search_func
522 * returns 1, searching will proceed among the key/value pairs that have a larger key.
524 * Return value: the value corresponding to the found key, or %NULL if the key
528 g_tree_search (GTree *tree,
529 GCompareFunc search_func,
530 gconstpointer user_data)
532 g_return_val_if_fail (tree != NULL, NULL);
535 return g_tree_node_search (tree->root, search_func, user_data);
544 * Gets the height of a #GTree.
546 * If the #GTree contains no nodes, the height is 0.
547 * If the #GTree contains only one root node the height is 1.
548 * If the root node has children the height is 2, etc.
550 * Return value: the height of the #GTree.
553 g_tree_height (GTree *tree)
555 g_return_val_if_fail (tree != NULL, 0);
558 return g_tree_node_height (tree->root);
567 * Gets the number of nodes in a #GTree.
569 * Return value: the number of nodes in the #GTree.
572 g_tree_nnodes (GTree *tree)
574 g_return_val_if_fail (tree != NULL, 0);
577 return g_tree_node_count (tree->root);
583 g_tree_node_insert (GTree *tree,
596 return g_tree_node_new (key, value);
599 cmp = tree->key_compare (key, node->key, tree->key_compare_data);
604 if (tree->value_destroy_func)
605 tree->value_destroy_func (node->value);
611 if (tree->key_destroy_func)
612 tree->key_destroy_func (node->key);
618 /* free the passed key */
619 if (tree->key_destroy_func)
620 tree->key_destroy_func (key);
630 old_balance = node->left->balance;
631 node->left = g_tree_node_insert (tree,
636 if ((old_balance != node->left->balance) && node->left->balance)
642 node->left = g_tree_node_new (key, value);
650 old_balance = node->right->balance;
651 node->right = g_tree_node_insert (tree,
656 if ((old_balance != node->right->balance) && node->right->balance)
662 node->right = g_tree_node_new (key, value);
669 if ((node->balance < -1) || (node->balance > 1))
670 node = g_tree_node_balance (node);
677 g_tree_node_remove (GTree *tree,
689 cmp = tree->key_compare (key, node->key, tree->key_compare_data);
702 old_balance = node->right->balance;
703 node->right = g_tree_node_remove_leftmost (node->right, &new_root);
704 new_root->left = node->left;
705 new_root->right = node->right;
706 new_root->balance = node->balance;
707 node = g_tree_node_restore_right_balance (new_root, old_balance);
712 if (tree->key_destroy_func)
713 tree->key_destroy_func (garbage->key);
714 if (tree->value_destroy_func)
715 tree->value_destroy_func (garbage->value);
718 #ifdef ENABLE_GC_FRIENDLY
719 garbage->left = NULL;
721 garbage->value = NULL;
722 #endif /* ENABLE_GC_FRIENDLY */
724 G_LOCK (g_tree_global);
725 garbage->right = node_free_list;
726 node_free_list = garbage;
727 G_UNLOCK (g_tree_global);
733 old_balance = node->left->balance;
734 node->left = g_tree_node_remove (tree, node->left, key, notify);
735 node = g_tree_node_restore_left_balance (node, old_balance);
742 old_balance = node->right->balance;
743 node->right = g_tree_node_remove (tree, node->right, key, notify);
744 node = g_tree_node_restore_right_balance (node, old_balance);
752 g_tree_node_balance (GTreeNode *node)
754 if (node->balance < -1)
756 if (node->left->balance > 0)
757 node->left = g_tree_node_rotate_left (node->left);
758 node = g_tree_node_rotate_right (node);
760 else if (node->balance > 1)
762 if (node->right->balance < 0)
763 node->right = g_tree_node_rotate_right (node->right);
764 node = g_tree_node_rotate_left (node);
771 g_tree_node_remove_leftmost (GTreeNode *node,
772 GTreeNode **leftmost)
782 old_balance = node->left->balance;
783 node->left = g_tree_node_remove_leftmost (node->left, leftmost);
784 return g_tree_node_restore_left_balance (node, old_balance);
788 g_tree_node_restore_left_balance (GTreeNode *node,
793 else if ((node->left->balance != old_balance) &&
794 (node->left->balance == 0))
797 if (node->balance > 1)
798 return g_tree_node_balance (node);
803 g_tree_node_restore_right_balance (GTreeNode *node,
808 else if ((node->right->balance != old_balance) &&
809 (node->right->balance == 0))
812 if (node->balance < -1)
813 return g_tree_node_balance (node);
818 g_tree_node_lookup (GTreeNode *node,
819 GCompareDataFunc compare,
820 gpointer compare_data,
828 cmp = (* compare) (key, node->key, compare_data);
835 return g_tree_node_lookup (node->left, compare, compare_data, key);
840 return g_tree_node_lookup (node->right, compare, compare_data, key);
847 g_tree_node_count (GTreeNode *node)
853 count += g_tree_node_count (node->left);
855 count += g_tree_node_count (node->right);
861 g_tree_node_pre_order (GTreeNode *node,
862 GTraverseFunc traverse_func,
865 if ((*traverse_func) (node->key, node->value, data))
869 if (g_tree_node_pre_order (node->left, traverse_func, data))
874 if (g_tree_node_pre_order (node->right, traverse_func, data))
882 g_tree_node_in_order (GTreeNode *node,
883 GTraverseFunc traverse_func,
888 if (g_tree_node_in_order (node->left, traverse_func, data))
891 if ((*traverse_func) (node->key, node->value, data))
895 if (g_tree_node_in_order (node->right, traverse_func, data))
903 g_tree_node_post_order (GTreeNode *node,
904 GTraverseFunc traverse_func,
909 if (g_tree_node_post_order (node->left, traverse_func, data))
914 if (g_tree_node_post_order (node->right, traverse_func, data))
917 if ((*traverse_func) (node->key, node->value, data))
924 g_tree_node_search (GTreeNode *node,
925 GCompareFunc search_func,
934 dir = (* search_func) (node->key, data);
948 g_tree_node_height (GTreeNode *node)
959 left_height = g_tree_node_height (node->left);
962 right_height = g_tree_node_height (node->right);
964 return MAX (left_height, right_height) + 1;
971 g_tree_node_rotate_left (GTreeNode *node)
979 node->right = right->left;
982 a_bal = node->balance;
983 b_bal = right->balance;
988 right->balance = b_bal - 1;
990 right->balance = a_bal + b_bal - 2;
991 node->balance = a_bal - 1;
996 right->balance = a_bal - 2;
998 right->balance = b_bal - 1;
999 node->balance = a_bal - b_bal - 1;
1006 g_tree_node_rotate_right (GTreeNode *node)
1014 node->left = left->right;
1017 a_bal = node->balance;
1018 b_bal = left->balance;
1023 left->balance = b_bal + 1;
1025 left->balance = a_bal + 2;
1026 node->balance = a_bal - b_bal + 1;
1031 left->balance = b_bal + 1;
1033 left->balance = a_bal + b_bal + 2;
1034 node->balance = a_bal + 1;
1041 g_tree_node_check (GTreeNode *node)
1053 left_height = g_tree_node_height (node->left);
1055 right_height = g_tree_node_height (node->right);
1057 balance = right_height - left_height;
1058 if (balance != node->balance)
1059 g_log (G_LOG_DOMAIN, G_LOG_LEVEL_INFO,
1060 "g_tree_node_check: failed: %d ( %d )\n",
1061 balance, node->balance);
1064 g_tree_node_check (node->left);
1066 g_tree_node_check (node->right);