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/.
37 typedef struct _GTreeNode GTreeNode;
42 GCompareDataFunc key_compare;
43 GDestroyNotify key_destroy_func;
44 GDestroyNotify value_destroy_func;
45 gpointer key_compare_data;
50 gint balance; /* height (left) - height (right) */
51 GTreeNode *left; /* left subtree */
52 GTreeNode *right; /* right subtree */
53 gpointer key; /* key for this node */
54 gpointer value; /* value stored at this node */
58 static GTreeNode* g_tree_node_new (gpointer key,
60 static void g_tree_node_destroy (GTreeNode *node,
61 GDestroyNotify key_destroy_func,
62 GDestroyNotify value_destroy_func);
63 static GTreeNode* g_tree_node_insert (GTree *tree,
69 static GTreeNode* g_tree_node_remove (GTree *tree,
73 static GTreeNode* g_tree_node_balance (GTreeNode *node);
74 static GTreeNode* g_tree_node_remove_leftmost (GTreeNode *node,
75 GTreeNode **leftmost);
76 static GTreeNode* g_tree_node_restore_left_balance (GTreeNode *node,
78 static GTreeNode* g_tree_node_restore_right_balance (GTreeNode *node,
80 static GTreeNode* g_tree_node_lookup (GTreeNode *node,
81 GCompareDataFunc compare,
84 static gint g_tree_node_count (GTreeNode *node);
85 static gint g_tree_node_pre_order (GTreeNode *node,
86 GTraverseFunc traverse_func,
88 static gint g_tree_node_in_order (GTreeNode *node,
89 GTraverseFunc traverse_func,
91 static gint g_tree_node_post_order (GTreeNode *node,
92 GTraverseFunc traverse_func,
94 static gpointer g_tree_node_search (GTreeNode *node,
95 GCompareFunc search_func,
97 static gint g_tree_node_height (GTreeNode *node);
98 static GTreeNode* g_tree_node_rotate_left (GTreeNode *node);
99 static GTreeNode* g_tree_node_rotate_right (GTreeNode *node);
100 static void g_tree_node_check (GTreeNode *node);
103 G_LOCK_DEFINE_STATIC (g_tree_global);
104 static GMemChunk *node_mem_chunk = NULL;
105 static GTreeNode *node_free_list = NULL;
109 g_tree_node_new (gpointer key,
114 G_LOCK (g_tree_global);
117 node = node_free_list;
118 node_free_list = node->right;
123 node_mem_chunk = g_mem_chunk_new ("GLib GTreeNode mem chunk",
128 node = g_chunk_new (GTreeNode, node_mem_chunk);
130 G_UNLOCK (g_tree_global);
142 g_tree_node_destroy (GTreeNode *node,
143 GDestroyNotify key_destroy_func,
144 GDestroyNotify value_destroy_func)
148 g_tree_node_destroy (node->right,
149 key_destroy_func, value_destroy_func);
150 g_tree_node_destroy (node->left,
151 key_destroy_func, value_destroy_func);
153 if (key_destroy_func)
154 key_destroy_func (node->key);
155 if (value_destroy_func)
156 value_destroy_func (node->value);
158 #ifdef ENABLE_GC_FRIENDLY
162 #endif /* ENABLE_GC_FRIENDLY */
164 G_LOCK (g_tree_global);
165 node->right = node_free_list;
166 node_free_list = node;
167 G_UNLOCK (g_tree_global);
173 * @key_compare_func: the function used to order the nodes in the #GTree.
174 * It should return values similar to the standard strcmp() function -
175 * 0 if the two arguments are equal, a negative value if the first argument
176 * comes before the second, or a positive value if the first argument comes
179 * Creates a new #GTree.
181 * Return value: a new #GTree.
184 g_tree_new (GCompareFunc key_compare_func)
186 g_return_val_if_fail (key_compare_func != NULL, NULL);
188 return g_tree_new_full ((GCompareDataFunc) key_compare_func, NULL,
193 * g_tree_new_with_data:
194 * @key_compare_func: qsort()-style comparison function.
195 * @key_compare_data: data to pass to comparison function.
197 * Creates a new #GTree with a comparison function that accepts user data.
198 * See g_tree_new() for more details.
200 * Return value: a new #GTree.
203 g_tree_new_with_data (GCompareDataFunc key_compare_func,
204 gpointer key_compare_data)
206 g_return_val_if_fail (key_compare_func != NULL, NULL);
208 return g_tree_new_full (key_compare_func, key_compare_data,
214 * @key_compare_func: qsort()-style comparison function.
215 * @key_compare_data: data to pass to comparison function.
216 * @key_destroy_func: a function to free the memory allocated for the key
217 * used when removing the entry from the #GTree or %NULL if you don't
218 * want to supply such a function.
219 * @value_destroy_func: a function to free the memory allocated for the
220 * value used when removing the entry from the #GTree or %NULL if you
221 * don't want to supply such a function.
223 * Creates a new #GTree like g_tree_new() and allows to specify functions
224 * to free the memory allocated for the key and value that get called when
225 * removing the entry from the #GTree.
227 * Return value: a new #GTree.
230 g_tree_new_full (GCompareDataFunc key_compare_func,
231 gpointer key_compare_data,
232 GDestroyNotify key_destroy_func,
233 GDestroyNotify value_destroy_func)
237 g_return_val_if_fail (key_compare_func != NULL, NULL);
239 tree = g_new (GTree, 1);
241 tree->key_compare = key_compare_func;
242 tree->key_destroy_func = key_destroy_func;
243 tree->value_destroy_func = value_destroy_func;
244 tree->key_compare_data = key_compare_data;
253 * Destroys the #GTree. If keys and/or values are dynamically allocated, you
254 * should either free them first or create the #GTree using g_tree_new_full().
255 * In the latter case the destroy functions you supplied will be called on
256 * all keys and values before destroying the #GTree.
259 g_tree_destroy (GTree *tree)
261 g_return_if_fail (tree != NULL);
263 g_tree_node_destroy (tree->root,
264 tree->key_destroy_func,
265 tree->value_destroy_func);
273 * @key: the key to insert.
274 * @value: the value corresponding to the key.
276 * Inserts a key/value pair into a #GTree. If the given key already exists
277 * in the #GTree its corresponding value is set to the new value. If you
278 * supplied a value_destroy_func when creating the #GTree, the old value is
279 * freed using that function. If you supplied a @key_destroy_func when
280 * creating the #GTree, the passed key is freed using that function.
282 * The tree is automatically 'balanced' as new key/value pairs are added,
283 * so that the distance from the root to every leaf is as small as possible.
286 g_tree_insert (GTree *tree,
292 g_return_if_fail (tree != NULL);
295 tree->root = g_tree_node_insert (tree,
304 * @key: the key to insert.
305 * @value: the value corresponding to the key.
307 * Inserts a new key and value into a #GTree similar to g_tree_insert().
308 * The difference is that if the key already exists in the #GTree, it gets
309 * replaced by the new key. If you supplied a @value_destroy_func when
310 * creating the #GTree, the old value is freed using that function. If you
311 * supplied a @key_destroy_func when creating the #GTree, the old key is
312 * freed using that function.
314 * The tree is automatically 'balanced' as new key/value pairs are added,
315 * so that the distance from the root to every leaf is as small as possible.
318 g_tree_replace (GTree *tree,
324 g_return_if_fail (tree != NULL);
327 tree->root = g_tree_node_insert (tree,
336 * @key: the key to remove.
338 * Removes a key/value pair from a #GTree.
340 * If the #GTree was created using g_tree_new_full(), the key and value
341 * are freed using the supplied destroy functions, otherwise you have to
342 * make sure that any dynamically allocated values are freed yourself.
343 * If the key does not exist in the #GTree, the function does nothing.
346 g_tree_remove (GTree *tree,
349 g_return_if_fail (tree != NULL);
351 tree->root = g_tree_node_remove (tree, tree->root, key, TRUE);
357 * @key: the key to remove.
359 * Removes a key and its associated value from a #GTree without calling
360 * the key and value destroy functions.
362 * If the key does not exist in the #GTree, the function does nothing.
365 g_tree_steal (GTree *tree,
368 g_return_if_fail (tree != NULL);
370 tree->root = g_tree_node_remove (tree, tree->root, key, FALSE);
376 * @key: the key to look up.
378 * Gets the value corresponding to the given key. Since a #GTree is
379 * automatically balanced as key/value pairs are added, key lookup is very
382 * Return value: the value corresponding to the key, or %NULL if the key was
386 g_tree_lookup (GTree *tree,
391 g_return_val_if_fail (tree != NULL, NULL);
393 node = g_tree_node_lookup (tree->root,
394 tree->key_compare, tree->key_compare_data, key);
396 return node ? node->value : NULL;
400 * g_tree_lookup_extended:
402 * @lookup_key: the key to look up.
403 * @orig_key: returns the original key.
404 * @value: returns the value associated with the key.
406 * Looks up a key in the #GTree, returning the original key and the
407 * associated value and a #gboolean which is %TRUE if the key was found. This
408 * is useful if you need to free the memory allocated for the original key,
409 * for example before calling g_tree_remove().
411 * Return value: %TRUE if the key was found in the #GTree.
414 g_tree_lookup_extended (GTree *tree,
415 gconstpointer lookup_key,
421 g_return_val_if_fail (tree != NULL, FALSE);
423 node = g_tree_node_lookup (tree->root,
424 tree->key_compare, tree->key_compare_data, lookup_key);
429 *orig_key = node->key;
431 *value = node->value;
441 * @func: the function to call for each node visited. If this function
442 * returns %TRUE, the traversal is stopped.
443 * @user_data: user data to pass to the function.
445 * Calls the given function for each of the key/value pairs in the #GTree.
446 * The function is passed the key and value of each pair, and the given
447 * @data parameter. The tree is traversed in sorted order.
449 * The tree may not be modified while iterating over it (you can't
450 * add/remove items). To remove all items matching a predicate, you need
451 * to add each item to a list in your #GTraverseFunc as you walk over
452 * the tree, then walk the list and remove each item.
455 g_tree_foreach (GTree *tree,
459 g_return_if_fail (tree != NULL);
464 g_tree_node_in_order (tree->root, func, user_data);
470 * @traverse_func: the function to call for each node visited. If this
471 * function returns %TRUE, the traversal is stopped.
472 * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
473 * %G_PRE_ORDER and %G_POST_ORDER.
474 * @user_data: user data to pass to the function.
476 * Calls the given function for each node in the #GTree.
478 * Deprecated: The order of a balanced tree is somewhat arbitrary. If you
479 * just want to visit all nodes in sorted order, use g_tree_foreach()
480 * instead. If you really need to visit nodes in a different order, consider
481 * using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
484 g_tree_traverse (GTree *tree,
485 GTraverseFunc traverse_func,
486 GTraverseType traverse_type,
489 g_return_if_fail (tree != NULL);
494 switch (traverse_type)
497 g_tree_node_pre_order (tree->root, traverse_func, user_data);
501 g_tree_node_in_order (tree->root, traverse_func, user_data);
505 g_tree_node_post_order (tree->root, traverse_func, user_data);
509 g_warning ("g_tree_traverse(): traverse type G_LEVEL_ORDER isn't implemented.");
517 * @search_func: a function used to search the #GTree.
518 * @user_data: the data passed as the second argument to the @search_func
521 * Searches a #GTree using @search_func.
523 * The @search_func is called with a pointer to the key of a key/value pair in the tree,
524 * and the passed in @user_data. If @search_func returns 0 for a key/value pair, then
525 * g_tree_search_func() will return the value of that pair. If @search_func returns -1,
526 * searching will proceed among the key/value pairs that have a smaller key; if @search_func
527 * returns 1, searching will proceed among the key/value pairs that have a larger key.
529 * Return value: the value corresponding to the found key, or %NULL if the key
533 g_tree_search (GTree *tree,
534 GCompareFunc search_func,
535 gconstpointer user_data)
537 g_return_val_if_fail (tree != NULL, NULL);
540 return g_tree_node_search (tree->root, search_func, user_data);
549 * Gets the height of a #GTree.
551 * If the #GTree contains no nodes, the height is 0.
552 * If the #GTree contains only one root node the height is 1.
553 * If the root node has children the height is 2, etc.
555 * Return value: the height of the #GTree.
558 g_tree_height (GTree *tree)
560 g_return_val_if_fail (tree != NULL, 0);
563 return g_tree_node_height (tree->root);
572 * Gets the number of nodes in a #GTree.
574 * Return value: the number of nodes in the #GTree.
577 g_tree_nnodes (GTree *tree)
579 g_return_val_if_fail (tree != NULL, 0);
582 return g_tree_node_count (tree->root);
588 g_tree_node_insert (GTree *tree,
601 return g_tree_node_new (key, value);
604 cmp = tree->key_compare (key, node->key, tree->key_compare_data);
609 if (tree->value_destroy_func)
610 tree->value_destroy_func (node->value);
616 if (tree->key_destroy_func)
617 tree->key_destroy_func (node->key);
623 /* free the passed key */
624 if (tree->key_destroy_func)
625 tree->key_destroy_func (key);
635 old_balance = node->left->balance;
636 node->left = g_tree_node_insert (tree,
641 if ((old_balance != node->left->balance) && node->left->balance)
647 node->left = g_tree_node_new (key, value);
655 old_balance = node->right->balance;
656 node->right = g_tree_node_insert (tree,
661 if ((old_balance != node->right->balance) && node->right->balance)
667 node->right = g_tree_node_new (key, value);
674 if ((node->balance < -1) || (node->balance > 1))
675 node = g_tree_node_balance (node);
682 g_tree_node_remove (GTree *tree,
694 cmp = tree->key_compare (key, node->key, tree->key_compare_data);
707 old_balance = node->right->balance;
708 node->right = g_tree_node_remove_leftmost (node->right, &new_root);
709 new_root->left = node->left;
710 new_root->right = node->right;
711 new_root->balance = node->balance;
712 node = g_tree_node_restore_right_balance (new_root, old_balance);
717 if (tree->key_destroy_func)
718 tree->key_destroy_func (garbage->key);
719 if (tree->value_destroy_func)
720 tree->value_destroy_func (garbage->value);
723 #ifdef ENABLE_GC_FRIENDLY
724 garbage->left = NULL;
726 garbage->value = NULL;
727 #endif /* ENABLE_GC_FRIENDLY */
729 G_LOCK (g_tree_global);
730 garbage->right = node_free_list;
731 node_free_list = garbage;
732 G_UNLOCK (g_tree_global);
738 old_balance = node->left->balance;
739 node->left = g_tree_node_remove (tree, node->left, key, notify);
740 node = g_tree_node_restore_left_balance (node, old_balance);
747 old_balance = node->right->balance;
748 node->right = g_tree_node_remove (tree, node->right, key, notify);
749 node = g_tree_node_restore_right_balance (node, old_balance);
757 g_tree_node_balance (GTreeNode *node)
759 if (node->balance < -1)
761 if (node->left->balance > 0)
762 node->left = g_tree_node_rotate_left (node->left);
763 node = g_tree_node_rotate_right (node);
765 else if (node->balance > 1)
767 if (node->right->balance < 0)
768 node->right = g_tree_node_rotate_right (node->right);
769 node = g_tree_node_rotate_left (node);
776 g_tree_node_remove_leftmost (GTreeNode *node,
777 GTreeNode **leftmost)
787 old_balance = node->left->balance;
788 node->left = g_tree_node_remove_leftmost (node->left, leftmost);
789 return g_tree_node_restore_left_balance (node, old_balance);
793 g_tree_node_restore_left_balance (GTreeNode *node,
798 else if ((node->left->balance != old_balance) &&
799 (node->left->balance == 0))
802 if (node->balance > 1)
803 return g_tree_node_balance (node);
808 g_tree_node_restore_right_balance (GTreeNode *node,
813 else if ((node->right->balance != old_balance) &&
814 (node->right->balance == 0))
817 if (node->balance < -1)
818 return g_tree_node_balance (node);
823 g_tree_node_lookup (GTreeNode *node,
824 GCompareDataFunc compare,
825 gpointer compare_data,
833 cmp = (* compare) (key, node->key, compare_data);
840 return g_tree_node_lookup (node->left, compare, compare_data, key);
845 return g_tree_node_lookup (node->right, compare, compare_data, key);
852 g_tree_node_count (GTreeNode *node)
858 count += g_tree_node_count (node->left);
860 count += g_tree_node_count (node->right);
866 g_tree_node_pre_order (GTreeNode *node,
867 GTraverseFunc traverse_func,
870 if ((*traverse_func) (node->key, node->value, data))
874 if (g_tree_node_pre_order (node->left, traverse_func, data))
879 if (g_tree_node_pre_order (node->right, traverse_func, data))
887 g_tree_node_in_order (GTreeNode *node,
888 GTraverseFunc traverse_func,
893 if (g_tree_node_in_order (node->left, traverse_func, data))
896 if ((*traverse_func) (node->key, node->value, data))
900 if (g_tree_node_in_order (node->right, traverse_func, data))
908 g_tree_node_post_order (GTreeNode *node,
909 GTraverseFunc traverse_func,
914 if (g_tree_node_post_order (node->left, traverse_func, data))
919 if (g_tree_node_post_order (node->right, traverse_func, data))
922 if ((*traverse_func) (node->key, node->value, data))
929 g_tree_node_search (GTreeNode *node,
930 GCompareFunc search_func,
939 dir = (* search_func) (node->key, data);
953 g_tree_node_height (GTreeNode *node)
964 left_height = g_tree_node_height (node->left);
967 right_height = g_tree_node_height (node->right);
969 return MAX (left_height, right_height) + 1;
976 g_tree_node_rotate_left (GTreeNode *node)
984 node->right = right->left;
987 a_bal = node->balance;
988 b_bal = right->balance;
993 right->balance = b_bal - 1;
995 right->balance = a_bal + b_bal - 2;
996 node->balance = a_bal - 1;
1001 right->balance = a_bal - 2;
1003 right->balance = b_bal - 1;
1004 node->balance = a_bal - b_bal - 1;
1011 g_tree_node_rotate_right (GTreeNode *node)
1019 node->left = left->right;
1022 a_bal = node->balance;
1023 b_bal = left->balance;
1028 left->balance = b_bal + 1;
1030 left->balance = a_bal + 2;
1031 node->balance = a_bal - b_bal + 1;
1036 left->balance = b_bal + 1;
1038 left->balance = a_bal + b_bal + 2;
1039 node->balance = a_bal + 1;
1046 g_tree_node_check (GTreeNode *node)
1058 left_height = g_tree_node_height (node->left);
1060 right_height = g_tree_node_height (node->right);
1062 balance = right_height - left_height;
1063 if (balance != node->balance)
1064 g_log (G_LOG_DOMAIN, G_LOG_LEVEL_INFO,
1065 "g_tree_node_check: failed: %d ( %d )\n",
1066 balance, node->balance);
1069 g_tree_node_check (node->left);
1071 g_tree_node_check (node->right);
1075 #define __G_TREE_C__
1076 #include "galiasdef.c"