<refentry id="glib-N-ary-Trees">
<refmeta>
<refentrytitle role="top_of_page" id="glib-N-ary-Trees.top_of_page">N-ary Trees</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>N-ary Trees</refname>
<refpurpose>trees of data with any number of branches</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-N-ary-Trees.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <link linkend="GNode">GNode</link>;
<link linkend="GNode">GNode</link>*              <link linkend="g-node-new">g_node_new</link>                          (<link linkend="gpointer">gpointer</link> data);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-copy">g_node_copy</link>                         (<link linkend="GNode">GNode</link> *node);
<link linkend="gpointer">gpointer</link>            (<link linkend="GCopyFunc">*GCopyFunc</link>)                        (<link linkend="gconstpointer">gconstpointer</link> src,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-copy-deep">g_node_copy_deep</link>                    (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GCopyFunc">GCopyFunc</link> copy_func,
                                                         <link linkend="gpointer">gpointer</link> data);

<link linkend="GNode">GNode</link>*              <link linkend="g-node-insert">g_node_insert</link>                       (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="gint">gint</link> position,
                                                         <link linkend="GNode">GNode</link> *node);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-insert-before">g_node_insert_before</link>                (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="GNode">GNode</link> *sibling,
                                                         <link linkend="GNode">GNode</link> *node);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-insert-after">g_node_insert_after</link>                 (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="GNode">GNode</link> *sibling,
                                                         <link linkend="GNode">GNode</link> *node);
#define             <link linkend="g-node-append">g_node_append</link>                       (parent, node)
<link linkend="GNode">GNode</link>*              <link linkend="g-node-prepend">g_node_prepend</link>                      (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="GNode">GNode</link> *node);

#define             <link linkend="g-node-insert-data">g_node_insert_data</link>                  (parent, position, data)
#define             <link linkend="g-node-insert-data-before">g_node_insert_data_before</link>           (parent, sibling, data)
#define             <link linkend="g-node-append-data">g_node_append_data</link>                  (parent, data)
#define             <link linkend="g-node-prepend-data">g_node_prepend_data</link>                 (parent, data)

<link linkend="void">void</link>                <link linkend="g-node-reverse-children">g_node_reverse_children</link>             (<link linkend="GNode">GNode</link> *node);
<link linkend="void">void</link>                <link linkend="g-node-traverse">g_node_traverse</link>                     (<link linkend="GNode">GNode</link> *root,
                                                         <link linkend="GTraverseType">GTraverseType</link> order,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="gint">gint</link> max_depth,
                                                         <link linkend="GNodeTraverseFunc">GNodeTraverseFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> data);
enum                <link linkend="GTraverseFlags">GTraverseFlags</link>;
<link linkend="gboolean">gboolean</link>            (<link linkend="GNodeTraverseFunc">*GNodeTraverseFunc</link>)                (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link>                <link linkend="g-node-children-foreach">g_node_children_foreach</link>             (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="GNodeForeachFunc">GNodeForeachFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link>                (<link linkend="GNodeForeachFunc">*GNodeForeachFunc</link>)                 (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="gpointer">gpointer</link> data);

<link linkend="GNode">GNode</link>*              <link linkend="g-node-get-root">g_node_get_root</link>                     (<link linkend="GNode">GNode</link> *node);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-find">g_node_find</link>                         (<link linkend="GNode">GNode</link> *root,
                                                         <link linkend="GTraverseType">GTraverseType</link> order,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-find-child">g_node_find_child</link>                   (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="gint">gint</link>                <link linkend="g-node-child-index">g_node_child_index</link>                  (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="gint">gint</link>                <link linkend="g-node-child-position">g_node_child_position</link>               (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GNode">GNode</link> *child);
#define             <link linkend="g-node-first-child">g_node_first_child</link>                  (node)
<link linkend="GNode">GNode</link>*              <link linkend="g-node-last-child">g_node_last_child</link>                   (<link linkend="GNode">GNode</link> *node);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-nth-child">g_node_nth_child</link>                    (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="guint">guint</link> n);
<link linkend="GNode">GNode</link>*              <link linkend="g-node-first-sibling">g_node_first_sibling</link>                (<link linkend="GNode">GNode</link> *node);
#define             <link linkend="g-node-next-sibling">g_node_next_sibling</link>                 (node)
#define             <link linkend="g-node-prev-sibling">g_node_prev_sibling</link>                 (node)
<link linkend="GNode">GNode</link>*              <link linkend="g-node-last-sibling">g_node_last_sibling</link>                 (<link linkend="GNode">GNode</link> *node);

#define             <link linkend="G-NODE-IS-LEAF--CAPS">G_NODE_IS_LEAF</link>                      (node)
#define             <link linkend="G-NODE-IS-ROOT--CAPS">G_NODE_IS_ROOT</link>                      (node)
<link linkend="guint">guint</link>               <link linkend="g-node-depth">g_node_depth</link>                        (<link linkend="GNode">GNode</link> *node);
<link linkend="guint">guint</link>               <link linkend="g-node-n-nodes">g_node_n_nodes</link>                      (<link linkend="GNode">GNode</link> *root,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags);
<link linkend="guint">guint</link>               <link linkend="g-node-n-children">g_node_n_children</link>                   (<link linkend="GNode">GNode</link> *node);
<link linkend="gboolean">gboolean</link>            <link linkend="g-node-is-ancestor">g_node_is_ancestor</link>                  (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GNode">GNode</link> *descendant);
<link linkend="guint">guint</link>               <link linkend="g-node-max-height">g_node_max_height</link>                   (<link linkend="GNode">GNode</link> *root);

<link linkend="void">void</link>                <link linkend="g-node-unlink">g_node_unlink</link>                       (<link linkend="GNode">GNode</link> *node);
<link linkend="void">void</link>                <link linkend="g-node-destroy">g_node_destroy</link>                      (<link linkend="GNode">GNode</link> *root);

<link linkend="void">void</link>                <link linkend="g-node-push-allocator">g_node_push_allocator</link>               (<link linkend="gpointer">gpointer</link> dummy);
<link linkend="void">void</link>                <link linkend="g-node-pop-allocator">g_node_pop_allocator</link>                (void);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-N-ary-Trees.description" role="desc">
<title role="desc.title">Description</title>
<para>
The <link linkend="GNode"><type>GNode</type></link> struct and its associated functions provide a N-ary tree data
structure, where nodes in the tree can contain arbitrary data.
</para>
<para>
To create a new tree use <link linkend="g-node-new"><function>g_node_new()</function></link>.
</para>
<para>
To insert a node into a tree use <link linkend="g-node-insert"><function>g_node_insert()</function></link>, <link linkend="g-node-insert-before"><function>g_node_insert_before()</function></link>,
<link linkend="g-node-append"><function>g_node_append()</function></link> and <link linkend="g-node-prepend"><function>g_node_prepend()</function></link>.
</para>
<para>
To create a new node and insert it into a tree use <link linkend="g-node-insert-data"><function>g_node_insert_data()</function></link>,
<link linkend="g-node-insert-data-before"><function>g_node_insert_data_before()</function></link>, <link linkend="g-node-append-data"><function>g_node_append_data()</function></link> and <link linkend="g-node-prepend-data"><function>g_node_prepend_data()</function></link>.
</para>
<para>
To reverse the children of a node use <link linkend="g-node-reverse-children"><function>g_node_reverse_children()</function></link>.
</para>
<para>
To find a node use <link linkend="g-node-get-root"><function>g_node_get_root()</function></link>, <link linkend="g-node-find"><function>g_node_find()</function></link>, <link linkend="g-node-find-child"><function>g_node_find_child()</function></link>,
<link linkend="g-node-child-index"><function>g_node_child_index()</function></link>, <link linkend="g-node-child-position"><function>g_node_child_position()</function></link>,
<link linkend="g-node-first-child"><function>g_node_first_child()</function></link>, <link linkend="g-node-last-child"><function>g_node_last_child()</function></link>,
<link linkend="g-node-nth-child"><function>g_node_nth_child()</function></link>, <link linkend="g-node-first-sibling"><function>g_node_first_sibling()</function></link>, <link linkend="g-node-prev-sibling"><function>g_node_prev_sibling()</function></link>,
<link linkend="g-node-next-sibling"><function>g_node_next_sibling()</function></link> or <link linkend="g-node-last-sibling"><function>g_node_last_sibling()</function></link>.
</para>
<para>
To get information about a node or tree use <link linkend="G-NODE-IS-LEAF--CAPS"><function>G_NODE_IS_LEAF()</function></link>,
<link linkend="G-NODE-IS-ROOT--CAPS"><function>G_NODE_IS_ROOT()</function></link>, <link linkend="g-node-depth"><function>g_node_depth()</function></link>, <link linkend="g-node-n-nodes"><function>g_node_n_nodes()</function></link>, <link linkend="g-node-n-children"><function>g_node_n_children()</function></link>,
<link linkend="g-node-is-ancestor"><function>g_node_is_ancestor()</function></link> or <link linkend="g-node-max-height"><function>g_node_max_height()</function></link>.
</para>
<para>
To traverse a tree, calling a function for each node visited in the
traversal, use <link linkend="g-node-traverse"><function>g_node_traverse()</function></link> or <link linkend="g-node-children-foreach"><function>g_node_children_foreach()</function></link>.
</para>
<para>
To remove a node or subtree from a tree use <link linkend="g-node-unlink"><function>g_node_unlink()</function></link> or
<link linkend="g-node-destroy"><function>g_node_destroy()</function></link>.
</para>
</refsect1>

<refsect1 id="glib-N-ary-Trees.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GNode" role="struct">
<title>GNode</title>
<indexterm zone="GNode"><primary sortas="Node">GNode</primary></indexterm><programlisting>typedef struct {
  gpointer data;
  GNode	  *next;
  GNode	  *prev;
  GNode	  *parent;
  GNode	  *children;
} GNode;
</programlisting>
<para>
The <structname>GNode</structname> struct represents one node in a
<link linkend="glib-N-ary-Trees">N-ary Tree</link>.
fields
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="gpointer">gpointer</link>&#160;<structfield>data</structfield>;</term>
<listitem><simpara>contains the actual data of the node.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GNode">GNode</link>&#160;*<structfield>next</structfield>;</term>
<listitem><simpara>points to the node's next sibling (a sibling is another 
  <structname>GNode</structname> with the same parent).
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GNode">GNode</link>&#160;*<structfield>prev</structfield>;</term>
<listitem><simpara>points to the node's previous sibling.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GNode">GNode</link>&#160;*<structfield>parent</structfield>;</term>
<listitem><simpara>points to the parent of the <structname>GNode</structname>,
  or is <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the <structname>GNode</structname> is the root of the tree.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GNode">GNode</link>&#160;*<structfield>children</structfield>;</term>
<listitem><simpara>The <structfield>children</structfield> field points to the first 
  child of the <structname>GNode</structname>. The other children are accessed
  by using the <structfield>next</structfield> pointer of each child.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-new" role="function">
<title>g_node_new ()</title>
<indexterm zone="g-node-new"><primary sortas="node_new">g_node_new</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_new                          (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Creates a new <link linkend="GNode"><type>GNode</type></link> containing the given data.
Used to create the first node in a tree.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data of the new node
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-copy" role="function">
<title>g_node_copy ()</title>
<indexterm zone="g-node-copy"><primary sortas="node_copy">g_node_copy</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_copy                         (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Recursively copies a <link linkend="GNode"><type>GNode</type></link> (but does not deep-copy the data inside the 
nodes, see <link linkend="g-node-copy-deep"><function>g_node_copy_deep()</function></link> if you need that).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GNode"><type>GNode</type></link> containing the same data pointers
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GCopyFunc" role="function" condition="since:2.4">
<title>GCopyFunc ()</title>
<indexterm zone="GCopyFunc" role="2.4"><primary sortas="CopyFunc">GCopyFunc</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            (*GCopyFunc)                        (<link linkend="gconstpointer">gconstpointer</link> src,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
A function of this signature is used to copy the node data 
when doing a deep-copy of a tree.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>src</parameter>&#160;:</term>
<listitem><simpara> A pointer to the data which should be copied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> Additional data
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A pointer to the copy

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-node-copy-deep" role="function" condition="since:2.4">
<title>g_node_copy_deep ()</title>
<indexterm zone="g-node-copy-deep" role="2.4"><primary sortas="node_copy_deep">g_node_copy_deep</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_copy_deep                    (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GCopyFunc">GCopyFunc</link> copy_func,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Recursively copies a <link linkend="GNode"><type>GNode</type></link> and its data.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>copy_func</parameter>&#160;:</term>
<listitem><simpara> the function which is called to copy the data inside each node,
  or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to use the original data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> data to pass to <parameter>copy_func</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GNode"><type>GNode</type></link> containing copies of the data in <parameter>node</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-node-insert" role="function">
<title>g_node_insert ()</title>
<indexterm zone="g-node-insert"><primary sortas="node_insert">g_node_insert</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_insert                       (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="gint">gint</link> position,
                                                         <link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Inserts a <link linkend="GNode"><type>GNode</type></link> beneath the parent at the given position.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place <parameter>node</parameter> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>position</parameter>&#160;:</term>
<listitem><simpara> the position to place <parameter>node</parameter> at, with respect to its siblings
    If position is -1, <parameter>node</parameter> is inserted as the last child of <parameter>parent</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to insert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the inserted <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-insert-before" role="function">
<title>g_node_insert_before ()</title>
<indexterm zone="g-node-insert-before"><primary sortas="node_insert_before">g_node_insert_before</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_insert_before                (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="GNode">GNode</link> *sibling,
                                                         <link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Inserts a <link linkend="GNode"><type>GNode</type></link> beneath the parent before the given sibling.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place <parameter>node</parameter> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sibling</parameter>&#160;:</term>
<listitem><simpara> the sibling <link linkend="GNode"><type>GNode</type></link> to place <parameter>node</parameter> before. 
    If sibling is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the node is inserted as the last child of <parameter>parent</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to insert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the inserted <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-insert-after" role="function">
<title>g_node_insert_after ()</title>
<indexterm zone="g-node-insert-after"><primary sortas="node_insert_after">g_node_insert_after</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_insert_after                 (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="GNode">GNode</link> *sibling,
                                                         <link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Inserts a <link linkend="GNode"><type>GNode</type></link> beneath the parent after the given sibling.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place <parameter>node</parameter> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sibling</parameter>&#160;:</term>
<listitem><simpara> the sibling <link linkend="GNode"><type>GNode</type></link> to place <parameter>node</parameter> after. 
    If sibling is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, the node is inserted as the first child of <parameter>parent</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to insert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the inserted <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-append" role="macro">
<title>g_node_append()</title>
<indexterm zone="g-node-append"><primary sortas="node_append">g_node_append</primary></indexterm><programlisting>#define             g_node_append(parent, node)</programlisting>
<para>
Inserts a <link linkend="GNode"><type>GNode</type></link> as the last child of the given parent.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place the new <link linkend="GNode"><type>GNode</type></link> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to insert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the inserted <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-prepend" role="function">
<title>g_node_prepend ()</title>
<indexterm zone="g-node-prepend"><primary sortas="node_prepend">g_node_prepend</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_prepend                      (<link linkend="GNode">GNode</link> *parent,
                                                         <link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Inserts a <link linkend="GNode"><type>GNode</type></link> as the first child of the given parent.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place the new <link linkend="GNode"><type>GNode</type></link> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to insert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the inserted <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-insert-data" role="macro">
<title>g_node_insert_data()</title>
<indexterm zone="g-node-insert-data"><primary sortas="node_insert_data">g_node_insert_data</primary></indexterm><programlisting>#define             g_node_insert_data(parent, position, data)</programlisting>
<para>
Inserts a new <link linkend="GNode"><type>GNode</type></link> at the given position.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place the new <link linkend="GNode"><type>GNode</type></link> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>position</parameter>&#160;:</term>
<listitem><simpara> the position to place the new <link linkend="GNode"><type>GNode</type></link> at. If position is -1, 
    the new <link linkend="GNode"><type>GNode</type></link> is inserted as the last child of <parameter>parent</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data for the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-insert-data-before" role="macro">
<title>g_node_insert_data_before()</title>
<indexterm zone="g-node-insert-data-before"><primary sortas="node_insert_data_before">g_node_insert_data_before</primary></indexterm><programlisting>#define             g_node_insert_data_before(parent, sibling, data)</programlisting>
<para>
Inserts a new <link linkend="GNode"><type>GNode</type></link> before the given sibling.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place the new <link linkend="GNode"><type>GNode</type></link> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sibling</parameter>&#160;:</term>
<listitem><simpara> the sibling <link linkend="GNode"><type>GNode</type></link> to place the new <link linkend="GNode"><type>GNode</type></link> before
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data for the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-append-data" role="macro">
<title>g_node_append_data()</title>
<indexterm zone="g-node-append-data"><primary sortas="node_append_data">g_node_append_data</primary></indexterm><programlisting>#define             g_node_append_data(parent, data)</programlisting>
<para>
Inserts a new <link linkend="GNode"><type>GNode</type></link> as the last child of the given parent.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place the new <link linkend="GNode"><type>GNode</type></link> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data for the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-prepend-data" role="macro">
<title>g_node_prepend_data()</title>
<indexterm zone="g-node-prepend-data"><primary sortas="node_prepend_data">g_node_prepend_data</primary></indexterm><programlisting>#define             g_node_prepend_data(parent, data)</programlisting>
<para>
Inserts a new <link linkend="GNode"><type>GNode</type></link> as the first child of the given parent.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to place the new <link linkend="GNode"><type>GNode</type></link> under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data for the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-reverse-children" role="function">
<title>g_node_reverse_children ()</title>
<indexterm zone="g-node-reverse-children"><primary sortas="node_reverse_children">g_node_reverse_children</primary></indexterm><programlisting><link linkend="void">void</link>                g_node_reverse_children             (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Reverses the order of the children of a <link linkend="GNode"><type>GNode</type></link>.
(It doesn't change the order of the grandchildren.)</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-traverse" role="function">
<title>g_node_traverse ()</title>
<indexterm zone="g-node-traverse"><primary sortas="node_traverse">g_node_traverse</primary></indexterm><programlisting><link linkend="void">void</link>                g_node_traverse                     (<link linkend="GNode">GNode</link> *root,
                                                         <link linkend="GTraverseType">GTraverseType</link> order,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="gint">gint</link> max_depth,
                                                         <link linkend="GNodeTraverseFunc">GNodeTraverseFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Traverses a tree starting at the given root <link linkend="GNode"><type>GNode</type></link>.
It calls the given function for each node visited.
The traversal can be halted at any point by returning <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> from <parameter>func</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>root</parameter>&#160;:</term>
<listitem><simpara> the root <link linkend="GNode"><type>GNode</type></link> of the tree to traverse
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>order</parameter>&#160;:</term>
<listitem><simpara> the order in which nodes are visited - <link linkend="G-IN-ORDER--CAPS"><literal>G_IN_ORDER</literal></link>, 
    <link linkend="G-PRE-ORDER--CAPS"><literal>G_PRE_ORDER</literal></link>, <link linkend="G-POST-ORDER--CAPS"><literal>G_POST_ORDER</literal></link>, or <link linkend="G-LEVEL-ORDER--CAPS"><literal>G_LEVEL_ORDER</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&#160;:</term>
<listitem><simpara> which types of children are to be visited, one of 
    <link linkend="G-TRAVERSE-ALL--CAPS"><literal>G_TRAVERSE_ALL</literal></link>, <link linkend="G-TRAVERSE-LEAVES--CAPS"><literal>G_TRAVERSE_LEAVES</literal></link> and <link linkend="G-TRAVERSE-NON-LEAVES--CAPS"><literal>G_TRAVERSE_NON_LEAVES</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_depth</parameter>&#160;:</term>
<listitem><simpara> 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.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call for each visited <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> user data to pass to the function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GTraverseFlags" role="enum">
<title>enum GTraverseFlags</title>
<indexterm zone="GTraverseFlags"><primary sortas="TraverseFlags">GTraverseFlags</primary></indexterm><programlisting>typedef enum
{
  G_TRAVERSE_LEAVES     = 1 &lt;&lt; 0,
  G_TRAVERSE_NON_LEAVES = 1 &lt;&lt; 1,
  G_TRAVERSE_ALL        = G_TRAVERSE_LEAVES | G_TRAVERSE_NON_LEAVES,
  G_TRAVERSE_MASK       = 0x03,
  G_TRAVERSE_LEAFS      = G_TRAVERSE_LEAVES,
  G_TRAVERSE_NON_LEAFS  = G_TRAVERSE_NON_LEAVES
} GTraverseFlags;
</programlisting>
<para>
Specifies which nodes are visited during several of the tree functions,
including <link linkend="g-node-traverse"><function>g_node_traverse()</function></link> and <link linkend="g-node-find"><function>g_node_find()</function></link>.
</para><variablelist role="enum">
<varlistentry id="G-TRAVERSE-LEAVES--CAPS" role="constant">
<term><literal>G_TRAVERSE_LEAVES</literal></term>
<listitem><simpara>only leaf nodes should be visited. This name has been
  introduced in 2.6, for older version use <link linkend="G-TRAVERSE-LEAFS--CAPS"><literal>G_TRAVERSE_LEAFS</literal></link>.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-TRAVERSE-NON-LEAVES--CAPS" role="constant">
<term><literal>G_TRAVERSE_NON_LEAVES</literal></term>
<listitem><simpara>only non-leaf nodes should be visited. This name 
  has been introduced in 2.6, for older version use <link linkend="G-TRAVERSE-NON-LEAFS--CAPS"><literal>G_TRAVERSE_NON_LEAFS</literal></link>.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-TRAVERSE-ALL--CAPS" role="constant">
<term><literal>G_TRAVERSE_ALL</literal></term>
<listitem><simpara>all nodes should be visited.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-TRAVERSE-MASK--CAPS" role="constant">
<term><literal>G_TRAVERSE_MASK</literal></term>
<listitem><simpara>a mask of all traverse flags.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-TRAVERSE-LEAFS--CAPS" role="constant">
<term><literal>G_TRAVERSE_LEAFS</literal></term>
<listitem><simpara>identical to <link linkend="G-TRAVERSE-LEAVES--CAPS"><literal>G_TRAVERSE_LEAVES</literal></link>.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-TRAVERSE-NON-LEAFS--CAPS" role="constant">
<term><literal>G_TRAVERSE_NON_LEAFS</literal></term>
<listitem><simpara>identical to <link linkend="G-TRAVERSE-NON-LEAVES--CAPS"><literal>G_TRAVERSE_NON_LEAVES</literal></link>.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="GNodeTraverseFunc" role="function">
<title>GNodeTraverseFunc ()</title>
<indexterm zone="GNodeTraverseFunc"><primary sortas="NodeTraverseFunc">GNodeTraverseFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GNodeTraverseFunc)                (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <link linkend="g-node-traverse"><function>g_node_traverse()</function></link>.
The function is called with each of the nodes visited, together with the
user data passed to <link linkend="g-node-traverse"><function>g_node_traverse()</function></link>.
If the function returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, then the traversal is stopped.
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GNode"><type>GNode</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>user data passed to <link linkend="g-node-traverse"><function>g_node_traverse()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE to stop the traversal.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-children-foreach" role="function">
<title>g_node_children_foreach ()</title>
<indexterm zone="g-node-children-foreach"><primary sortas="node_children_foreach">g_node_children_foreach</primary></indexterm><programlisting><link linkend="void">void</link>                g_node_children_foreach             (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="GNodeForeachFunc">GNodeForeachFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Calls a function for each of the children of a <link linkend="GNode"><type>GNode</type></link>.
Note that it doesn't descend beneath the child nodes.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&#160;:</term>
<listitem><simpara> which types of children are to be visited, one of 
    <link linkend="G-TRAVERSE-ALL--CAPS"><literal>G_TRAVERSE_ALL</literal></link>, <link linkend="G-TRAVERSE-LEAVES--CAPS"><literal>G_TRAVERSE_LEAVES</literal></link> and <link linkend="G-TRAVERSE-NON-LEAVES--CAPS"><literal>G_TRAVERSE_NON_LEAVES</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call for each visited node
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> user data to pass to the function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GNodeForeachFunc" role="function">
<title>GNodeForeachFunc ()</title>
<indexterm zone="GNodeForeachFunc"><primary sortas="NodeForeachFunc">GNodeForeachFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GNodeForeachFunc)                 (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <link linkend="g-node-children-foreach"><function>g_node_children_foreach()</function></link>.
The function is called with each child node, together with the user data
passed to <link linkend="g-node-children-foreach"><function>g_node_children_foreach()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GNode"><type>GNode</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>user data passed to <link linkend="g-node-children-foreach"><function>g_node_children_foreach()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-get-root" role="function">
<title>g_node_get_root ()</title>
<indexterm zone="g-node-get-root"><primary sortas="node_get_root">g_node_get_root</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_get_root                     (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Gets the root of a tree.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the root of the tree
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-find" role="function">
<title>g_node_find ()</title>
<indexterm zone="g-node-find"><primary sortas="node_find">g_node_find</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_find                         (<link linkend="GNode">GNode</link> *root,
                                                         <link linkend="GTraverseType">GTraverseType</link> order,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Finds a <link linkend="GNode"><type>GNode</type></link> in a tree.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>root</parameter>&#160;:</term>
<listitem><simpara> the root <link linkend="GNode"><type>GNode</type></link> of the tree to search
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>order</parameter>&#160;:</term>
<listitem><simpara> the order in which nodes are visited - <link linkend="G-IN-ORDER--CAPS"><literal>G_IN_ORDER</literal></link>, 
    <link linkend="G-PRE-ORDER--CAPS"><literal>G_PRE_ORDER</literal></link>, <link linkend="G-POST-ORDER--CAPS"><literal>G_POST_ORDER</literal></link>, or <link linkend="G-LEVEL-ORDER--CAPS"><literal>G_LEVEL_ORDER</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&#160;:</term>
<listitem><simpara> which types of children are to be searched, one of 
    <link linkend="G-TRAVERSE-ALL--CAPS"><literal>G_TRAVERSE_ALL</literal></link>, <link linkend="G-TRAVERSE-LEAVES--CAPS"><literal>G_TRAVERSE_LEAVES</literal></link> and <link linkend="G-TRAVERSE-NON-LEAVES--CAPS"><literal>G_TRAVERSE_NON_LEAVES</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data to find
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the found <link linkend="GNode"><type>GNode</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the data is not found
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-find-child" role="function">
<title>g_node_find_child ()</title>
<indexterm zone="g-node-find-child"><primary sortas="node_find_child">g_node_find_child</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_find_child                   (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Finds the first child of a <link linkend="GNode"><type>GNode</type></link> with the given data.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&#160;:</term>
<listitem><simpara> which types of children are to be searched, one of 
    <link linkend="G-TRAVERSE-ALL--CAPS"><literal>G_TRAVERSE_ALL</literal></link>, <link linkend="G-TRAVERSE-LEAVES--CAPS"><literal>G_TRAVERSE_LEAVES</literal></link> and <link linkend="G-TRAVERSE-NON-LEAVES--CAPS"><literal>G_TRAVERSE_NON_LEAVES</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data to find
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the found child <link linkend="GNode"><type>GNode</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the data is not found
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-child-index" role="function">
<title>g_node_child_index ()</title>
<indexterm zone="g-node-child-index"><primary sortas="node_child_index">g_node_child_index</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_node_child_index                  (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Gets the position of the first child of a <link linkend="GNode"><type>GNode</type></link> 
which contains the given data.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the data to find
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the index of the child of <parameter>node</parameter> which contains 
    <parameter>data</parameter>, or -1 if the data is not found
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-child-position" role="function">
<title>g_node_child_position ()</title>
<indexterm zone="g-node-child-position"><primary sortas="node_child_position">g_node_child_position</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_node_child_position               (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GNode">GNode</link> *child);</programlisting>
<para>
Gets the position of a <link linkend="GNode"><type>GNode</type></link> with respect to its siblings.
<parameter>child</parameter> must be a child of <parameter>node</parameter>. The first child is numbered 0, 
the second 1, and so on.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>child</parameter>&#160;:</term>
<listitem><simpara> a child of <parameter>node</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the position of <parameter>child</parameter> with respect to its siblings
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-first-child" role="macro">
<title>g_node_first_child()</title>
<indexterm zone="g-node-first-child"><primary sortas="node_first_child">g_node_first_child</primary></indexterm><programlisting>#define             g_node_first_child(node)</programlisting>
<para>
Gets the first child of a <link linkend="GNode"><type>GNode</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the first child of <parameter>node</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>node</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> 
    or has no children
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-last-child" role="function">
<title>g_node_last_child ()</title>
<indexterm zone="g-node-last-child"><primary sortas="node_last_child">g_node_last_child</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_last_child                   (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Gets the last child of a <link linkend="GNode"><type>GNode</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link> (must not be <link linkend="NULL--CAPS"><literal>NULL</literal></link>)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the last child of <parameter>node</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>node</parameter> has no children
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-nth-child" role="function">
<title>g_node_nth_child ()</title>
<indexterm zone="g-node-nth-child"><primary sortas="node_nth_child">g_node_nth_child</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_nth_child                    (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="guint">guint</link> n);</programlisting>
<para>
Gets a child of a <link linkend="GNode"><type>GNode</type></link>, using the given index.
The first child is at index 0. If the index is 
too big, <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara> the index of the desired child
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the child of <parameter>node</parameter> at index <parameter>n</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-first-sibling" role="function">
<title>g_node_first_sibling ()</title>
<indexterm zone="g-node-first-sibling"><primary sortas="node_first_sibling">g_node_first_sibling</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_first_sibling                (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Gets the first sibling of a <link linkend="GNode"><type>GNode</type></link>.
This could possibly be the node itself.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the first sibling of <parameter>node</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-next-sibling" role="macro">
<title>g_node_next_sibling()</title>
<indexterm zone="g-node-next-sibling"><primary sortas="node_next_sibling">g_node_next_sibling</primary></indexterm><programlisting>#define             g_node_next_sibling(node)</programlisting>
<para>
Gets the next sibling of a <link linkend="GNode"><type>GNode</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the next sibling of <parameter>node</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>node</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-prev-sibling" role="macro">
<title>g_node_prev_sibling()</title>
<indexterm zone="g-node-prev-sibling"><primary sortas="node_prev_sibling">g_node_prev_sibling</primary></indexterm><programlisting>#define             g_node_prev_sibling(node)</programlisting>
<para>
Gets the previous sibling of a <link linkend="GNode"><type>GNode</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the previous sibling of <parameter>node</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>node</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-last-sibling" role="function">
<title>g_node_last_sibling ()</title>
<indexterm zone="g-node-last-sibling"><primary sortas="node_last_sibling">g_node_last_sibling</primary></indexterm><programlisting><link linkend="GNode">GNode</link>*              g_node_last_sibling                 (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Gets the last sibling of a <link linkend="GNode"><type>GNode</type></link>.
This could possibly be the node itself.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the last sibling of <parameter>node</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-NODE-IS-LEAF--CAPS" role="macro">
<title>G_NODE_IS_LEAF()</title>
<indexterm zone="G-NODE-IS-LEAF--CAPS"><primary sortas="NODE_IS_LEAF">G_NODE_IS_LEAF</primary></indexterm><programlisting>#define	 G_NODE_IS_LEAF(node)	(((GNode*) (node))-&gt;children == NULL)
</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if a <link linkend="GNode"><type>GNode</type></link> is a leaf node.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <link linkend="GNode"><type>GNode</type></link> is a leaf node 
    (i.e. it has no children)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-NODE-IS-ROOT--CAPS" role="macro">
<title>G_NODE_IS_ROOT()</title>
<indexterm zone="G-NODE-IS-ROOT--CAPS"><primary sortas="NODE_IS_ROOT">G_NODE_IS_ROOT</primary></indexterm><programlisting>#define             G_NODE_IS_ROOT(node)</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if a <link linkend="GNode"><type>GNode</type></link> is the root of a tree.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <link linkend="GNode"><type>GNode</type></link> is the root of a tree 
    (i.e. it has no parent or siblings)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-depth" role="function">
<title>g_node_depth ()</title>
<indexterm zone="g-node-depth"><primary sortas="node_depth">g_node_depth</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_node_depth                        (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Gets the depth of a <link linkend="GNode"><type>GNode</type></link>.
</para>
<para>
If <parameter>node</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> 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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the depth of the <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-n-nodes" role="function">
<title>g_node_n_nodes ()</title>
<indexterm zone="g-node-n-nodes"><primary sortas="node_n_nodes">g_node_n_nodes</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_node_n_nodes                      (<link linkend="GNode">GNode</link> *root,
                                                         <link linkend="GTraverseFlags">GTraverseFlags</link> flags);</programlisting>
<para>
Gets the number of nodes in a tree.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>root</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&#160;:</term>
<listitem><simpara> which types of children are to be counted, one of 
    <link linkend="G-TRAVERSE-ALL--CAPS"><literal>G_TRAVERSE_ALL</literal></link>, <link linkend="G-TRAVERSE-LEAVES--CAPS"><literal>G_TRAVERSE_LEAVES</literal></link> and <link linkend="G-TRAVERSE-NON-LEAVES--CAPS"><literal>G_TRAVERSE_NON_LEAVES</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of nodes in the tree
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-n-children" role="function">
<title>g_node_n_children ()</title>
<indexterm zone="g-node-n-children"><primary sortas="node_n_children">g_node_n_children</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_node_n_children                   (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Gets the number of children of a <link linkend="GNode"><type>GNode</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of children of <parameter>node</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-is-ancestor" role="function">
<title>g_node_is_ancestor ()</title>
<indexterm zone="g-node-is-ancestor"><primary sortas="node_is_ancestor">g_node_is_ancestor</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_node_is_ancestor                  (<link linkend="GNode">GNode</link> *node,
                                                         <link linkend="GNode">GNode</link> *descendant);</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>node</parameter> is an ancestor of <parameter>descendant</parameter>.
This is true if node is the parent of <parameter>descendant</parameter>, 
or if node is the grandparent of <parameter>descendant</parameter> etc.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>descendant</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>node</parameter> is an ancestor of <parameter>descendant</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-max-height" role="function">
<title>g_node_max_height ()</title>
<indexterm zone="g-node-max-height"><primary sortas="node_max_height">g_node_max_height</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_node_max_height                   (<link linkend="GNode">GNode</link> *root);</programlisting>
<para>
Gets the maximum height of all branches beneath a <link linkend="GNode"><type>GNode</type></link>.
This is the maximum distance from the <link linkend="GNode"><type>GNode</type></link> to all leaf nodes.
</para>
<para>
If <parameter>root</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, 0 is returned. If <parameter>root</parameter> has no children, 
1 is returned. If <parameter>root</parameter> has children, 2 is returned. And so on.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>root</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GNode"><type>GNode</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the maximum height of the tree beneath <parameter>root</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-unlink" role="function">
<title>g_node_unlink ()</title>
<indexterm zone="g-node-unlink"><primary sortas="node_unlink">g_node_unlink</primary></indexterm><programlisting><link linkend="void">void</link>                g_node_unlink                       (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Unlinks a <link linkend="GNode"><type>GNode</type></link> from a tree, resulting in two separate trees.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>node</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GNode"><type>GNode</type></link> to unlink, which becomes the root of a new tree
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-destroy" role="function">
<title>g_node_destroy ()</title>
<indexterm zone="g-node-destroy"><primary sortas="node_destroy">g_node_destroy</primary></indexterm><programlisting><link linkend="void">void</link>                g_node_destroy                      (<link linkend="GNode">GNode</link> *root);</programlisting>
<para>
Removes <parameter>root</parameter> and its children from the tree, freeing any memory
allocated.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>root</parameter>&#160;:</term>
<listitem><simpara> the root of the tree/subtree to destroy
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-push-allocator" role="function" condition="deprecated">
<title>g_node_push_allocator ()</title>
<indexterm zone="g-node-push-allocator" role="deprecated"><primary sortas="node_push_allocator">g_node_push_allocator</primary></indexterm><programlisting><link linkend="void">void</link>                g_node_push_allocator               (<link linkend="gpointer">gpointer</link> dummy);</programlisting>
<warning><para><literal>g_node_push_allocator</literal> has been deprecated since version 2.10 and should not be used in newly-written code. It does nothing, since <link linkend="GNode"><type>GNode</type></link> has been converted
  to the <link linkend="glib-Memory-Slices">slice allocator</link></para></warning>
<para>
Sets the allocator to use to allocate <link linkend="GNode"><type>GNode</type></link> elements.
Use <link linkend="g-node-pop-allocator"><function>g_node_pop_allocator()</function></link> to restore the previous allocator.
</para>
<para>
Note that this function is not available if GLib has been compiled
with <option>--disable-mem-pools</option>
</para><variablelist role="params">
<varlistentry><term><parameter>dummy</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GAllocator"><type>GAllocator</type></link> to use when allocating <link linkend="GNode"><type>GNode</type></link> elements.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-node-pop-allocator" role="function" condition="deprecated">
<title>g_node_pop_allocator ()</title>
<indexterm zone="g-node-pop-allocator" role="deprecated"><primary sortas="node_pop_allocator">g_node_pop_allocator</primary></indexterm><programlisting><link linkend="void">void</link>                g_node_pop_allocator                (void);</programlisting>
<warning><para><literal>g_node_pop_allocator</literal> has been deprecated since version 2.10 and should not be used in newly-written code. It does nothing, since <link linkend="GNode"><type>GNode</type></link> has been converted
  to the <link linkend="glib-Memory-Slices">slice allocator</link></para></warning>
<para>
Restores the previous <link linkend="GAllocator"><type>GAllocator</type></link>, used when allocating <link linkend="GNode"><type>GNode</type></link> elements.
</para>
<para>
Note that this function is not available if GLib has been compiled
with <option>--disable-mem-pools</option>
</para></refsect2>

</refsect1>




</refentry>
