trees-binary.sgml

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

so that the distance from the root to every leaf is as small as possible.</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 insert.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> the value corresponding to the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-replace">g_tree_replace ()</title>
<programlisting>void        g_tree_replace                  (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="gpointer">gpointer</link> key,
                                             <link linkend="gpointer">gpointer</link> value);</programlisting>
<para>
Inserts a new key and value into a <link linkend="GTree">GTree</link> similar to <link linkend="g-tree-insert">g_tree_insert</link>(). 
The difference is that if the key already exists in the <link linkend="GTree">GTree</link>, it gets 
replaced by the new key. If you supplied a <parameter>value_destroy_func</parameter> when 
creating the <link linkend="GTree">GTree</link>, the old value is freed using that function. If you 
supplied a <parameter>key_destroy_func</parameter> when creating the <link linkend="GTree">GTree</link>, the old key is 
freed using that function. 
</para>
<para>
The tree is automatically 'balanced' as new key/value pairs are added,
so that the distance from the root to every leaf is as small as possible.</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 insert.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> the value corresponding to the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-nnodes">g_tree_nnodes ()</title>
<programlisting><link linkend="gint">gint</link>        g_tree_nnodes                   (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Gets the number of nodes in a <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>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the number of nodes in the <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-height">g_tree_height ()</title>
<programlisting><link linkend="gint">gint</link>        g_tree_height                   (<link linkend="GTree">GTree</link> *tree);</programlisting>
<para>
Gets the height of a <link linkend="GTree">GTree</link>.
</para>
<para>
If the <link linkend="GTree">GTree</link> contains no nodes, the height is 0.
If the <link linkend="GTree">GTree</link> contains only one root node the height is 1.
If the root node has children the height is 2, etc.</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"><emphasis>Returns</emphasis> :</entry><entry> the height of the <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-lookup">g_tree_lookup ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_tree_lookup                   (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Gets the value corresponding to the given key. Since a <link linkend="GTree">GTree</link> is 
automatically balanced as key/value pairs are added, key lookup is very 
fast.</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 look up.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the value corresponding to the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-lookup-extended">g_tree_lookup_extended ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_tree_lookup_extended          (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="gconstpointer">gconstpointer</link> lookup_key,
                                             <link linkend="gpointer">gpointer</link> *orig_key,
                                             <link linkend="gpointer">gpointer</link> *value);</programlisting>
<para>
Looks up a key in the <link linkend="GTree">GTree</link>, returning the original key and the
associated value and a <link linkend="gboolean">gboolean</link> which is <literal>TRUE</literal> if the key was found. This 
is useful if you need to free the memory allocated for the original key, 
for example before calling <link linkend="g-tree-remove">g_tree_remove</link>().</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>lookup_key</parameter>&nbsp;:</entry>
<entry> the key to look up.
</entry></row>
<row><entry align="right"><parameter>orig_key</parameter>&nbsp;:</entry>
<entry> returns the original key.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> returns the value associated with the key.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the key was found in the <link linkend="GTree">GTree</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-foreach">g_tree_foreach ()</title>
<programlisting>void        g_tree_foreach                  (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="GTraverseFunc">GTraverseFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Calls the given function for each of the key/value pairs in the <link linkend="GTree">GTree</link>.
The function is passed the key and value of each pair, and the given
<parameter>data</parameter> parameter. The tree is traversed in sorted order.
</para>
<para>
The tree may not be modified while iterating over it (you can't 
add/remove items). To remove all items matching a predicate, you need 
to add each item to a list in your <link linkend="GTraverseFunc">GTraverseFunc</link> as you walk over 
the tree, then walk the list and remove each item.</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>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>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to the function.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-tree-traverse">g_tree_traverse ()</title>
<programlisting>void        g_tree_traverse                 (<link linkend="GTree">GTree</link> *tree,
                                             <link linkend="GTraverseFunc">GTraverseFunc</link> traverse_func,
                                             <link linkend="GTraverseType">GTraverseType</link> traverse_type,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<warning>
<para>
<literal>g_tree_traverse</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Calls the given function for each node in the <link linkend="GTree">GTree</link>. This function is
deprecated, since the order of a balanced tree is somewhat arbitrary.
If you just want to visit all nodes in sorted order, use <link linkend="g-tree-foreach">g_tree_foreach</link>() 
instead. If you really need to visit nodes in a different order, consider
using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>