luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Move docs inline. (#316260, Philippe Blain)

Browse Source 
2008-01-27  Matthias Clasen  <mclasen@redhat.com>

        * glib/gnode.[hc]: Move docs inline.  (#316260, Philippe Blain)



svn path=/trunk/; revision=6392
This commit is contained in:
Matthias Clasen 2008-01-28 04:50:12 +00:00 committed by Matthias Clasen
parent 137fdf9089
commit cf9b04e7df
5 changed files with 546 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ChangeLog
View File

@ -1,3 +1,7 @@
2008-01-27 Matthias Clasen <mclasen@redhat.com>
* glib/gnode.[hc]: Move docs inline. (#316260, Philippe Blain)
2008-01-27 Matthias Clasen <mclasen@redhat.com>
* glib/gutf8.c (g_utf8_strreverse): Document limitations

4
docs/reference/ChangeLog
View File

@ -1,3 +1,7 @@
2008-01-27 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/trees-nary.sgml: Move docs inline
2008-01-27 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/macros_misc.sgml: Document G_GNUC_(PRETTY)_FUNCTION

314
docs/reference/glib/tmpl/trees-nary.sgml
View File

@ -71,34 +71,30 @@ fields
<!-- ##### FUNCTION g_node_new ##### -->
<para>
Creates a new #GNode containing the given data.
Used to create the first node in a tree.
</para>
@data: the data of the new node.
@Returns: a new #GNode.
@data:
@Returns:
<!-- ##### FUNCTION g_node_copy ##### -->
<para>
Recursively copies a #GNode (but does not deep-copy the data inside the nodes,
see g_node_copy_deep() if you need that).
</para>
@node: a #GNode.
@Returns: a new #GNode containing the same data pointers.
@node:
@Returns:
<!-- ##### USER_FUNCTION GCopyFunc ##### -->
<para>
A function of this signature is used to copy the node data when doing a deep-copy
of a tree.
</para>
@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:
<!-- ##### FUNCTION g_node_copy_deep ##### -->
@ -114,130 +110,118 @@ of a tree.
<!-- ##### FUNCTION g_node_insert ##### -->
<para>
Inserts a #GNode beneath the parent at the given position.
</para>
@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:
<!-- ##### FUNCTION g_node_insert_before ##### -->
<para>
Inserts a #GNode beneath the parent before the given sibling.
</para>
@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:
<!-- ##### FUNCTION g_node_insert_after ##### -->
<para>
Inserts a #GNode beneath the parent after the given sibling.
</para>
@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:
<!-- ##### MACRO g_node_append ##### -->
<para>
Inserts a #GNode as the last child of the given parent.
</para>
@parent: the #GNode to place the new #GNode under.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
@parent:
@node:
@Returns:
<!-- ##### FUNCTION g_node_prepend ##### -->
<para>
Inserts a #GNode as the first child of the given parent.
</para>
@parent: the #GNode to place the new #GNode under.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
@parent:
@node:
@Returns:
<!-- ##### MACRO g_node_insert_data ##### -->
<para>
Inserts a new #GNode at the given position.
</para>
@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:
<!-- ##### MACRO g_node_insert_data_before ##### -->
<para>
Inserts a new #GNode before the given sibling.
</para>
@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:
<!-- ##### MACRO g_node_append_data ##### -->
<para>
Inserts a new #GNode as the last child of the given parent.
</para>
@parent: the #GNode to place the new #GNode under.
@data: the data for the new #GNode.
@Returns: the new #GNode.
@parent:
@data:
@Returns:
<!-- ##### MACRO g_node_prepend_data ##### -->
<para>
Inserts a new #GNode as the first child of the given parent.
</para>
@parent: the #GNode to place the new #GNode under.
@data: the data for the new #GNode.
@Returns: the new #GNode.
@parent:
@data:
@Returns:
<!-- ##### FUNCTION g_node_reverse_children ##### -->
<para>
Reverses the order of the children of a #GNode.
(It doesn't change the order of the grandchildren.)
</para>
@node: a #GNode.
@node:
<!-- ##### FUNCTION g_node_traverse ##### -->
<para>
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.
</para>
@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:
<!-- ##### ENUM GTraverseFlags ##### -->
@ -270,15 +254,13 @@ If the function returns %TRUE, then the traversal is stopped.
<!-- ##### FUNCTION g_node_children_foreach ##### -->
<para>
Calls a function for each of the children of a #GNode.
Note that it doesn't descend beneath the child nodes.
</para>
@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:
<!-- ##### USER_FUNCTION GNodeForeachFunc ##### -->
@ -294,223 +276,199 @@ passed to g_node_children_foreach().
<!-- ##### FUNCTION g_node_get_root ##### -->
<para>
Gets the root of a tree.
</para>
@node: a #GNode.
@Returns: the root of the tree.
@node:
@Returns:
<!-- ##### FUNCTION g_node_find ##### -->
<para>
Finds a #GNode in a tree.
</para>
@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:
<!-- ##### FUNCTION g_node_find_child ##### -->
<para>
Finds the first child of a #GNode with the given data.
</para>
@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:
<!-- ##### FUNCTION g_node_child_index ##### -->
<para>
Gets the position of the first child of a #GNode which contains the given data.
</para>
@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:
<!-- ##### FUNCTION g_node_child_position ##### -->
<para>
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.
</para>
@node: a #GNode.
@child: a child of @node.
@Returns: the position of @child with respect to its siblings.
@node:
@child:
@Returns:
<!-- ##### MACRO g_node_first_child ##### -->
<para>
Gets the first child of a #GNode.
</para>
@node: a #GNode.
@Returns: the first child of @node, or %NULL if @node is %NULL or has no children.
@node:
@Returns:
<!-- ##### FUNCTION g_node_last_child ##### -->
<para>
Gets the last child of a #GNode.
</para>
@node: a #GNode (must not be %NULL).
@Returns: the last child of @node, or %NULL if @node has no children.
@node:
@Returns:
<!-- ##### FUNCTION g_node_nth_child ##### -->
<para>
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.
</para>
@node: a #GNode.
@n: the index of the desired child.
@Returns: the child of @node at index @n.
@node:
@n:
@Returns:
<!-- ##### FUNCTION g_node_first_sibling ##### -->
<para>
Gets the first sibling of a #GNode.
This could possibly be the node itself.
</para>
@node: a #GNode.
@Returns: the first sibling of @node.
@node:
@Returns:
<!-- ##### MACRO g_node_next_sibling ##### -->
<para>
Gets the next sibling of a #GNode.
</para>
@node: a #GNode.
@Returns: the next sibling of @node, or %NULL if @node is %NULL.
@node:
@Returns:
<!-- ##### MACRO g_node_prev_sibling ##### -->
<para>
Gets the previous sibling of a #GNode.
</para>
@node: a #GNode.
@Returns: the previous sibling of @node, or %NULL if @node is %NULL.
@node:
@Returns:
<!-- ##### FUNCTION g_node_last_sibling ##### -->
<para>
Gets the last sibling of a #GNode.
This could possibly be the node itself.
</para>
@node: a #GNode.
@Returns: the last sibling of @node.
@node:
@Returns:
<!-- ##### MACRO G_NODE_IS_LEAF ##### -->
<para>
Returns %TRUE if a #GNode is a leaf node.
</para>
@node: a #GNode.
@Returns: %TRUE if the #GNode is a leaf node (i.e. it has no children).
@node:
@Returns:
<!-- ##### MACRO G_NODE_IS_ROOT ##### -->
<para>
Returns %TRUE if a #GNode is the root of a tree.
</para>
@node: a #GNode.
@Returns: %TRUE if the #GNode is the root of a tree (i.e. it has no parent
or siblings).
@node:
@Returns:
<!-- ##### FUNCTION g_node_depth ##### -->
<para>
Gets the depth of a #GNode.
</para>
<para>
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.
</para>
@node: a #GNode.
@Returns: the depth of the #GNode.
@node:
@Returns:
<!-- ##### FUNCTION g_node_n_nodes ##### -->
<para>
Gets the number of nodes in a tree.
</para>
@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:
<!-- ##### FUNCTION g_node_n_children ##### -->
<para>
Gets the number of children of a #GNode.
</para>
@node: a #GNode.
@Returns: the number of children of @node.
@node:
@Returns:
<!-- ##### FUNCTION g_node_is_ancestor ##### -->
<para>
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.
</para>
@node: a #GNode.
@descendant: a #GNode.
@Returns: %TRUE if @node is an ancestor of @descendant.
@node:
@descendant:
@Returns:
<!-- ##### FUNCTION g_node_max_height ##### -->
<para>
Gets the maximum height of all branches beneath a #GNode.
This is the maximum distance from the #GNode to all leaf nodes.
</para>
<para>
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.
</para>
@root: a #GNode.
@Returns: the maximum height of the tree beneath @root.
@root:
@Returns:
<!-- ##### FUNCTION g_node_unlink ##### -->
<para>
Unlinks a #GNode from a tree, resulting in two separate trees.
</para>
@node: the #GNode to unlink, which becomes the root of a new tree.
@node:
<!-- ##### FUNCTION g_node_destroy ##### -->
<para>
Removes the #GNode and its children from the tree, freeing any memory
allocated.
</para>
@root: the root of the tree/subtree to destroy.
@root:
<!-- ##### FUNCTION g_node_push_allocator ##### -->

333
glib/gnode.c
View File

@ -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;

111
glib/gnode.h
View File

@ -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)