From cf9b04e7df58712a2cd06de4df73fb1aa27db835 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 28 Jan 2008 04:50:12 +0000 Subject: [PATCH] Move docs inline. (#316260, Philippe Blain) 2008-01-27 Matthias Clasen * glib/gnode.[hc]: Move docs inline. (#316260, Philippe Blain) svn path=/trunk/; revision=6392 --- ChangeLog | 4 + docs/reference/ChangeLog | 4 + docs/reference/glib/tmpl/trees-nary.sgml | 314 +++++++++++++---------------- glib/gnode.c | 333 +++++++++++++++++++++++++++---- glib/gnode.h | 111 +++++++++++ 5 files changed, 546 insertions(+), 220 deletions(-) diff --git a/ChangeLog b/ChangeLog index 439bf19..5483e39 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2008-01-27 Matthias Clasen + * glib/gnode.[hc]: Move docs inline. (#316260, Philippe Blain) + +2008-01-27 Matthias Clasen + * glib/gutf8.c (g_utf8_strreverse): Document limitations of this function. (#487909, Peter Moulder) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index db7b5a0..52d54a1 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,9 @@ 2008-01-27 Matthias Clasen + * glib/tmpl/trees-nary.sgml: Move docs inline + +2008-01-27 Matthias Clasen + * glib/tmpl/macros_misc.sgml: Document G_GNUC_(PRETTY)_FUNCTION as deprecated. diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index 0e2c2a1..424b322 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -71,34 +71,30 @@ fields -Creates a new #GNode containing the given data. -Used to create the first node in a tree. + -@data: the data of the new node. -@Returns: a new #GNode. +@data: +@Returns: -Recursively copies a #GNode (but does not deep-copy the data inside the nodes, -see g_node_copy_deep() if you need that). + -@node: a #GNode. -@Returns: a new #GNode containing the same data pointers. +@node: +@Returns: -A function of this signature is used to copy the node data when doing a deep-copy -of a tree. + -@src: A pointer to the data which should be copied. -@data: Additional data. -@Returns: A pointer to the copy. -@Since: 2.4 +@src: +@data: +@Returns: @@ -114,130 +110,118 @@ of a tree. -Inserts a #GNode beneath the parent at the given position. + -@parent: the #GNode to place @node under. -@position: the position to place @node at, with respect to its siblings. -If position is -1, @node is inserted as the last child of @parent. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@position: +@node: +@Returns: -Inserts a #GNode beneath the parent before the given sibling. + -@parent: the #GNode to place @node under. -@sibling: the sibling #GNode to place @node before. If sibling is %NULL, -the node is inserted as the last child of @parent. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@sibling: +@node: +@Returns: -Inserts a #GNode beneath the parent after the given sibling. + -@parent: the #GNode to place @node under. -@sibling: the sibling #GNode to place @node after. If sibling is %NULL, -the node is inserted as the first child of @parent. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@sibling: +@node: +@Returns: -Inserts a #GNode as the last child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@node: +@Returns: -Inserts a #GNode as the first child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@node: +@Returns: -Inserts a new #GNode at the given position. + -@parent: the #GNode to place the new #GNode under. -@position: the position to place the new #GNode at. -If position is -1, the new #GNode is inserted as the last child of @parent. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@position: +@data: +@Returns: -Inserts a new #GNode before the given sibling. + -@parent: the #GNode to place the new #GNode under. -@sibling: the sibling #GNode to place the new #GNode before. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@sibling: +@data: +@Returns: -Inserts a new #GNode as the last child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@data: +@Returns: -Inserts a new #GNode as the first child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@data: +@Returns: -Reverses the order of the children of a #GNode. -(It doesn't change the order of the grandchildren.) + -@node: a #GNode. +@node: -Traverses a tree starting at the given root #GNode. -It calls the given function for each node visited. -The traversal can be halted at any point by returning %TRUE from @func. + -@root: the root #GNode of the tree to traverse. -@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, -%G_POST_ORDER, or %G_LEVEL_ORDER. -@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES. -@max_depth: the maximum depth of the traversal. Nodes below this -depth will not be visited. If max_depth is -1 all nodes in the tree are -visited. If depth is 1, only the root is visited. If depth is 2, the root -and its children are visited. And so on. -@func: the function to call for each visited #GNode. -@data: user data to pass to the function. +@root: +@order: +@flags: +@max_depth: +@func: +@data: @@ -270,15 +254,13 @@ If the function returns %TRUE, then the traversal is stopped. -Calls a function for each of the children of a #GNode. -Note that it doesn't descend beneath the child nodes. + -@node: a #GNode. -@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES. -@func: the function to call for each visited node. -@data: user data to pass to the function. +@node: +@flags: +@func: +@data: @@ -294,223 +276,199 @@ passed to g_node_children_foreach(). -Gets the root of a tree. + -@node: a #GNode. -@Returns: the root of the tree. +@node: +@Returns: -Finds a #GNode in a tree. + -@root: the root #GNode of the tree to search. -@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, -%G_POST_ORDER, or %G_LEVEL_ORDER. -@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES. -@data: the data to find. -@Returns: the found #GNode, or %NULL if the data is not found. +@root: +@order: +@flags: +@data: +@Returns: -Finds the first child of a #GNode with the given data. + -@node: a #GNode. -@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES. -@data: the data to find. -@Returns: the found child #GNode, or %NULL if the data is not found. +@node: +@flags: +@data: +@Returns: -Gets the position of the first child of a #GNode which contains the given data. + -@node: a #GNode. -@data: the data to find. -@Returns: the index of the child of @node which contains @data, or -1 -if the data is not found. +@node: +@data: +@Returns: -Gets the position of a #GNode with respect to its siblings. -@child must be a child of @node. -The first child is numbered 0, the second 1, and so on. + -@node: a #GNode. -@child: a child of @node. -@Returns: the position of @child with respect to its siblings. +@node: +@child: +@Returns: -Gets the first child of a #GNode. + -@node: a #GNode. -@Returns: the first child of @node, or %NULL if @node is %NULL or has no children. +@node: +@Returns: -Gets the last child of a #GNode. + -@node: a #GNode (must not be %NULL). -@Returns: the last child of @node, or %NULL if @node has no children. +@node: +@Returns: -Gets a child of a #GNode, using the given index. -The first child is at index 0. If the index is too big, %NULL is returned. + -@node: a #GNode. -@n: the index of the desired child. -@Returns: the child of @node at index @n. +@node: +@n: +@Returns: -Gets the first sibling of a #GNode. -This could possibly be the node itself. + -@node: a #GNode. -@Returns: the first sibling of @node. +@node: +@Returns: -Gets the next sibling of a #GNode. + -@node: a #GNode. -@Returns: the next sibling of @node, or %NULL if @node is %NULL. +@node: +@Returns: -Gets the previous sibling of a #GNode. + -@node: a #GNode. -@Returns: the previous sibling of @node, or %NULL if @node is %NULL. +@node: +@Returns: -Gets the last sibling of a #GNode. -This could possibly be the node itself. + -@node: a #GNode. -@Returns: the last sibling of @node. +@node: +@Returns: -Returns %TRUE if a #GNode is a leaf node. + -@node: a #GNode. -@Returns: %TRUE if the #GNode is a leaf node (i.e. it has no children). +@node: +@Returns: -Returns %TRUE if a #GNode is the root of a tree. + -@node: a #GNode. -@Returns: %TRUE if the #GNode is the root of a tree (i.e. it has no parent -or siblings). +@node: +@Returns: -Gets the depth of a #GNode. - - -If @node is %NULL the depth is 0. -The root node has a depth of 1. -For the children of the root node the depth is 2. And so on. + -@node: a #GNode. -@Returns: the depth of the #GNode. +@node: +@Returns: -Gets the number of nodes in a tree. + -@root: a #GNode. -@flags: which types of children are to be counted, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES. -@Returns: the number of nodes in the tree. +@root: +@flags: +@Returns: -Gets the number of children of a #GNode. + -@node: a #GNode. -@Returns: the number of children of @node. +@node: +@Returns: -Returns %TRUE if @node is an ancestor of @descendant. -This is true if node is the parent of @descendant, or if node is the -grandparent of @descendant etc. + -@node: a #GNode. -@descendant: a #GNode. -@Returns: %TRUE if @node is an ancestor of @descendant. +@node: +@descendant: +@Returns: -Gets the maximum height of all branches beneath a #GNode. -This is the maximum distance from the #GNode to all leaf nodes. - - -If @root is %NULL, 0 is returned. If @root has no children, 1 is returned. -If @root has children, 2 is returned. And so on. + -@root: a #GNode. -@Returns: the maximum height of the tree beneath @root. +@root: +@Returns: -Unlinks a #GNode from a tree, resulting in two separate trees. + -@node: the #GNode to unlink, which becomes the root of a new tree. +@node: -Removes the #GNode and its children from the tree, freeing any memory -allocated. + -@root: the root of the tree/subtree to destroy. +@root: diff --git a/glib/gnode.c b/glib/gnode.c index 747545d..142eade 100644 --- a/glib/gnode.c +++ b/glib/gnode.c @@ -43,10 +43,19 @@ void g_node_pop_allocator (void) { /* present for binary compat only #define g_node_free(node) g_slice_free (GNode, node) /* --- functions --- */ +/** + * g_node_new: + * @data: the data of the new node + * + * Creates a new #GNode containing the given data. + * Used to create the first node in a tree. + * + * Returns: a new #GNode + */ GNode* g_node_new (gpointer data) { - GNode *node = g_node_alloc0(); + GNode *node = g_node_alloc0 (); node->data = data; return node; } @@ -64,6 +73,13 @@ g_nodes_free (GNode *node) } } +/** + * g_node_destroy: + * @root: the root of the tree/subtree to destroy + * + * Removes @root and its children from the tree, freeing any memory + * allocated. + */ void g_node_destroy (GNode *root) { @@ -75,6 +91,12 @@ g_node_destroy (GNode *root) g_nodes_free (root); } +/** + * g_node_unlink: + * @node: the #GNode to unlink, which becomes the root of a new tree + * + * Unlinks a #GNode from a tree, resulting in two separate trees. + */ void g_node_unlink (GNode *node) { @@ -132,6 +154,15 @@ g_node_copy_deep (GNode *node, return new_node; } +/** + * g_node_copy: + * @node: a #GNode + * + * Recursively copies a #GNode (but does not deep-copy the data inside the + * nodes, see g_node_copy_deep() if you need that). + * + * Returns: a new #GNode containing the same data pointers + */ GNode* g_node_copy (GNode *node) { @@ -150,6 +181,17 @@ g_node_copy (GNode *node) return new_node; } +/** + * g_node_insert: + * @parent: the #GNode to place @node under + * @position: the position to place @node at, with respect to its siblings + * If position is -1, @node is inserted as the last child of @parent + * @node: the #GNode to insert + * + * Inserts a #GNode beneath the parent at the given position. + * + * Returns: the inserted #GNode + */ GNode* g_node_insert (GNode *parent, gint position, @@ -169,6 +211,17 @@ g_node_insert (GNode *parent, return g_node_append (parent, node); } +/** + * g_node_insert_before: + * @parent: the #GNode to place @node under + * @sibling: the sibling #GNode to place @node before. + * If sibling is %NULL, the node is inserted as the last child of @parent. + * @node: the #GNode to insert + * + * Inserts a #GNode beneath the parent before the given sibling. + * + * Returns: the inserted #GNode + */ GNode* g_node_insert_before (GNode *parent, GNode *sibling, @@ -215,6 +268,17 @@ g_node_insert_before (GNode *parent, return node; } +/** + * g_node_insert_after: + * @parent: the #GNode to place @node under + * @sibling: the sibling #GNode to place @node after. + * If sibling is %NULL, the node is inserted as the first child of @parent. + * @node: the #GNode to insert + * + * Inserts a #GNode beneath the parent after the given sibling. + * + * Returns: the inserted #GNode + */ GNode* g_node_insert_after (GNode *parent, GNode *sibling, @@ -251,6 +315,15 @@ g_node_insert_after (GNode *parent, return node; } +/** + * g_node_prepend: + * @parent: the #GNode to place the new #GNode under + * @node: the #GNode to insert + * + * Inserts a #GNode as the first child of the given parent. + * + * Returns: the inserted #GNode + */ GNode* g_node_prepend (GNode *parent, GNode *node) @@ -260,6 +333,14 @@ g_node_prepend (GNode *parent, return g_node_insert_before (parent, parent->children, node); } +/** + * g_node_get_root: + * @node: a #GNode + * + * Gets the root of a tree. + * + * Returns: the root of the tree + */ GNode* g_node_get_root (GNode *node) { @@ -271,6 +352,17 @@ g_node_get_root (GNode *node) return node; } +/** + * g_node_is_ancestor: + * @node: a #GNode + * @descendant: a #GNode + * + * Returns %TRUE if @node is an ancestor of @descendant. + * This is true if node is the parent of @descendant, + * or if node is the grandparent of @descendant etc. + * + * Returns: %TRUE if @node is an ancestor of @descendant + */ gboolean g_node_is_ancestor (GNode *node, GNode *descendant) @@ -289,13 +381,21 @@ g_node_is_ancestor (GNode *node, return FALSE; } -/* returns 1 for root, 2 for first level children, - * 3 for children's children... +/** + * g_node_depth: + * @node: a #GNode + * + * Gets the depth of a #GNode. + * + * If @node is %NULL the depth is 0. The root node has a depth of 1. + * For the children of the root node the depth is 2. And so on. + * + * Returns: the depth of the #GNode */ guint g_node_depth (GNode *node) { - register guint depth = 0; + guint depth = 0; while (node) { @@ -306,6 +406,13 @@ g_node_depth (GNode *node) return depth; } +/** + * g_node_reverse_children: + * @node: a #GNode. + * + * Reverses the order of the children of a #GNode. + * (It doesn't change the order of the grandchildren.) + */ void g_node_reverse_children (GNode *node) { @@ -326,11 +433,23 @@ g_node_reverse_children (GNode *node) node->children = last; } +/** + * g_node_max_height: + * @root: a #GNode + * + * Gets the maximum height of all branches beneath a #GNode. + * This is the maximum distance from the #GNode to all leaf nodes. + * + * If @root is %NULL, 0 is returned. If @root has no children, + * 1 is returned. If @root has children, 2 is returned. And so on. + * + * Returns: the maximum height of the tree beneath @root + */ guint g_node_max_height (GNode *root) { - register GNode *child; - register guint max_height = 0; + GNode *child; + guint max_height = 0; if (!root) return 0; @@ -338,7 +457,7 @@ g_node_max_height (GNode *root) child = root->children; while (child) { - register guint tmp_height; + guint tmp_height; tmp_height = g_node_max_height (child); if (tmp_height > max_height) @@ -366,7 +485,7 @@ g_node_traverse_pre_order (GNode *node, child = node->children; while (child) { - register GNode *current; + GNode *current; current = child; child = current->next; @@ -403,7 +522,7 @@ g_node_depth_traverse_pre_order (GNode *node, child = node->children; while (child) { - register GNode *current; + GNode *current; current = child; child = current->next; @@ -431,7 +550,7 @@ g_node_traverse_post_order (GNode *node, child = node->children; while (child) { - register GNode *current; + GNode *current; current = child; child = current->next; @@ -468,7 +587,7 @@ g_node_depth_traverse_post_order (GNode *node, child = node->children; while (child) { - register GNode *current; + GNode *current; current = child; child = current->next; @@ -498,7 +617,7 @@ g_node_traverse_in_order (GNode *node, if (node->children) { GNode *child; - register GNode *current; + GNode *current; child = node->children; current = child; @@ -539,7 +658,7 @@ g_node_depth_traverse_in_order (GNode *node, if (depth) { GNode *child; - register GNode *current; + GNode *current; child = node->children; current = child; @@ -575,9 +694,9 @@ static gboolean g_node_traverse_level (GNode *node, GTraverseFlags flags, guint level, - GNodeTraverseFunc func, - gpointer data, - gboolean *more_levels) + GNodeTraverseFunc func, + gpointer data, + gboolean *more_levels) { if (level == 0) { @@ -608,11 +727,11 @@ g_node_traverse_level (GNode *node, } static gboolean -g_node_depth_traverse_level (GNode *node, - GTraverseFlags flags, - guint depth, - GNodeTraverseFunc func, - gpointer data) +g_node_depth_traverse_level (GNode *node, + GTraverseFlags flags, + guint depth, + GNodeTraverseFunc func, + gpointer data) { guint level; gboolean more_levels; @@ -630,6 +749,24 @@ g_node_depth_traverse_level (GNode *node, return FALSE; } +/** + * g_node_traverse: + * @root: the root #GNode of the tree to traverse + * @order: the order in which nodes are visited - %G_IN_ORDER, + * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. + * @flags: which types of children are to be visited, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @max_depth: the maximum depth of the traversal. Nodes below this + * depth will not be visited. If max_depth is -1 all nodes in + * the tree are visited. If depth is 1, only the root is visited. + * If depth is 2, the root and its children are visited. And so on. + * @func: the function to call for each visited #GNode + * @data: user data to pass to the function + * + * Traverses a tree starting at the given root #GNode. + * It calls the given function for each node visited. + * The traversal can be halted at any point by returning %TRUE from @func. + */ void g_node_traverse (GNode *root, GTraverseType order, @@ -671,10 +808,10 @@ g_node_traverse (GNode *root, } static gboolean -g_node_find_func (GNode *node, - gpointer data) +g_node_find_func (GNode *node, + gpointer data) { - register gpointer *d = data; + gpointer *d = data; if (*d != node->data) return FALSE; @@ -684,11 +821,24 @@ g_node_find_func (GNode *node, return TRUE; } +/** + * g_node_find: + * @root: the root #GNode of the tree to search + * @order: the order in which nodes are visited - %G_IN_ORDER, + * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER + * @flags: which types of children are to be searched, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @data: the data to find + * + * Finds a #GNode in a tree. + * + * Returns: the found #GNode, or %NULL if the data is not found + */ GNode* -g_node_find (GNode *root, - GTraverseType order, - GTraverseFlags flags, - gpointer data) +g_node_find (GNode *root, + GTraverseType order, + GTraverseFlags flags, + gpointer data) { gpointer d[2]; @@ -727,9 +877,19 @@ g_node_count_func (GNode *node, (*n)++; } +/** + * g_node_n_nodes: + * @root: a #GNode + * @flags: which types of children are to be counted, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * + * Gets the number of nodes in a tree. + * + * Returns: the number of nodes in the tree + */ guint -g_node_n_nodes (GNode *root, - GTraverseFlags flags) +g_node_n_nodes (GNode *root, + GTraverseFlags flags) { guint n = 0; @@ -741,6 +901,14 @@ g_node_n_nodes (GNode *root, return n; } +/** + * g_node_last_child: + * @node: a #GNode (must not be %NULL) + * + * Gets the last child of a #GNode. + * + * Returns: the last child of @node, or %NULL if @node has no children + */ GNode* g_node_last_child (GNode *node) { @@ -754,6 +922,17 @@ g_node_last_child (GNode *node) return node; } +/** + * g_node_nth_child: + * @node: a #GNode + * @n: the index of the desired child + * + * Gets a child of a #GNode, using the given index. + * The first child is at index 0. If the index is + * too big, %NULL is returned. + * + * Returns: the child of @node at index @n + */ GNode* g_node_nth_child (GNode *node, guint n) @@ -768,6 +947,14 @@ g_node_nth_child (GNode *node, return node; } +/** + * g_node_n_children: + * @node: a #GNode + * + * Gets the number of children of a #GNode. + * + * Returns: the number of children of @node + */ guint g_node_n_children (GNode *node) { @@ -785,10 +972,21 @@ g_node_n_children (GNode *node) return n; } +/** + * g_node_find_child: + * @node: a #GNode + * @flags: which types of children are to be searched, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @data: the data to find + * + * Finds the first child of a #GNode with the given data. + * + * Returns: the found child #GNode, or %NULL if the data is not found + */ GNode* -g_node_find_child (GNode *node, - GTraverseFlags flags, - gpointer data) +g_node_find_child (GNode *node, + GTraverseFlags flags, + gpointer data) { g_return_val_if_fail (node != NULL, NULL); g_return_val_if_fail (flags <= G_TRAVERSE_MASK, NULL); @@ -815,11 +1013,22 @@ g_node_find_child (GNode *node, return NULL; } +/** + * g_node_child_position: + * @node: a #GNode + * @child: a child of @node + * + * Gets the position of a #GNode with respect to its siblings. + * @child must be a child of @node. The first child is numbered 0, + * the second 1, and so on. + * + * Returns: the position of @child with respect to its siblings + */ gint g_node_child_position (GNode *node, GNode *child) { - register guint n = 0; + guint n = 0; g_return_val_if_fail (node != NULL, -1); g_return_val_if_fail (child != NULL, -1); @@ -837,11 +1046,22 @@ g_node_child_position (GNode *node, return -1; } +/** + * g_node_child_index: + * @node: a #GNode + * @data: the data to find + * + * Gets the position of the first child of a #GNode + * which contains the given data. + * + * Returns: the index of the child of @node which contains + * @data, or -1 if the data is not found + */ gint -g_node_child_index (GNode *node, - gpointer data) +g_node_child_index (GNode *node, + gpointer data) { - register guint n = 0; + guint n = 0; g_return_val_if_fail (node != NULL, -1); @@ -857,6 +1077,15 @@ g_node_child_index (GNode *node, return -1; } +/** + * g_node_first_sibling: + * @node: a #GNode + * + * Gets the first sibling of a #GNode. + * This could possibly be the node itself. + * + * Returns: the first sibling of @node + */ GNode* g_node_first_sibling (GNode *node) { @@ -871,6 +1100,15 @@ g_node_first_sibling (GNode *node) return node; } +/** + * g_node_last_sibling: + * @node: a #GNode + * + * Gets the last sibling of a #GNode. + * This could possibly be the node itself. + * + * Returns: the last sibling of @node + */ GNode* g_node_last_sibling (GNode *node) { @@ -882,11 +1120,22 @@ g_node_last_sibling (GNode *node) return node; } +/** + * g_node_children_foreach: + * @node: a #GNode + * @flags: which types of children are to be visited, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @func: the function to call for each visited node + * @data: user data to pass to the function + * + * Calls a function for each of the children of a #GNode. + * Note that it doesn't descend beneath the child nodes. + */ void -g_node_children_foreach (GNode *node, - GTraverseFlags flags, - GNodeForeachFunc func, - gpointer data) +g_node_children_foreach (GNode *node, + GTraverseFlags flags, + GNodeForeachFunc func, + gpointer data) { g_return_if_fail (node != NULL); g_return_if_fail (flags <= G_TRAVERSE_MASK); @@ -895,7 +1144,7 @@ g_node_children_foreach (GNode *node, node = node->children; while (node) { - register GNode *current; + GNode *current; current = node; node = current->next; diff --git a/glib/gnode.h b/glib/gnode.h index a22c8fb..e5b7ebc 100644 --- a/glib/gnode.h +++ b/glib/gnode.h @@ -57,6 +57,19 @@ typedef gboolean (*GNodeTraverseFunc) (GNode *node, gpointer data); typedef void (*GNodeForeachFunc) (GNode *node, gpointer data); + +/** + * GCopyFunc: + * @src: A pointer to the data which should be copied + * @data: Additional data + * + * A function of this signature is used to copy the node data + * when doing a deep-copy of a tree. + * + * Returns: A pointer to the copy + * + * Since: 2.4 + */ typedef gpointer (*GCopyFunc) (gconstpointer src, gpointer data); @@ -71,9 +84,28 @@ struct _GNode GNode *children; }; +/** + * G_NODE_IS_ROOT: + * @node: a #GNode + * + * Returns %TRUE if a #GNode is the root of a tree. + * + * Returns: %TRUE if the #GNode is the root of a tree + * (i.e. it has no parent or siblings) + */ #define G_NODE_IS_ROOT(node) (((GNode*) (node))->parent == NULL && \ ((GNode*) (node))->prev == NULL && \ ((GNode*) (node))->next == NULL) + +/** + * G_NODE_IS_LEAF: + * @node: a #GNode + * + * Returns %TRUE if a #GNode is a leaf node. + * + * Returns: %TRUE if the #GNode is a leaf node + * (i.e. it has no children) + */ #define G_NODE_IS_LEAF(node) (((GNode*) (node))->children == NULL) GNode* g_node_new (gpointer data); @@ -106,14 +138,66 @@ GNode* g_node_find (GNode *root, gpointer data); /* convenience macros */ +/** + * g_node_append: + * @parent: the #GNode to place the new #GNode under + * @node: the #GNode to insert + * + * Inserts a #GNode as the last child of the given parent. + * + * Returns: the inserted #GNode + */ #define g_node_append(parent, node) \ g_node_insert_before ((parent), NULL, (node)) + +/** + * g_node_insert_data: + * @parent: the #GNode to place the new #GNode under + * @position: the position to place the new #GNode at. If position is -1, + * the new #GNode is inserted as the last child of @parent + * @data: the data for the new #GNode + * + * Inserts a new #GNode at the given position. + * + * Returns: the new #GNode + */ #define g_node_insert_data(parent, position, data) \ g_node_insert ((parent), (position), g_node_new (data)) + +/** + * g_node_insert_data_before: + * @parent: the #GNode to place the new #GNode under + * @sibling: the sibling #GNode to place the new #GNode before + * @data: the data for the new #GNode + * + * Inserts a new #GNode before the given sibling. + * + * Returns: the new #GNode + */ #define g_node_insert_data_before(parent, sibling, data) \ g_node_insert_before ((parent), (sibling), g_node_new (data)) + +/** + * g_node_prepend_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode + * + * Inserts a new #GNode as the first child of the given parent. + * + * Returns: the new #GNode + */ #define g_node_prepend_data(parent, data) \ g_node_prepend ((parent), g_node_new (data)) + +/** + * g_node_append_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode + * + * Inserts a new #GNode as the last child of the given parent. + * + * Returns: the new #GNode + */ #define g_node_append_data(parent, data) \ g_node_insert_before ((parent), NULL, g_node_new (data)) @@ -156,10 +240,37 @@ gint g_node_child_index (GNode *node, GNode* g_node_first_sibling (GNode *node); GNode* g_node_last_sibling (GNode *node); +/** + * g_node_prev_sibling: + * @node: a #GNode + * + * Gets the previous sibling of a #GNode. + * + * Returns: the previous sibling of @node, or %NULL if @node is %NULL + */ #define g_node_prev_sibling(node) ((node) ? \ ((GNode*) (node))->prev : NULL) + +/** + * g_node_next_sibling: + * @node: a #GNode + * + * Gets the next sibling of a #GNode. + * + * Returns: the next sibling of @node, or %NULL if @node is %NULL + */ #define g_node_next_sibling(node) ((node) ? \ ((GNode*) (node))->next : NULL) + +/** + * g_node_first_child: + * @node: a #GNode + * + * Gets the first child of a #GNode. + * + * Returns: the first child of @node, or %NULL if @node is %NULL + * or has no children + */ #define g_node_first_child(node) ((node) ? \ ((GNode*) (node))->children : NULL) -- 2.7.4