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
of this function. (#487909, Peter Moulder)
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
as deprecated.
<!-- ##### 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 ##### -->
<!-- ##### 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 ##### -->
<!-- ##### 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 ##### -->
<!-- ##### 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 ##### -->
#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;
}
}
}
+/**
+ * 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)
{
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)
{
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)
{
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,
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,
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,
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)
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)
{
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)
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)
{
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)
{
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;
child = root->children;
while (child)
{
- register guint tmp_height;
+ guint tmp_height;
tmp_height = g_node_max_height (child);
if (tmp_height > max_height)
child = node->children;
while (child)
{
- register GNode *current;
+ GNode *current;
current = child;
child = current->next;
child = node->children;
while (child)
{
- register GNode *current;
+ GNode *current;
current = child;
child = current->next;
child = node->children;
while (child)
{
- register GNode *current;
+ GNode *current;
current = child;
child = current->next;
child = node->children;
while (child)
{
- register GNode *current;
+ GNode *current;
current = child;
child = current->next;
if (node->children)
{
GNode *child;
- register GNode *current;
+ GNode *current;
child = node->children;
current = child;
if (depth)
{
GNode *child;
- register GNode *current;
+ GNode *current;
child = node->children;
current = child;
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)
{
}
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;
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,
}
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;
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];
(*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;
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)
{
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)
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)
{
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);
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);
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);
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)
{
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)
{
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);
node = node->children;
while (node)
{
- register GNode *current;
+ GNode *current;
current = node;
node = current->next;
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);
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);
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))
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)
projects / platform / upstream / glib.git / commitdiff