luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-25 03:32:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

More GTree and GNode formatting and documentation fixes

Browse Source 
Among other things, add images for tree traversal types,
taken from Wikimedia Commons.
This commit is contained in:
Matthias Clasen 2014-01-19 23:49:12 -05:00
parent 5459d148d1
commit 647412603a
7 changed files with 2741 additions and 306 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/reference/glib/Makefile.am
View File

@ -55,7 +55,11 @@ IGNORE_HFILES = \
# Images to copy into HTML directory # Images to copy into HTML directory
HTML_IMAGES = \ HTML_IMAGES = \
file-name-encodings.png \ file-name-encodings.png \
mainloop-states.gif mainloop-states.gif \
Sorted_binary_tree_breadth-first_traversal.svg \
Sorted_binary_tree_inorder.svg \
Sorted_binary_tree_postorder.svg \
Sorted_binary_tree_preorder.svg
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE) # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
content_files = \ content_files = \
@ -90,6 +94,10 @@ EXTRA_DIST += \
mainloop-states.fig \ mainloop-states.fig \
mainloop-states.png \ mainloop-states.png \
mainloop-states.eps \ mainloop-states.eps \
Sorted_binary_tree_breadth-first_traversal.svg \
Sorted_binary_tree_inorder.svg \
Sorted_binary_tree_postorder.svg \
Sorted_binary_tree_preorder.svg \
version.xml.in version.xml.in
######################################################################## ########################################################################

134
docs/reference/glib/Sorted_binary_tree_breadth-first_traversal.svg Normal file
View File

@ -0,0 +1,134 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 16.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
width="266px" height="212px" viewBox="0 0 266 212" enable-background="new 0 0 266 212" xml:space="preserve">
<g>
<g>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="27.23" y1="23.192" x2="29.23" y2="23.192"/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9562,3.9562" x1="33.187" y1="23.192" x2="236.932" y2="23.192"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,23.192 240.91,23.192
238.97,23.677 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="24.646" x2="27.971" y2="76.427"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,76.912 24.095,77.396
26.095,77.396 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="77.396" x2="236.902" y2="77.396"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,77.396 240.91,77.396
238.97,77.881 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="78.85" x2="27.971" y2="130.631"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,131.114 24.095,131.6
26.095,131.6 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="131.6" x2="236.902" y2="131.6"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,131.6 240.91,131.6
238.97,132.085 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="133.053" x2="27.971" y2="184.835"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,185.318 24.095,185.804
26.095,185.804 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0086,4.0086" x1="30.104" y1="185.804" x2="228.53" y2="185.804"/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="230.534" y1="185.804" x2="232.534" y2="185.804"/>
<g>
<rect x="24.095" y="19.892" width="6.602" height="6.602"/>
</g>
<g>
<path d="M238.569,185.804c-2.84,1.054-6.363,2.852-8.548,4.756l1.721-4.756l-1.721-4.755
C232.206,182.953,235.729,184.751,238.569,185.804z"/>
</g>
</g>
</g>
<g id="graph0">
<title>sorted_binary_tree</title>
<g id="node1">
<title>C</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="185.804" rx="18.067" ry="18.067"/>
<text transform="matrix(1 0 0 1 55.5435 190.8223)" font-family="'Times-Roman'" font-size="14.0528">C</text>
</g>
<g id="node2">
<title>E</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="185.804" rx="18.067" ry="18.067"/>
<text transform="matrix(1 0 0 1 128.21 190.8223)" font-family="'Times-Roman'" font-size="14.0528">E</text>
</g>
<g id="node3">
<title>H</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="185.804" rx="17.064" ry="18.067"/>
<text transform="matrix(1 0 0 1 199.6992 190.8223)" font-family="'Times-Roman'" font-size="14.0528">H</text>
</g>
<g id="node4">
<title>A</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="24.094" cy="131.6" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 19.02 136.6191)" font-family="'Times-Roman'" font-size="14.0528">A</text>
</g>
<g id="node5">
<title>D</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="96.366" cy="131.6" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 91.292 136.6191)" font-family="'Times-Roman'" font-size="14.0528">D</text>
</g>
<g id="edge6">
<title>D-&gt;C</title>
<path fill="none" stroke="#000000" d="M86.328,147.66c-3.011,4.016-7.026,9.034-10.038,14.053"/>
<polygon stroke="#000000" points="78.298,164.725 70.268,170.747 73.279,160.709 "/>
</g>
<g id="edge8">
<title>D-&gt;E</title>
<path fill="none" stroke="#000000" d="M106.404,147.66c3.011,4.016,7.026,9.034,10.038,14.053"/>
<polygon stroke="#000000" points="119.453,160.709 122.464,170.747 114.434,164.725 "/>
</g>
<g id="node6">
<title>I</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="240.909" cy="131.6" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 238.5693 136.6191)" font-family="'Times-Roman'" font-size="14.0528">I</text>
</g>
<g id="edge12">
<title>I-&gt;H</title>
<path fill="none" stroke="#000000" d="M230.871,146.656c-3.011,5.02-6.021,10.038-10.037,15.057"/>
<polygon stroke="#000000" points="223.846,163.721 214.812,169.743 217.822,159.705 "/>
</g>
<g id="node7">
<title>B</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="77.396" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 55.5435 82.415)" font-family="'Times-Roman'" font-size="14.0528">B</text>
</g>
<g id="edge3">
<title>B-&gt;A</title>
<path fill="none" stroke="#000000" d="M50.192,92.453c-3.011,5.019-6.022,10.038-10.038,15.057"/>
<polygon stroke="#000000" points="43.166,109.518 34.132,115.539 37.144,105.502 "/>
</g>
<g id="edge5">
<title>B-&gt;D</title>
<path fill="none" stroke="#000000" d="M70.268,92.453c3.011,5.019,6.022,10.038,10.038,15.057"/>
<polygon stroke="#000000" points="83.317,105.502 86.328,115.539 77.294,109.518 "/>
</g>
<g id="node8">
<title>G</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="77.396" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 199.6992 82.415)" font-family="'Times-Roman'" font-size="14.0528">G</text>
</g>
<g id="edge11">
<title>G-&gt;I</title>
<path fill="none" stroke="#000000" d="M214.812,93.457c3.011,4.015,7.026,9.034,10.038,14.053"/>
<polygon stroke="#000000" points="227.86,106.506 230.871,116.543 222.842,110.521 "/>
</g>
<g id="node9">
<title>F</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="23.192" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 128.5942 28.2109)" font-family="'Times-Roman'" font-size="14.0528">F</text>
</g>
<g id="edge2">
<title>F-&gt;B</title>
<path fill="none" stroke="#000000" d="M117.445,34.234c-11.042,8.03-23.087,17.064-34.128,26.098"/>
<polygon stroke="#000000" points="85.325,63.343 75.287,66.354 81.31,57.321 "/>
</g>
<g id="edge10">
<title>F-&gt;G</title>
<path fill="none" stroke="#000000" d="M147.559,34.234c11.041,8.03,23.087,17.064,34.129,26.098"/>
<polygon stroke="#000000" points="183.694,57.321 189.717,66.354 179.68,63.343 "/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

753
docs/reference/glib/Sorted_binary_tree_inorder.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

750
docs/reference/glib/Sorted_binary_tree_postorder.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

750
docs/reference/glib/Sorted_binary_tree_preorder.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

53
glib/gnode.c
View File

@ -820,6 +820,59 @@ g_node_depth_traverse_level (GNode *node,
* It calls the given function for each node visited. * It calls the given function for each node visited.
* The traversal can be halted at any point by returning %TRUE from @func. * The traversal can be halted at any point by returning %TRUE from @func.
*/ */
/**
* GTraverseType:
* @G_IN_ORDER: 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.
* <informalfigure>
* <mediaobject>
* <imageobject>
* <imagedata align="right" fileref="Sorted_binary_tree_inorder.svg" format="SVG"/>
* </imageobject>
* <caption>In order: A, B, C, D, E, F, G, H, I</caption>
* </mediaobject>
* </informalfigure>
* @G_PRE_ORDER: visits a node, then its children.
* <informalfigure>
* <mediaobject>
* <imageobject>
* <imagedata align="right" fileref="Sorted_binary_tree_preorder.svg" format="SVG"/>
* </imageobject>
* <caption>Pre order: F, B, A, D, C, E, G, I, H</caption>
* </mediaobject>
* </informalfigure>
* @G_POST_ORDER: visits the node's children, then the node itself.
* <informalfigure>
* <mediaobject>
* <imageobject>
* <imagedata align="right" fileref="Sorted_binary_tree_postorder.svg" format="SVG"/>
* </imageobject>
* <caption>Post order: A, C, E, D, B, H, I, G, F</caption>
* </mediaobject>
* </informalfigure>
* @G_LEVEL_ORDER: 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.
* <informalfigure>
* <mediaobject>
* <imageobject>
* <imagedata align="right" fileref="Sorted_binary_tree_breadth-first_traversal.svg" format="SVG"/>
* </imageobject>
* <caption>Level order: F, B, G, A, D, I, C, E, H</caption>
* </mediaobject>
* </informalfigure>
*
* Specifies the type of traveral performed by g_tree_traverse(),
* g_node_traverse() and g_node_find().
*/
/** /**
* GTraverseFlags: * GTraverseFlags:
* @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has

225
glib/gtree.c
View File

@ -77,7 +77,7 @@ typedef struct _GTreeNode GTreeNode;
* structure representing a <link * structure representing a <link
* linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. It * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. It
* should be accessed only by using the following functions. * should be accessed only by using the following functions.
**/ */
struct _GTree struct _GTree
{ {
GTreeNode *root; GTreeNode *root;
@ -159,9 +159,9 @@ g_tree_node_new (gpointer key,
* *
* Creates a new #GTree. * Creates a new #GTree.
* *
* Return value: a new #GTree. * Return value: a newly allocated #GTree
**/ */
GTree* GTree *
g_tree_new (GCompareFunc key_compare_func) g_tree_new (GCompareFunc key_compare_func)
{ {
g_return_val_if_fail (key_compare_func != NULL, NULL); g_return_val_if_fail (key_compare_func != NULL, NULL);
@ -172,15 +172,15 @@ g_tree_new (GCompareFunc key_compare_func)
/** /**
* g_tree_new_with_data: * g_tree_new_with_data:
* @key_compare_func: qsort()-style comparison function. * @key_compare_func: qsort()-style comparison function
* @key_compare_data: data to pass to comparison function. * @key_compare_data: data to pass to comparison function
* *
* Creates a new #GTree with a comparison function that accepts user data. * Creates a new #GTree with a comparison function that accepts user data.
* See g_tree_new() for more details. * See g_tree_new() for more details.
* *
* Return value: a new #GTree. * Return value: a newly allocated #GTree
**/ */
GTree* GTree *
g_tree_new_with_data (GCompareDataFunc key_compare_func, g_tree_new_with_data (GCompareDataFunc key_compare_func,
gpointer key_compare_data) gpointer key_compare_data)
{ {
@ -192,22 +192,22 @@ g_tree_new_with_data (GCompareDataFunc key_compare_func,
/** /**
* g_tree_new_full: * g_tree_new_full:
* @key_compare_func: qsort()-style comparison function. * @key_compare_func: qsort()-style comparison function
* @key_compare_data: data to pass to comparison function. * @key_compare_data: data to pass to comparison function
* @key_destroy_func: a function to free the memory allocated for the key * @key_destroy_func: a function to free the memory allocated for the key
* used when removing the entry from the #GTree or %NULL if you don't * used when removing the entry from the #GTree or %NULL if you don't
* want to supply such a function. * want to supply such a function
* @value_destroy_func: a function to free the memory allocated for the * @value_destroy_func: a function to free the memory allocated for the
* value used when removing the entry from the #GTree or %NULL if you * value used when removing the entry from the #GTree or %NULL if you
* don't want to supply such a function. * don't want to supply such a function
* *
* Creates a new #GTree like g_tree_new() and allows to specify functions * Creates a new #GTree like g_tree_new() and allows to specify functions
* to free the memory allocated for the key and value that get called when * to free the memory allocated for the key and value that get called when
* removing the entry from the #GTree. * removing the entry from the #GTree.
* *
* Return value: a new #GTree. * Return value: a newly allocated #GTree
**/ */
GTree* GTree *
g_tree_new_full (GCompareDataFunc key_compare_func, g_tree_new_full (GCompareDataFunc key_compare_func,
gpointer key_compare_data, gpointer key_compare_data,
GDestroyNotify key_destroy_func, GDestroyNotify key_destroy_func,
@ -302,15 +302,16 @@ g_tree_remove_all (GTree *tree)
/** /**
* g_tree_ref: * g_tree_ref:
* @tree: a #GTree. * @tree: a #GTree
* *
* Increments the reference count of @tree by one. It is safe to call * Increments the reference count of @tree by one.
* this function from any thread.
* *
* Return value: the passed in #GTree. * It is safe to call this function from any thread.
*
* Return value: the passed in #GTree
* *
* Since: 2.22 * Since: 2.22
**/ */
GTree * GTree *
g_tree_ref (GTree *tree) g_tree_ref (GTree *tree)
{ {
@ -323,17 +324,17 @@ g_tree_ref (GTree *tree)
/** /**
* g_tree_unref: * g_tree_unref:
* @tree: a #GTree. * @tree: a #GTree
* *
* Decrements the reference count of @tree by one. If the reference count * Decrements the reference count of @tree by one.
* drops to 0, all keys and values will be destroyed (if destroy * If the reference count drops to 0, all keys and values will
* functions were specified) and all memory allocated by @tree will be * be destroyed (if destroy functions were specified) and all
* released. * memory allocated by @tree will be released.
* *
* It is safe to call this function from any thread. * It is safe to call this function from any thread.
* *
* Since: 2.22 * Since: 2.22
**/ */
void void
g_tree_unref (GTree *tree) g_tree_unref (GTree *tree)
{ {
@ -348,7 +349,7 @@ g_tree_unref (GTree *tree)
/** /**
* g_tree_destroy: * g_tree_destroy:
* @tree: a #GTree. * @tree: a #GTree
* *
* Removes all keys and values from the #GTree and decreases its * Removes all keys and values from the #GTree and decreases its
* reference count by one. If keys and/or values are dynamically * reference count by one. If keys and/or values are dynamically
@ -356,7 +357,7 @@ g_tree_unref (GTree *tree)
* using g_tree_new_full(). In the latter case the destroy functions * using g_tree_new_full(). In the latter case the destroy functions
* you supplied will be called on all keys and values before destroying * you supplied will be called on all keys and values before destroying
* the #GTree. * the #GTree.
**/ */
void void
g_tree_destroy (GTree *tree) g_tree_destroy (GTree *tree)
{ {
@ -368,19 +369,21 @@ g_tree_destroy (GTree *tree)
/** /**
* g_tree_insert: * g_tree_insert:
* @tree: a #GTree. * @tree: a #GTree
* @key: the key to insert. * @key: the key to insert
* @value: the value corresponding to the key. * @value: the value corresponding to the key
* *
* Inserts a key/value pair into a #GTree. If the given key already exists * Inserts a key/value pair into a #GTree.
* in the #GTree its corresponding value is set to the new value. If you *
* supplied a value_destroy_func when creating the #GTree, the old value is * If the given key already exists in the #GTree its corresponding value
* freed using that function. If you supplied a @key_destroy_func when * is set to the new value. If you supplied a @value_destroy_func when
* creating the #GTree, the passed key is freed using that function. * creating the #GTree, the old value is freed using that function. If
* you supplied a @key_destroy_func when creating the #GTree, the passed
* key is freed using that function.
* *
* The tree is automatically 'balanced' as new key/value pairs are added, * 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. * so that the distance from the root to every leaf is as small as possible.
**/ */
void void
g_tree_insert (GTree *tree, g_tree_insert (GTree *tree,
gpointer key, gpointer key,
@ -397,9 +400,9 @@ g_tree_insert (GTree *tree,
/** /**
* g_tree_replace: * g_tree_replace:
* @tree: a #GTree. * @tree: a #GTree
* @key: the key to insert. * @key: the key to insert
* @value: the value corresponding to the key. * @value: the value corresponding to the key
* *
* Inserts a new key and value into a #GTree similar to g_tree_insert(). * Inserts a new key and value into a #GTree similar to g_tree_insert().
* The difference is that if the key already exists in the #GTree, it gets * The difference is that if the key already exists in the #GTree, it gets
@ -410,7 +413,7 @@ g_tree_insert (GTree *tree,
* *
* The tree is automatically 'balanced' as new key/value pairs are added, * 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. * so that the distance from the root to every leaf is as small as possible.
**/ */
void void
g_tree_replace (GTree *tree, g_tree_replace (GTree *tree,
gpointer key, gpointer key,
@ -522,9 +525,10 @@ g_tree_insert_internal (GTree *tree,
} }
} }
/* restore balance. This is the goodness of a non-recursive /* Restore balance. This is the goodness of a non-recursive
implementation, when we are done with balancing we 'break' * implementation, when we are done with balancing we 'break'
the loop and we are done. */ * the loop and we are done.
*/
while (1) while (1)
{ {
GTreeNode *bparent = path[--idx]; GTreeNode *bparent = path[--idx];
@ -556,8 +560,8 @@ g_tree_insert_internal (GTree *tree,
/** /**
* g_tree_remove: * g_tree_remove:
* @tree: a #GTree. * @tree: a #GTree
* @key: the key to remove. * @key: the key to remove
* *
* Removes a key/value pair from a #GTree. * Removes a key/value pair from a #GTree.
* *
@ -566,9 +570,9 @@ g_tree_insert_internal (GTree *tree,
* make sure that any dynamically allocated values are freed yourself. * make sure that any dynamically allocated values are freed yourself.
* If the key does not exist in the #GTree, the function does nothing. * If the key does not exist in the #GTree, the function does nothing.
* *
* Returns: %TRUE if the key was found (prior to 2.8, this function returned * Returns: %TRUE if the key was found (prior to 2.8, this function
* nothing) * returned nothing)
**/ */
gboolean gboolean
g_tree_remove (GTree *tree, g_tree_remove (GTree *tree,
gconstpointer key) gconstpointer key)
@ -588,17 +592,17 @@ g_tree_remove (GTree *tree,
/** /**
* g_tree_steal: * g_tree_steal:
* @tree: a #GTree. * @tree: a #GTree
* @key: the key to remove. * @key: the key to remove
* *
* Removes a key and its associated value from a #GTree without calling * Removes a key and its associated value from a #GTree without calling
* the key and value destroy functions. * the key and value destroy functions.
* *
* If the key does not exist in the #GTree, the function does nothing. * If the key does not exist in the #GTree, the function does nothing.
* *
* Returns: %TRUE if the key was found (prior to 2.8, this function returned * Returns: %TRUE if the key was found (prior to 2.8, this function
* nothing) * returned nothing)
**/ */
gboolean gboolean
g_tree_steal (GTree *tree, g_tree_steal (GTree *tree,
gconstpointer key) gconstpointer key)
@ -660,8 +664,9 @@ g_tree_remove_internal (GTree *tree,
} }
} }
/* the following code is almost equal to g_tree_remove_node, /* The following code is almost equal to g_tree_remove_node,
except that we do not have to call g_tree_node_parent. */ * except that we do not have to call g_tree_node_parent.
*/
balance = parent = path[--idx]; balance = parent = path[--idx];
g_assert (!parent || parent->left == node || parent->right == node); g_assert (!parent || parent->left == node || parent->right == node);
left_node = (parent && node == parent->left); left_node = (parent && node == parent->left);
@ -824,16 +829,16 @@ g_tree_remove_internal (GTree *tree,
/** /**
* g_tree_lookup: * g_tree_lookup:
* @tree: a #GTree. * @tree: a #GTree
* @key: the key to look up. * @key: the key to look up
* *
* Gets the value corresponding to the given key. Since a #GTree is * Gets the value corresponding to the given key. Since a #GTree is
* automatically balanced as key/value pairs are added, key lookup is very * automatically balanced as key/value pairs are added, key lookup
* fast. * is O(log n) (where n is the number of key/value pairs in the tree).
* *
* Return value: the value corresponding to the key, or %NULL if the key was * Return value: the value corresponding to the key, or %NULL
* not found. * if the key was not found.
**/ */
gpointer gpointer
g_tree_lookup (GTree *tree, g_tree_lookup (GTree *tree,
gconstpointer key) gconstpointer key)
@ -849,18 +854,18 @@ g_tree_lookup (GTree *tree,
/** /**
* g_tree_lookup_extended: * g_tree_lookup_extended:
* @tree: a #GTree. * @tree: a #GTree
* @lookup_key: the key to look up. * @lookup_key: the key to look up
* @orig_key: returns the original key. * @orig_key: returns the original key
* @value: returns the value associated with the key. * @value: returns the value associated with the key
* *
* Looks up a key in the #GTree, returning the original key and the * Looks up a key in the #GTree, returning the original key and the
* associated value and a #gboolean which is %TRUE if the key was found. This * associated value. This is useful if you need to free the memory
* is useful if you need to free the memory allocated for the original key, * allocated for the original key, for example before calling
* for example before calling g_tree_remove(). * g_tree_remove().
* *
* Return value: %TRUE if the key was found in the #GTree. * Return value: %TRUE if the key was found in the #GTree
**/ */
gboolean gboolean
g_tree_lookup_extended (GTree *tree, g_tree_lookup_extended (GTree *tree,
gconstpointer lookup_key, gconstpointer lookup_key,
@ -887,10 +892,10 @@ g_tree_lookup_extended (GTree *tree,
/** /**
* g_tree_foreach: * g_tree_foreach:
* @tree: a #GTree. * @tree: a #GTree
* @func: the function to call for each node visited. * @func: the function to call for each node visited.
* If this function returns %TRUE, the traversal is stopped. * If this function returns %TRUE, the traversal is stopped.
* @user_data: user data to pass to the function. * @user_data: user data to pass to the function
* *
* Calls the given function for each of the key/value pairs in the #GTree. * Calls the given function for each of the key/value pairs in the #GTree.
* The function is passed the key and value of each pair, and the given * The function is passed the key and value of each pair, and the given
@ -900,7 +905,7 @@ g_tree_lookup_extended (GTree *tree,
* add/remove items). To remove all items matching a predicate, you need * add/remove items). To remove all items matching a predicate, you need
* to add each item to a list in your #GTraverseFunc as you walk over * to add each item to a list in your #GTraverseFunc as you walk over
* the tree, then walk the list and remove each item. * the tree, then walk the list and remove each item.
**/ */
void void
g_tree_foreach (GTree *tree, g_tree_foreach (GTree *tree,
GTraverseFunc func, GTraverseFunc func,
@ -926,52 +931,34 @@ g_tree_foreach (GTree *tree,
/** /**
* g_tree_traverse: * g_tree_traverse:
* @tree: a #GTree. * @tree: a #GTree
* @traverse_func: the function to call for each node visited. If this * @traverse_func: the function to call for each node visited. If this
* function returns %TRUE, the traversal is stopped. * function returns %TRUE, the traversal is stopped.
* @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
* %G_PRE_ORDER and %G_POST_ORDER. * %G_PRE_ORDER and %G_POST_ORDER
* @user_data: user data to pass to the function. * @user_data: user data to pass to the function
* *
* Calls the given function for each node in the #GTree. * Calls the given function for each node in the #GTree.
* *
* Deprecated:2.2: The order of a balanced tree is somewhat arbitrary. If you * Deprecated:2.2: The order of a balanced tree is somewhat arbitrary.
* just want to visit all nodes in sorted order, use g_tree_foreach() * If you just want to visit all nodes in sorted order, use
* instead. If you really need to visit nodes in a different order, consider * g_tree_foreach() instead. If you really need to visit nodes in
* using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>. * a different order, consider using an
**/ * <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
*/
/** /**
* GTraverseFunc: * GTraverseFunc:
* @key: a key of a #GTree node. * @key: a key of a #GTree node
* @value: the value corresponding to the key. * @value: the value corresponding to the key
* @data: user data passed to g_tree_traverse(). * @data: user data passed to g_tree_traverse()
* *
* Specifies the type of function passed to g_tree_traverse(). It is * Specifies the type of function passed to g_tree_traverse(). It is
* passed the key and value of each node, together with the @user_data * passed the key and value of each node, together with the @user_data
* parameter passed to g_tree_traverse(). If the function returns * parameter passed to g_tree_traverse(). If the function returns
* %TRUE, the traversal is stopped. * %TRUE, the traversal is stopped.
* *
* Returns: %TRUE to stop the traversal. * Returns: %TRUE to stop the traversal
**/ */
/**
* GTraverseType:
* @G_IN_ORDER: 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.
* @G_PRE_ORDER: visits a node, then its children.
* @G_POST_ORDER: visits the node's children, then the node itself.
* @G_LEVEL_ORDER: 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.
*
* Specifies the type of traveral performed by g_tree_traverse(),
* g_node_traverse() and g_node_find().
**/
void void
g_tree_traverse (GTree *tree, g_tree_traverse (GTree *tree,
GTraverseFunc traverse_func, GTraverseFunc traverse_func,
@ -1019,8 +1006,8 @@ g_tree_traverse (GTree *tree,
* @search_func returns 1, searching will proceed among the key/value * @search_func returns 1, searching will proceed among the key/value
* pairs that have a larger key. * pairs that have a larger key.
* *
* Return value: the value corresponding to the found key, or %NULL if * Return value: the value corresponding to the found key, or %NULL
* the key was not found. * if the key was not found.
*/ */
gpointer gpointer
g_tree_search (GTree *tree, g_tree_search (GTree *tree,
@ -1037,7 +1024,7 @@ g_tree_search (GTree *tree,
/** /**
* g_tree_height: * g_tree_height:
* @tree: a #GTree. * @tree: a #GTree
* *
* Gets the height of a #GTree. * Gets the height of a #GTree.
* *
@ -1045,8 +1032,8 @@ g_tree_search (GTree *tree,
* If the #GTree contains only one root node the height is 1. * If the #GTree contains only one root node the height is 1.
* If the root node has children the height is 2, etc. * If the root node has children the height is 2, etc.
* *
* Return value: the height of the #GTree. * Return value: the height of @tree
**/ */
gint gint
g_tree_height (GTree *tree) g_tree_height (GTree *tree)
{ {
@ -1074,12 +1061,12 @@ g_tree_height (GTree *tree)
/** /**
* g_tree_nnodes: * g_tree_nnodes:
* @tree: a #GTree. * @tree: a #GTree
* *
* Gets the number of nodes in a #GTree. * Gets the number of nodes in a #GTree.
* *
* Return value: the number of nodes in the #GTree. * Return value: the number of nodes in @tree
**/ */
gint gint
g_tree_nnodes (GTree *tree) g_tree_nnodes (GTree *tree)
{ {
@ -1088,7 +1075,7 @@ g_tree_nnodes (GTree *tree)
return tree->nnodes; return tree->nnodes;
} }
static GTreeNode* static GTreeNode *
g_tree_node_balance (GTreeNode *node) g_tree_node_balance (GTreeNode *node)
{ {
if (node->balance < -1) if (node->balance < -1)
@ -1241,7 +1228,7 @@ g_tree_node_search (GTreeNode *node,
} }
} }
static GTreeNode* static GTreeNode *
g_tree_node_rotate_left (GTreeNode *node) g_tree_node_rotate_left (GTreeNode *node)
{ {
GTreeNode *right; GTreeNode *right;
@ -1282,7 +1269,7 @@ g_tree_node_rotate_left (GTreeNode *node)
return right; return right;
} }
static GTreeNode* static GTreeNode *
g_tree_node_rotate_right (GTreeNode *node) g_tree_node_rotate_right (GTreeNode *node)
{ {
GTreeNode *left; GTreeNode *left;