Description
The GNode struct and its associated functions provide a N-ary tree
data structure, where nodes in the tree can contain arbitrary data.
To create a new tree use g_node_new().
To insert a node into a tree use g_node_insert(),
g_node_insert_before(), g_node_append() and g_node_prepend().
To create a new node and insert it into a tree use
g_node_insert_data(), g_node_insert_data_after(),
g_node_insert_data_before(), g_node_append_data()
and g_node_prepend_data().
To reverse the children of a node use g_node_reverse_children().
To find a node use g_node_get_root(), g_node_find(),
g_node_find_child(), g_node_child_index(), g_node_child_position(),
g_node_first_child(), g_node_last_child(), g_node_nth_child(),
g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling()
or g_node_last_sibling().
To get information about a node or tree use G_NODE_IS_LEAF(),
G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(),
g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
To traverse a tree, calling a function for each node visited in the
traversal, use g_node_traverse() or g_node_children_foreach().
To remove a node or subtree from a tree use g_node_unlink() or
g_node_destroy().
Functions
g_node_new ()
GNode *
g_node_new (gpointer data);
Creates a new GNode containing the given data.
Used to create the first node in a tree.
g_node_copy ()
GNode *
g_node_copy (GNode *node);
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
GCopyFunc ()
gpointer
(*GCopyFunc) (gconstpointer src,
gpointer 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.
[not nullable]
Since: 2.4
g_node_copy_deep ()
GNode *
g_node_copy_deep (GNode *node,
GCopyFunc copy_func,
gpointer data);
Recursively copies a GNode and its data.
Returns
a new GNode containing copies of the data in node
.
Since: 2.4
g_node_insert ()
GNode *
g_node_insert (GNode *parent,
gint position,
GNode *node);
Inserts a GNode beneath the parent at the given position.
Returns
the inserted GNode
g_node_insert_before ()
GNode *
g_node_insert_before (GNode *parent,
GNode *sibling,
GNode *node);
Inserts a GNode beneath the parent before the given sibling.
Returns
the inserted GNode
g_node_insert_after ()
GNode *
g_node_insert_after (GNode *parent,
GNode *sibling,
GNode *node);
Inserts a GNode beneath the parent after the given sibling.
Returns
the inserted GNode
g_node_append()
#define g_node_append(parent, node)
Inserts a GNode as the last child of the given parent.
Returns
the inserted GNode
g_node_prepend ()
GNode *
g_node_prepend (GNode *parent,
GNode *node);
Inserts a GNode as the first child of the given parent.
Returns
the inserted GNode
g_node_insert_data()
#define g_node_insert_data(parent, position, data)
Inserts a new GNode at the given position.
g_node_insert_data_after()
#define g_node_insert_data_after(parent, sibling, data)
Inserts a new GNode after the given sibling.
g_node_insert_data_before()
#define g_node_insert_data_before(parent, sibling, data)
Inserts a new GNode before the given sibling.
g_node_append_data()
#define g_node_append_data(parent, data)
Inserts a new GNode as the last child of the given parent.
g_node_prepend_data()
#define g_node_prepend_data(parent, data)
Inserts a new GNode as the first child of the given parent.
g_node_reverse_children ()
void
g_node_reverse_children (GNode *node);
Reverses the order of the children of a GNode.
(It doesn't change the order of the grandchildren.)
g_node_traverse ()
void
g_node_traverse (GNode *root,
GTraverseType order,
GTraverseFlags flags,
gint max_depth,
GNodeTraverseFunc func,
gpointer data);
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
.
func
must not do anything that would modify the structure of the tree.
GNodeTraverseFunc ()
gboolean
(*GNodeTraverseFunc) (GNode *node,
gpointer data);
Specifies the type of function passed to g_node_traverse(). The
function is called with each of the nodes visited, together with the
user data passed to g_node_traverse(). If the function returns
TRUE, then the traversal is stopped.
Returns
TRUE to stop the traversal.
g_node_children_foreach ()
void
g_node_children_foreach (GNode *node,
GTraverseFlags flags,
GNodeForeachFunc func,
gpointer data);
Calls a function for each of the children of a GNode. Note that it
doesn't descend beneath the child nodes. func
must not do anything
that would modify the structure of the tree.
g_node_get_root ()
GNode *
g_node_get_root (GNode *node);
Gets the root of a tree.
Returns
the root of the tree
g_node_child_index ()
gint
g_node_child_index (GNode *node,
gpointer data);
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
g_node_child_position ()
gint
g_node_child_position (GNode *node,
GNode *child);
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
g_node_first_child()
#define g_node_first_child(node)
Gets the first child of a GNode.
Returns
the first child of node
, or NULL if node
is NULL
or has no children
g_node_last_child ()
GNode *
g_node_last_child (GNode *node);
Gets the last child of a GNode.
Returns
the last child of node
, or NULL if node
has no children
g_node_nth_child ()
GNode *
g_node_nth_child (GNode *node,
guint n);
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
g_node_first_sibling ()
GNode *
g_node_first_sibling (GNode *node);
Gets the first sibling of a GNode.
This could possibly be the node itself.
Returns
the first sibling of node
g_node_next_sibling()
#define g_node_next_sibling(node)
Gets the next sibling of a GNode.
Returns
the next sibling of node
, or NULL if node
is the last node
or NULL
g_node_prev_sibling()
#define g_node_prev_sibling(node)
Gets the previous sibling of a GNode.
Returns
the previous sibling of node
, or NULL if node
is the first
node or NULL
g_node_last_sibling ()
GNode *
g_node_last_sibling (GNode *node);
Gets the last sibling of a GNode.
This could possibly be the node itself.
Returns
the last sibling of node
G_NODE_IS_LEAF()
#define G_NODE_IS_LEAF(node) (((GNode*) (node))->children == NULL)
Returns TRUE if a GNode is a leaf node.
Returns
TRUE if the GNode is a leaf node
(i.e. it has no children)
G_NODE_IS_ROOT()
#define G_NODE_IS_ROOT(node)
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)
g_node_depth ()
guint
g_node_depth (GNode *node);
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
g_node_n_nodes ()
guint
g_node_n_nodes (GNode *root,
GTraverseFlags flags);
Gets the number of nodes in a tree.
Returns
the number of nodes in the tree
g_node_n_children ()
guint
g_node_n_children (GNode *node);
Gets the number of children of a GNode.
Returns
the number of children of node
g_node_is_ancestor ()
gboolean
g_node_is_ancestor (GNode *node,
GNode *descendant);
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
g_node_max_height ()
guint
g_node_max_height (GNode *root);
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
g_node_unlink ()
void
g_node_unlink (GNode *node);
Unlinks a GNode from a tree, resulting in two separate trees.
g_node_destroy ()
void
g_node_destroy (GNode *root);
Removes root
and its children from the tree, freeing any memory
allocated.