1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * GNode: N-way tree implementation.
5 * Copyright (C) 1998 Tim Janik
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
24 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
25 * file for a list of people on the GLib Team. See the ChangeLog
26 * files for a list of changes. These files are distributed with
27 * GLib at ftp://ftp.gtk.org/pub/gtk/.
39 void g_node_push_allocator (gpointer dummy
) { /* present for binary compat only */ }
40 void g_node_pop_allocator (void) { /* present for binary compat only */ }
42 #define g_node_alloc0() g_slice_new0 (GNode)
43 #define g_node_free(node) g_slice_free (GNode, node)
45 /* --- functions --- */
48 * @data: the data of the new node
50 * Creates a new #GNode containing the given data.
51 * Used to create the first node in a tree.
53 * Returns: a new #GNode
56 g_node_new (gpointer data
)
58 GNode
*node
= g_node_alloc0 ();
64 g_nodes_free (GNode
*node
)
68 GNode
*next
= node
->next
;
70 g_nodes_free (node
->children
);
78 * @root: the root of the tree/subtree to destroy
80 * Removes @root and its children from the tree, freeing any memory
84 g_node_destroy (GNode
*root
)
86 g_return_if_fail (root
!= NULL
);
88 if (!G_NODE_IS_ROOT (root
))
96 * @node: the #GNode to unlink, which becomes the root of a new tree
98 * Unlinks a #GNode from a tree, resulting in two separate trees.
101 g_node_unlink (GNode
*node
)
103 g_return_if_fail (node
!= NULL
);
106 node
->prev
->next
= node
->next
;
107 else if (node
->parent
)
108 node
->parent
->children
= node
->next
;
112 node
->next
->prev
= node
->prev
;
121 * @copy_func: the function which is called to copy the data inside each node,
122 * or %NULL to use the original data.
123 * @data: data to pass to @copy_func
125 * Recursively copies a #GNode and its data.
127 * Return value: a new #GNode containing copies of the data in @node.
132 g_node_copy_deep (GNode
*node
,
136 GNode
*new_node
= NULL
;
138 if (copy_func
== NULL
)
139 return g_node_copy (node
);
143 GNode
*child
, *new_child
;
145 new_node
= g_node_new (copy_func (node
->data
, data
));
147 for (child
= g_node_last_child (node
); child
; child
= child
->prev
)
149 new_child
= g_node_copy_deep (child
, copy_func
, data
);
150 g_node_prepend (new_node
, new_child
);
161 * Recursively copies a #GNode (but does not deep-copy the data inside the
162 * nodes, see g_node_copy_deep() if you need that).
164 * Returns: a new #GNode containing the same data pointers
167 g_node_copy (GNode
*node
)
169 GNode
*new_node
= NULL
;
175 new_node
= g_node_new (node
->data
);
177 for (child
= g_node_last_child (node
); child
; child
= child
->prev
)
178 g_node_prepend (new_node
, g_node_copy (child
));
186 * @parent: the #GNode to place @node under
187 * @position: the position to place @node at, with respect to its siblings
188 * If position is -1, @node is inserted as the last child of @parent
189 * @node: the #GNode to insert
191 * Inserts a #GNode beneath the parent at the given position.
193 * Returns: the inserted #GNode
196 g_node_insert (GNode
*parent
,
200 g_return_val_if_fail (parent
!= NULL
, node
);
201 g_return_val_if_fail (node
!= NULL
, node
);
202 g_return_val_if_fail (G_NODE_IS_ROOT (node
), node
);
205 return g_node_insert_before (parent
,
206 g_node_nth_child (parent
, position
),
208 else if (position
== 0)
209 return g_node_prepend (parent
, node
);
210 else /* if (position < 0) */
211 return g_node_append (parent
, node
);
215 * g_node_insert_before:
216 * @parent: the #GNode to place @node under
217 * @sibling: the sibling #GNode to place @node before.
218 * If sibling is %NULL, the node is inserted as the last child of @parent.
219 * @node: the #GNode to insert
221 * Inserts a #GNode beneath the parent before the given sibling.
223 * Returns: the inserted #GNode
226 g_node_insert_before (GNode
*parent
,
230 g_return_val_if_fail (parent
!= NULL
, node
);
231 g_return_val_if_fail (node
!= NULL
, node
);
232 g_return_val_if_fail (G_NODE_IS_ROOT (node
), node
);
234 g_return_val_if_fail (sibling
->parent
== parent
, node
);
236 node
->parent
= parent
;
242 node
->prev
= sibling
->prev
;
243 node
->prev
->next
= node
;
244 node
->next
= sibling
;
245 sibling
->prev
= node
;
249 node
->parent
->children
= node
;
250 node
->next
= sibling
;
251 sibling
->prev
= node
;
256 if (parent
->children
)
258 sibling
= parent
->children
;
259 while (sibling
->next
)
260 sibling
= sibling
->next
;
261 node
->prev
= sibling
;
262 sibling
->next
= node
;
265 node
->parent
->children
= node
;
272 * g_node_insert_after:
273 * @parent: the #GNode to place @node under
274 * @sibling: the sibling #GNode to place @node after.
275 * If sibling is %NULL, the node is inserted as the first child of @parent.
276 * @node: the #GNode to insert
278 * Inserts a #GNode beneath the parent after the given sibling.
280 * Returns: the inserted #GNode
283 g_node_insert_after (GNode
*parent
,
287 g_return_val_if_fail (parent
!= NULL
, node
);
288 g_return_val_if_fail (node
!= NULL
, node
);
289 g_return_val_if_fail (G_NODE_IS_ROOT (node
), node
);
291 g_return_val_if_fail (sibling
->parent
== parent
, node
);
293 node
->parent
= parent
;
299 sibling
->next
->prev
= node
;
301 node
->next
= sibling
->next
;
302 node
->prev
= sibling
;
303 sibling
->next
= node
;
307 if (parent
->children
)
309 node
->next
= parent
->children
;
310 parent
->children
->prev
= node
;
312 parent
->children
= node
;
320 * @parent: the #GNode to place the new #GNode under
321 * @node: the #GNode to insert
323 * Inserts a #GNode as the first child of the given parent.
325 * Returns: the inserted #GNode
328 g_node_prepend (GNode
*parent
,
331 g_return_val_if_fail (parent
!= NULL
, node
);
333 return g_node_insert_before (parent
, parent
->children
, node
);
340 * Gets the root of a tree.
342 * Returns: the root of the tree
345 g_node_get_root (GNode
*node
)
347 g_return_val_if_fail (node
!= NULL
, NULL
);
356 * g_node_is_ancestor:
358 * @descendant: a #GNode
360 * Returns %TRUE if @node is an ancestor of @descendant.
361 * This is true if node is the parent of @descendant,
362 * or if node is the grandparent of @descendant etc.
364 * Returns: %TRUE if @node is an ancestor of @descendant
367 g_node_is_ancestor (GNode
*node
,
370 g_return_val_if_fail (node
!= NULL
, FALSE
);
371 g_return_val_if_fail (descendant
!= NULL
, FALSE
);
375 if (descendant
->parent
== node
)
378 descendant
= descendant
->parent
;
388 * Gets the depth of a #GNode.
390 * If @node is %NULL the depth is 0. The root node has a depth of 1.
391 * For the children of the root node the depth is 2. And so on.
393 * Returns: the depth of the #GNode
396 g_node_depth (GNode
*node
)
410 * g_node_reverse_children:
413 * Reverses the order of the children of a #GNode.
414 * (It doesn't change the order of the grandchildren.)
417 g_node_reverse_children (GNode
*node
)
422 g_return_if_fail (node
!= NULL
);
424 child
= node
->children
;
430 last
->next
= last
->prev
;
433 node
->children
= last
;
440 * Gets the maximum height of all branches beneath a #GNode.
441 * This is the maximum distance from the #GNode to all leaf nodes.
443 * If @root is %NULL, 0 is returned. If @root has no children,
444 * 1 is returned. If @root has children, 2 is returned. And so on.
446 * Returns: the maximum height of the tree beneath @root
449 g_node_max_height (GNode
*root
)
452 guint max_height
= 0;
457 child
= root
->children
;
462 tmp_height
= g_node_max_height (child
);
463 if (tmp_height
> max_height
)
464 max_height
= tmp_height
;
468 return max_height
+ 1;
472 g_node_traverse_pre_order (GNode
*node
,
473 GTraverseFlags flags
,
474 GNodeTraverseFunc func
,
481 if ((flags
& G_TRAVERSE_NON_LEAFS
) &&
485 child
= node
->children
;
491 child
= current
->next
;
492 if (g_node_traverse_pre_order (current
, flags
, func
, data
))
496 else if ((flags
& G_TRAVERSE_LEAFS
) &&
504 g_node_depth_traverse_pre_order (GNode
*node
,
505 GTraverseFlags flags
,
507 GNodeTraverseFunc func
,
514 if ((flags
& G_TRAVERSE_NON_LEAFS
) &&
522 child
= node
->children
;
528 child
= current
->next
;
529 if (g_node_depth_traverse_pre_order (current
, flags
, depth
, func
, data
))
533 else if ((flags
& G_TRAVERSE_LEAFS
) &&
541 g_node_traverse_post_order (GNode
*node
,
542 GTraverseFlags flags
,
543 GNodeTraverseFunc func
,
550 child
= node
->children
;
556 child
= current
->next
;
557 if (g_node_traverse_post_order (current
, flags
, func
, data
))
561 if ((flags
& G_TRAVERSE_NON_LEAFS
) &&
566 else if ((flags
& G_TRAVERSE_LEAFS
) &&
574 g_node_depth_traverse_post_order (GNode
*node
,
575 GTraverseFlags flags
,
577 GNodeTraverseFunc func
,
587 child
= node
->children
;
593 child
= current
->next
;
594 if (g_node_depth_traverse_post_order (current
, flags
, depth
, func
, data
))
599 if ((flags
& G_TRAVERSE_NON_LEAFS
) &&
604 else if ((flags
& G_TRAVERSE_LEAFS
) &&
612 g_node_traverse_in_order (GNode
*node
,
613 GTraverseFlags flags
,
614 GNodeTraverseFunc func
,
622 child
= node
->children
;
624 child
= current
->next
;
626 if (g_node_traverse_in_order (current
, flags
, func
, data
))
629 if ((flags
& G_TRAVERSE_NON_LEAFS
) &&
636 child
= current
->next
;
637 if (g_node_traverse_in_order (current
, flags
, func
, data
))
641 else if ((flags
& G_TRAVERSE_LEAFS
) &&
649 g_node_depth_traverse_in_order (GNode
*node
,
650 GTraverseFlags flags
,
652 GNodeTraverseFunc func
,
663 child
= node
->children
;
665 child
= current
->next
;
667 if (g_node_depth_traverse_in_order (current
, flags
, depth
, func
, data
))
670 if ((flags
& G_TRAVERSE_NON_LEAFS
) &&
677 child
= current
->next
;
678 if (g_node_depth_traverse_in_order (current
, flags
, depth
, func
, data
))
682 else if ((flags
& G_TRAVERSE_NON_LEAFS
) &&
686 else if ((flags
& G_TRAVERSE_LEAFS
) &&
694 g_node_traverse_level (GNode
*node
,
695 GTraverseFlags flags
,
697 GNodeTraverseFunc func
,
699 gboolean
*more_levels
)
706 return (flags
& G_TRAVERSE_NON_LEAFS
) && func (node
, data
);
710 return (flags
& G_TRAVERSE_LEAFS
) && func (node
, data
);
715 node
= node
->children
;
719 if (g_node_traverse_level (node
, flags
, level
- 1, func
, data
, more_levels
))
730 g_node_depth_traverse_level (GNode
*node
,
731 GTraverseFlags flags
,
733 GNodeTraverseFunc func
,
737 gboolean more_levels
;
740 while (level
!= depth
)
743 if (g_node_traverse_level (node
, flags
, level
, func
, data
, &more_levels
))
754 * @root: the root #GNode of the tree to traverse
755 * @order: the order in which nodes are visited - %G_IN_ORDER,
756 * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER.
757 * @flags: which types of children are to be visited, one of
758 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
759 * @max_depth: the maximum depth of the traversal. Nodes below this
760 * depth will not be visited. If max_depth is -1 all nodes in
761 * the tree are visited. If depth is 1, only the root is visited.
762 * If depth is 2, the root and its children are visited. And so on.
763 * @func: the function to call for each visited #GNode
764 * @data: user data to pass to the function
766 * Traverses a tree starting at the given root #GNode.
767 * It calls the given function for each node visited.
768 * The traversal can be halted at any point by returning %TRUE from @func.
771 g_node_traverse (GNode
*root
,
773 GTraverseFlags flags
,
775 GNodeTraverseFunc func
,
778 g_return_if_fail (root
!= NULL
);
779 g_return_if_fail (func
!= NULL
);
780 g_return_if_fail (order
<= G_LEVEL_ORDER
);
781 g_return_if_fail (flags
<= G_TRAVERSE_MASK
);
782 g_return_if_fail (depth
== -1 || depth
> 0);
788 g_node_traverse_pre_order (root
, flags
, func
, data
);
790 g_node_depth_traverse_pre_order (root
, flags
, depth
, func
, data
);
794 g_node_traverse_post_order (root
, flags
, func
, data
);
796 g_node_depth_traverse_post_order (root
, flags
, depth
, func
, data
);
800 g_node_traverse_in_order (root
, flags
, func
, data
);
802 g_node_depth_traverse_in_order (root
, flags
, depth
, func
, data
);
805 g_node_depth_traverse_level (root
, flags
, depth
, func
, data
);
811 g_node_find_func (GNode
*node
,
816 if (*d
!= node
->data
)
826 * @root: the root #GNode of the tree to search
827 * @order: the order in which nodes are visited - %G_IN_ORDER,
828 * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER
829 * @flags: which types of children are to be searched, one of
830 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
831 * @data: the data to find
833 * Finds a #GNode in a tree.
835 * Returns: the found #GNode, or %NULL if the data is not found
838 g_node_find (GNode
*root
,
840 GTraverseFlags flags
,
845 g_return_val_if_fail (root
!= NULL
, NULL
);
846 g_return_val_if_fail (order
<= G_LEVEL_ORDER
, NULL
);
847 g_return_val_if_fail (flags
<= G_TRAVERSE_MASK
, NULL
);
852 g_node_traverse (root
, order
, flags
, -1, g_node_find_func
, d
);
858 g_node_count_func (GNode
*node
,
859 GTraverseFlags flags
,
866 if (flags
& G_TRAVERSE_NON_LEAFS
)
869 child
= node
->children
;
872 g_node_count_func (child
, flags
, n
);
876 else if (flags
& G_TRAVERSE_LEAFS
)
883 * @flags: which types of children are to be counted, one of
884 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
886 * Gets the number of nodes in a tree.
888 * Returns: the number of nodes in the tree
891 g_node_n_nodes (GNode
*root
,
892 GTraverseFlags flags
)
896 g_return_val_if_fail (root
!= NULL
, 0);
897 g_return_val_if_fail (flags
<= G_TRAVERSE_MASK
, 0);
899 g_node_count_func (root
, flags
, &n
);
906 * @node: a #GNode (must not be %NULL)
908 * Gets the last child of a #GNode.
910 * Returns: the last child of @node, or %NULL if @node has no children
913 g_node_last_child (GNode
*node
)
915 g_return_val_if_fail (node
!= NULL
, NULL
);
917 node
= node
->children
;
928 * @n: the index of the desired child
930 * Gets a child of a #GNode, using the given index.
931 * The first child is at index 0. If the index is
932 * too big, %NULL is returned.
934 * Returns: the child of @node at index @n
937 g_node_nth_child (GNode
*node
,
940 g_return_val_if_fail (node
!= NULL
, NULL
);
942 node
= node
->children
;
944 while ((n
-- > 0) && node
)
954 * Gets the number of children of a #GNode.
956 * Returns: the number of children of @node
959 g_node_n_children (GNode
*node
)
963 g_return_val_if_fail (node
!= NULL
, 0);
965 node
= node
->children
;
978 * @flags: which types of children are to be searched, one of
979 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
980 * @data: the data to find
982 * Finds the first child of a #GNode with the given data.
984 * Returns: the found child #GNode, or %NULL if the data is not found
987 g_node_find_child (GNode
*node
,
988 GTraverseFlags flags
,
991 g_return_val_if_fail (node
!= NULL
, NULL
);
992 g_return_val_if_fail (flags
<= G_TRAVERSE_MASK
, NULL
);
994 node
= node
->children
;
997 if (node
->data
== data
)
999 if (G_NODE_IS_LEAF (node
))
1001 if (flags
& G_TRAVERSE_LEAFS
)
1006 if (flags
& G_TRAVERSE_NON_LEAFS
)
1017 * g_node_child_position:
1019 * @child: a child of @node
1021 * Gets the position of a #GNode with respect to its siblings.
1022 * @child must be a child of @node. The first child is numbered 0,
1023 * the second 1, and so on.
1025 * Returns: the position of @child with respect to its siblings
1028 g_node_child_position (GNode
*node
,
1033 g_return_val_if_fail (node
!= NULL
, -1);
1034 g_return_val_if_fail (child
!= NULL
, -1);
1035 g_return_val_if_fail (child
->parent
== node
, -1);
1037 node
= node
->children
;
1050 * g_node_child_index:
1052 * @data: the data to find
1054 * Gets the position of the first child of a #GNode
1055 * which contains the given data.
1057 * Returns: the index of the child of @node which contains
1058 * @data, or -1 if the data is not found
1061 g_node_child_index (GNode
*node
,
1066 g_return_val_if_fail (node
!= NULL
, -1);
1068 node
= node
->children
;
1071 if (node
->data
== data
)
1081 * g_node_first_sibling:
1084 * Gets the first sibling of a #GNode.
1085 * This could possibly be the node itself.
1087 * Returns: the first sibling of @node
1090 g_node_first_sibling (GNode
*node
)
1092 g_return_val_if_fail (node
!= NULL
, NULL
);
1095 return node
->parent
->children
;
1104 * g_node_last_sibling:
1107 * Gets the last sibling of a #GNode.
1108 * This could possibly be the node itself.
1110 * Returns: the last sibling of @node
1113 g_node_last_sibling (GNode
*node
)
1115 g_return_val_if_fail (node
!= NULL
, NULL
);
1124 * g_node_children_foreach:
1126 * @flags: which types of children are to be visited, one of
1127 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
1128 * @func: the function to call for each visited node
1129 * @data: user data to pass to the function
1131 * Calls a function for each of the children of a #GNode.
1132 * Note that it doesn't descend beneath the child nodes.
1135 g_node_children_foreach (GNode
*node
,
1136 GTraverseFlags flags
,
1137 GNodeForeachFunc func
,
1140 g_return_if_fail (node
!= NULL
);
1141 g_return_if_fail (flags
<= G_TRAVERSE_MASK
);
1142 g_return_if_fail (func
!= NULL
);
1144 node
= node
->children
;
1150 node
= current
->next
;
1151 if (G_NODE_IS_LEAF (current
))
1153 if (flags
& G_TRAVERSE_LEAFS
)
1154 func (current
, data
);
1158 if (flags
& G_TRAVERSE_NON_LEAFS
)
1159 func (current
, data
);
1164 #define __G_NODE_C__
1165 #include "galiasdef.c"