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.
345 g_tree_remove (GTree *tree,
348 g_return_if_fail (tree != NULL);
350 tree->root = g_tree_node_remove (tree, tree->root, key, TRUE);
356 * @key: the key to remove.
358 * Removes a key and its associated value from a #GTree without calling
359 * the key and value destroy functions.
362 g_tree_steal (GTree *tree,
365 g_return_if_fail (tree != NULL);
367 tree->root = g_tree_node_remove (tree, tree->root, key, FALSE);
373 * @key: the key to look up.
375 * Gets the value corresponding to the given key. Since a #GTree is
376 * automatically balanced as key/value pairs are added, key lookup is very
379 * Return value: the value corresponding to the key.
382 g_tree_lookup (GTree *tree,
387 g_return_val_if_fail (tree != NULL, NULL);
389 node = g_tree_node_lookup (tree->root,
390 tree->key_compare, tree->key_compare_data, key);
392 return node ? node->value : NULL;
396 * g_tree_lookup_extended:
398 * @lookup_key: the key to look up.
399 * @orig_key: returns the original key.
400 * @value: returns the value associated with the key.
402 * Looks up a key in the #GTree, returning the original key and the
403 * associated value and a #gboolean which is %TRUE if the key was found. This
404 * is useful if you need to free the memory allocated for the original key,
405 * for example before calling g_tree_remove().
407 * Return value: %TRUE if the key was found in the #GTree.
410 g_tree_lookup_extended (GTree *tree,
411 gconstpointer lookup_key,
417 g_return_val_if_fail (tree != NULL, FALSE);
419 node = g_tree_node_lookup (tree->root,
420 tree->key_compare, tree->key_compare_data, lookup_key);
425 *orig_key = node->key;
427 *value = node->value;
437 * @func: the function to call for each node visited. If this function
438 * returns %TRUE, the traversal is stopped.
439 * @user_data: user data to pass to the function.
441 * Calls the given function for each of the key/value pairs in the #GTree.
442 * The function is passed the key and value of each pair, and the given
443 * @data parameter. The tree is traversed in sorted order.
445 * The tree may not be modified while iterating over it (you can't
446 * add/remove items). To remove all items matching a predicate, you need
447 * to add each item to a list in your #GTraverseFunc as you walk over
448 * the tree, then walk the list and remove each item.
451 g_tree_foreach (GTree *tree,
455 g_return_if_fail (tree != NULL);
460 g_tree_node_in_order (tree->root, func, user_data);
466 * @traverse_func: the function to call for each node visited. If this
467 * function returns %TRUE, the traversal is stopped.
468 * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
469 * %G_PRE_ORDER and %G_POST_ORDER.
470 * @user_data: user data to pass to the function.
472 * Calls the given function for each node in the #GTree.
474 * Deprecated: The order of a balanced tree is somewhat arbitrary. If you
475 * just want to visit all nodes in sorted order, use g_tree_foreach()
476 * instead. If you really need to visit nodes in a different order, consider
477 * using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
480 g_tree_traverse (GTree *tree,
481 GTraverseFunc traverse_func,
482 GTraverseType traverse_type,
485 g_return_if_fail (tree != NULL);
490 switch (traverse_type)
493 g_tree_node_pre_order (tree->root, traverse_func, user_data);
497 g_tree_node_in_order (tree->root, traverse_func, user_data);
501 g_tree_node_post_order (tree->root, traverse_func, user_data);
505 g_warning ("g_tree_traverse(): traverse type G_LEVEL_ORDER isn't implemented.");
513 * @search_func: a function used to search the #GTree.
514 * @user_data: the data passed as the second argument to the @search_func
517 * Searches a #GTree using @search_func.
519 * The @search_func is called with a pointer to the key of a key/value pair in the tree,
520 * and the passed in @user_data. If @search_func returns 0 for a key/value pair, then
521 * g_tree_search_func() will return the value of that pair. If @search_func returns -1,
522 * searching will proceed among the key/value pairs that have a smaller key; if @search_func
523 * returns 1, searching will proceed among the key/value pairs that have a larger key.
525 * Return value: the value corresponding to the found key, or %NULL if the key
529 g_tree_search (GTree *tree,
530 GCompareFunc search_func,
531 gconstpointer user_data)
533 g_return_val_if_fail (tree != NULL, NULL);
536 return g_tree_node_search (tree->root, search_func, user_data);
545 * Gets the height of a #GTree.
547 * If the #GTree contains no nodes, the height is 0.
548 * If the #GTree contains only one root node the height is 1.
549 * If the root node has children the height is 2, etc.
551 * Return value: the height of the #GTree.
554 g_tree_height (GTree *tree)
556 g_return_val_if_fail (tree != NULL, 0);
559 return g_tree_node_height (tree->root);
568 * Gets the number of nodes in a #GTree.
570 * Return value: the number of nodes in the #GTree.
573 g_tree_nnodes (GTree *tree)
575 g_return_val_if_fail (tree != NULL, 0);
578 return g_tree_node_count (tree->root);
584 g_tree_node_insert (GTree *tree,
597 return g_tree_node_new (key, value);
600 cmp = tree->key_compare (key, node->key, tree->key_compare_data);
605 if (tree->value_destroy_func)
606 tree->value_destroy_func (node->value);
612 if (tree->key_destroy_func)
613 tree->key_destroy_func (node->key);
619 /* free the passed key */
620 if (tree->key_destroy_func)
621 tree->key_destroy_func (key);
631 old_balance = node->left->balance;
632 node->left = g_tree_node_insert (tree,
637 if ((old_balance != node->left->balance) && node->left->balance)
643 node->left = g_tree_node_new (key, value);
651 old_balance = node->right->balance;
652 node->right = g_tree_node_insert (tree,
657 if ((old_balance != node->right->balance) && node->right->balance)
663 node->right = g_tree_node_new (key, value);
670 if ((node->balance < -1) || (node->balance > 1))
671 node = g_tree_node_balance (node);
678 g_tree_node_remove (GTree *tree,
690 cmp = tree->key_compare (key, node->key, tree->key_compare_data);
703 old_balance = node->right->balance;
704 node->right = g_tree_node_remove_leftmost (node->right, &new_root);
705 new_root->left = node->left;
706 new_root->right = node->right;
707 new_root->balance = node->balance;
708 node = g_tree_node_restore_right_balance (new_root, old_balance);
713 if (tree->key_destroy_func)
714 tree->key_destroy_func (garbage->key);
715 if (tree->value_destroy_func)
716 tree->value_destroy_func (garbage->value);
719 #ifdef ENABLE_GC_FRIENDLY
720 garbage->left = NULL;
722 garbage->value = NULL;
723 #endif /* ENABLE_GC_FRIENDLY */
725 G_LOCK (g_tree_global);
726 garbage->right = node_free_list;
727 node_free_list = garbage;
728 G_UNLOCK (g_tree_global);
734 old_balance = node->left->balance;
735 node->left = g_tree_node_remove (tree, node->left, key, notify);
736 node = g_tree_node_restore_left_balance (node, old_balance);
743 old_balance = node->right->balance;
744 node->right = g_tree_node_remove (tree, node->right, key, notify);
745 node = g_tree_node_restore_right_balance (node, old_balance);
753 g_tree_node_balance (GTreeNode *node)
755 if (node->balance < -1)
757 if (node->left->balance > 0)
758 node->left = g_tree_node_rotate_left (node->left);
759 node = g_tree_node_rotate_right (node);
761 else if (node->balance > 1)
763 if (node->right->balance < 0)
764 node->right = g_tree_node_rotate_right (node->right);
765 node = g_tree_node_rotate_left (node);
772 g_tree_node_remove_leftmost (GTreeNode *node,
773 GTreeNode **leftmost)
783 old_balance = node->left->balance;
784 node->left = g_tree_node_remove_leftmost (node->left, leftmost);
785 return g_tree_node_restore_left_balance (node, old_balance);
789 g_tree_node_restore_left_balance (GTreeNode *node,
794 else if ((node->left->balance != old_balance) &&
795 (node->left->balance == 0))
798 if (node->balance > 1)
799 return g_tree_node_balance (node);
804 g_tree_node_restore_right_balance (GTreeNode *node,
809 else if ((node->right->balance != old_balance) &&
810 (node->right->balance == 0))
813 if (node->balance < -1)
814 return g_tree_node_balance (node);
819 g_tree_node_lookup (GTreeNode *node,
820 GCompareDataFunc compare,
821 gpointer compare_data,
829 cmp = (* compare) (key, node->key, compare_data);
836 return g_tree_node_lookup (node->left, compare, compare_data, key);
841 return g_tree_node_lookup (node->right, compare, compare_data, key);
848 g_tree_node_count (GTreeNode *node)
854 count += g_tree_node_count (node->left);
856 count += g_tree_node_count (node->right);
862 g_tree_node_pre_order (GTreeNode *node,
863 GTraverseFunc traverse_func,
866 if ((*traverse_func) (node->key, node->value, data))
870 if (g_tree_node_pre_order (node->left, traverse_func, data))
875 if (g_tree_node_pre_order (node->right, traverse_func, data))
883 g_tree_node_in_order (GTreeNode *node,
884 GTraverseFunc traverse_func,
889 if (g_tree_node_in_order (node->left, traverse_func, data))
892 if ((*traverse_func) (node->key, node->value, data))
896 if (g_tree_node_in_order (node->right, traverse_func, data))
904 g_tree_node_post_order (GTreeNode *node,
905 GTraverseFunc traverse_func,
910 if (g_tree_node_post_order (node->left, traverse_func, data))
915 if (g_tree_node_post_order (node->right, traverse_func, data))
918 if ((*traverse_func) (node->key, node->value, data))
925 g_tree_node_search (GTreeNode *node,
926 GCompareFunc search_func,
935 dir = (* search_func) (node->key, data);
949 g_tree_node_height (GTreeNode *node)
960 left_height = g_tree_node_height (node->left);
963 right_height = g_tree_node_height (node->right);
965 return MAX (left_height, right_height) + 1;
972 g_tree_node_rotate_left (GTreeNode *node)
980 node->right = right->left;
983 a_bal = node->balance;
984 b_bal = right->balance;
989 right->balance = b_bal - 1;
991 right->balance = a_bal + b_bal - 2;
992 node->balance = a_bal - 1;
997 right->balance = a_bal - 2;
999 right->balance = b_bal - 1;
1000 node->balance = a_bal - b_bal - 1;
1007 g_tree_node_rotate_right (GTreeNode *node)
1015 node->left = left->right;
1018 a_bal = node->balance;
1019 b_bal = left->balance;
1024 left->balance = b_bal + 1;
1026 left->balance = a_bal + 2;
1027 node->balance = a_bal - b_bal + 1;
1032 left->balance = b_bal + 1;
1034 left->balance = a_bal + b_bal + 2;
1035 node->balance = a_bal + 1;
1042 g_tree_node_check (GTreeNode *node)
1054 left_height = g_tree_node_height (node->left);
1056 right_height = g_tree_node_height (node->right);
1058 balance = right_height - left_height;
1059 if (balance != node->balance)
1060 g_log (G_LOG_DOMAIN, G_LOG_LEVEL_INFO,
1061 "g_tree_node_check: failed: %d ( %d )\n",
1062 balance, node->balance);
1065 g_tree_node_check (node->left);
1067 g_tree_node_check (node->right);