trees-binary.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><parameter>traverse_func</parameter>&nbsp;:</entry>
<entry> the function to call for each node visited. If this 
  function returns <literal>TRUE</literal>, the traversal is stopped.
</entry></row>
<row><entry align="right"><parameter>traverse_type</parameter>&nbsp;:</entry>
<entry> the order in which nodes are visited, one of <literal>G_IN_ORDER</literal>,
  <literal>G_PRE_ORDER</literal> and <literal>G_POST_ORDER</literal>.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to the function.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GTraverseFunc">GTraverseFunc ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    (*GTraverseFunc)                (<link linkend="gpointer">gpointer</link> key,
                                             <link linkend="gpointer">gpointer</link> value,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <link linkend="g-tree-traverse">g_tree_traverse</link>().
It is passed the key and value of each node, together with
the <parameter>user_data</parameter> parameter passed to <link linkend="g-tree-traverse">g_tree_traverse</link>().
If the function returns <literal>TRUE</literal>, the traversal is stopped.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry>a key of a <link linkend="GTree">GTree</link> node.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>the value corresponding to the key.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>user data passed to <link linkend="g-tree-traverse">g_tree_traverse</link>().
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> to stop the traversal.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GTraverseType">enum GTraverseType</title>
<programlisting>typedef enum
{
  G_IN_ORDER,
  G_PRE_ORDER,
  G_POST_ORDER,
  G_LEVEL_ORDER
} GTraverseType;
</programlisting>
<para>
Specifies the type of traveral performed by <link linkend="g-tree-traverse">g_tree_traverse</link>(),
<link linkend="g-node-traverse">g_node_traverse</link>() and <link linkend="g-node-find">g_node_find</link>().
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_IN_ORDER</literal></entry>
<entry>vists a node's left child first, then the node itself, then its
  right child. This is the one to use if you want the output sorted according
  to the compare function.
</entry>
</row>
<row>
<entry><literal>G_PRE_ORDER</literal></entry>
<entry>visits a node, then its children.
</entry>
</row>
<row>
<entry><literal>G_POST_ORDER</literal></entry>
<entry>visits the node's children, then the node itself.
</entry>
</row>
<row>
<entry><literal>G_LEVEL_ORDER</literal></entry>
<entry>is not implemented for
  <link linkend="glib-Balanced-Binary-Trees">Balanced Binary Trees</link>.
  For <link linkend="glib-N-ary-Trees">N-ary Trees</link>, it vists the root
  node first, then its children, then its grandchildren, and so on. Note that
  this is less efficient than the other orders.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-search">g_tree_search ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_tree_search                   (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="GCompareFunc">GCompareFunc</link> search_func,
                                             <link linkend="gconstpointer">gconstpointer</link> user_data);</programlisting>
<para>
Searches a <link linkend="GTree">GTree</link> using an alternative form of the comparison function.
</para>
<para>
This function is not as useful as it sounds.
It allows you to use a different function for performing the lookup of
a key. However, since the tree is ordered according to the <parameter>key_compare_func</parameter>
function passed to <link linkend="g-tree-new">g_tree_new</link>(), the function you pass to <link linkend="g-tree-search">g_tree_search</link>() 
must return exactly the same value as would be returned by the comparison 
function, for each pair of tree nodes, or the search will not work.
</para>
<para>
To search for a specific value, you can use <link linkend="g-tree-foreach">g_tree_foreach</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
<row><entry align="right"><parameter>search_func</parameter>&nbsp;:</entry>
<entry> the comparison function used to search the <link linkend="GTree">GTree</link>. 
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> the data passed as the second argument to the <parameter>search_func</parameter> 
function.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the value corresponding to the found key, or <literal>NULL</literal> if the key 
is not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-remove">g_tree_remove ()</title>
<programlisting>void        g_tree_remove                   (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Removes a key/value pair from a <link linkend="GTree">GTree</link>.
</para>
<para>
If the <link linkend="GTree">GTree</link> was created using <link linkend="g-tree-new-full">g_tree_new_full</link>(), the key and value 
are freed using the supplied destroy functions, otherwise you have to 
make sure that any dynamically allocated values are freed yourself.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="Gtree">Gtree</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to remove.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-steal">g_tree_steal ()</title>
<programlisting>void        g_tree_steal                    (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Removes a key and its associated value from a <link linkend="GTree">GTree</link> without calling 
the key and value destroy functions.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="Gtree">Gtree</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to remove.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-destroy">g_tree_destroy ()</title>
<programlisting>void        g_tree_destroy                  (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Destroys the <link linkend="GTree">GTree</link>. If keys and/or values are dynamically allocated, you 
should either free them first or create the <link linkend="GTree">GTree</link> using <link linkend="g-tree-new-full">g_tree_new_full</link>().
In the latter case the destroy functions you supplied will be called on 
all keys and values before destroying the <link linkend="GTree">GTree</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>tree</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>