From 4353151449fedf8e018c07ae4d196652a39f0528 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sun, 31 Jan 2010 00:27:28 -0500 Subject: [PATCH] GTree, GNode: move docs from tmpl to .c --- docs/reference/glib/tmpl/.gitignore | 2 + docs/reference/glib/tmpl/trees-binary.sgml | 250 ---------- docs/reference/glib/tmpl/trees-nary.sgml | 501 --------------------- glib/gnode.c | 116 +++++ glib/gtree.c | 67 +++ 5 files changed, 185 insertions(+), 751 deletions(-) delete mode 100644 docs/reference/glib/tmpl/trees-binary.sgml delete mode 100644 docs/reference/glib/tmpl/trees-nary.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 4aaebc064..b942d63fe 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -20,4 +20,6 @@ shell.sgml string_chunks.sgml thread_pools.sgml threads.sgml +trees-binary.sgml +trees-nary.sgml timers.sgml diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml deleted file mode 100644 index 6ef493219..000000000 --- a/docs/reference/glib/tmpl/trees-binary.sgml +++ /dev/null @@ -1,250 +0,0 @@ - -Balanced Binary Trees - - -a sorted collection of key/value pairs optimized for searching -and traversing in order - - - -The #GTree structure and its associated functions provide a sorted collection -of key/value pairs optimized for searching and traversing in order. - - -To create a new #GTree use g_tree_new(). - - -To insert a key/value pair into a #GTree use g_tree_insert(). - - -To lookup the value corresponding to a given key, use g_tree_lookup() and -g_tree_lookup_extended(). - - -To find out the number of nodes in a #GTree, use g_tree_nnodes(). -To get the height of a #GTree, use g_tree_height(). - - -To traverse a #GTree, calling a function for each node visited in the -traversal, use g_tree_foreach(). - - -To remove a key/value pair use g_tree_remove(). - - -To destroy a #GTree, use g_tree_destroy(). - - - - - - - - - - - - -The GTree struct is an opaque data structure representing a -Balanced Binary Tree. -It should be accessed only by using the following functions. - - - - - - - - -@key_compare_func: -@Returns: - - - - - - - -@tree: -@Returns: - - - - - - - -@tree: - - - - - - - -@key_compare_func: -@key_compare_data: -@Returns: - - - - - - - -@key_compare_func: -@key_compare_data: -@key_destroy_func: -@value_destroy_func: -@Returns: - - - - - - - -@tree: -@key: -@value: - - - - - - - -@tree: -@key: -@value: - - - - - - - -@tree: -@Returns: - - - - - - - -@tree: -@Returns: - - - - - - - -@tree: -@key: -@Returns: - - - - - -@tree: -@lookup_key: -@orig_key: -@value: -@Returns: - - - - - - - -@tree: -@func: -@user_data: - - - - - - - -@tree: -@traverse_func: -@traverse_type: -@user_data: - - - - -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 parameter passed to g_tree_traverse(). -If the function returns %TRUE, the traversal is stopped. - - -@key: a key of a #GTree node. -@value: the value corresponding to the key. -@data: user data passed to g_tree_traverse(). -@Returns: %TRUE to stop the traversal. - - - - -Specifies the type of traveral performed by g_tree_traverse(), -g_node_traverse() and g_node_find(). - - -@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 - Balanced Binary Trees. - For N-ary Trees, 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. - - - - - - -@tree: -@search_func: -@user_data: -@Returns: - - - - - - - -@tree: -@key: -@Returns: - - - - - - - -@tree: -@key: -@Returns: - - - - - - - -@tree: - - diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml deleted file mode 100644 index 0c570d08b..000000000 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ /dev/null @@ -1,501 +0,0 @@ - -N-ary Trees - - -trees of data with any number of branches - - - -The #GNode struct and its associated functions provide a N-ary tree data -structure, where nodes in the tree can contain arbitrary data. - - -To create a new tree use g_node_new(). - - -To insert a node into a tree use g_node_insert(), g_node_insert_before(), -g_node_append() and g_node_prepend(). - - -To create a new node and insert it into a tree use g_node_insert_data(), -g_node_insert_data_before(), g_node_append_data() and g_node_prepend_data(). - - -To reverse the children of a node use g_node_reverse_children(). - - -To find a node use g_node_get_root(), g_node_find(), g_node_find_child(), -g_node_child_index(), g_node_child_position(), -g_node_first_child(), g_node_last_child(), -g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(), -g_node_next_sibling() or g_node_last_sibling(). - - -To get information about a node or tree use G_NODE_IS_LEAF(), -G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(), -g_node_is_ancestor() or g_node_max_height(). - - -To traverse a tree, calling a function for each node visited in the -traversal, use g_node_traverse() or g_node_children_foreach(). - - -To remove a node or subtree from a tree use g_node_unlink() or -g_node_destroy(). - - - - - - - - - - - - -The GNode struct represents one node in a -N-ary Tree. -fields - - -@data: contains the actual data of the node. -@next: points to the node's next sibling (a sibling is another - GNode with the same parent). -@prev: points to the node's previous sibling. -@parent: points to the parent of the GNode, - or is %NULL if the GNode is the root of the tree. -@children: The children field points to the first - child of the GNode. The other children are accessed - by using the next pointer of each child. - - - - - - -@data: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@src: -@data: -@Returns: - - - - - - - -@node: -@copy_func: -@data: -@Returns: - - - - - - - -@parent: -@position: -@node: -@Returns: - - - - - - - -@parent: -@sibling: -@node: -@Returns: - - - - - - - -@parent: -@sibling: -@node: -@Returns: - - - - - - - -@parent: -@node: -@Returns: - - - - - - - -@parent: -@node: -@Returns: - - - - - - - -@parent: -@position: -@data: -@Returns: - - - - - - - -@parent: -@sibling: -@data: -@Returns: - - - - - - - -@parent: -@data: -@Returns: - - - - - - - -@parent: -@data: -@Returns: - - - - - - - -@node: - - - - - - - -@root: -@order: -@flags: -@max_depth: -@func: -@data: - - - - -Specifies which nodes are visited during several of the tree functions, -including g_node_traverse() and g_node_find(). - - -@G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has been - introduced in 2.6, for older version use %G_TRAVERSE_LEAFS. -@G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This name - has been introduced in 2.6, for older version use %G_TRAVERSE_NON_LEAFS. -@G_TRAVERSE_ALL: all nodes should be visited. -@G_TRAVERSE_MASK: a mask of all traverse flags. -@G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES. -@G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES. - - - -Specifies the type of function passed to g_node_traverse(). -The function is called with each of the nodes visited, together with the -user data passed to g_node_traverse(). -If the function returns %TRUE, then the traversal is stopped. - - -@node: a #GNode. -@data: user data passed to g_node_traverse(). -@Returns: %TRUE to stop the traversal. - - - - - - - -@node: -@flags: -@func: -@data: - - - - -Specifies the type of function passed to g_node_children_foreach(). -The function is called with each child node, together with the user data -passed to g_node_children_foreach(). - - -@node: a #GNode. -@data: user data passed to g_node_children_foreach(). - - - - - - - -@node: -@Returns: - - - - - - - -@root: -@order: -@flags: -@data: -@Returns: - - - - - - - -@node: -@flags: -@data: -@Returns: - - - - - - - -@node: -@data: -@Returns: - - - - - - - -@node: -@child: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@n: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@root: -@flags: -@Returns: - - - - - - - -@node: -@Returns: - - - - - - - -@node: -@descendant: -@Returns: - - - - - - - -@root: -@Returns: - - - - - - - -@node: - - - - - - - -@root: - - - - -Sets the allocator to use to allocate #GNode elements. -Use g_node_pop_allocator() to restore the previous allocator. - - -Note that this function is not available if GLib has been compiled -with - - -@dummy: the #GAllocator to use when allocating #GNode elements. -@Deprecated: 2.10: It does nothing, since #GNode has been converted - to the slice allocator - - - - -Restores the previous #GAllocator, used when allocating #GNode elements. - - -Note that this function is not available if GLib has been compiled -with - - -@Deprecated: 2.10: It does nothing, since #GNode has been converted - to the slice allocator - - diff --git a/glib/gnode.c b/glib/gnode.c index 142eadeed..7d3dfceb6 100644 --- a/glib/gnode.c +++ b/glib/gnode.c @@ -36,7 +36,87 @@ #include "glib.h" #include "galias.h" +/** + * SECTION: trees-nary + * @title: N-ary Trees + * @short_description: trees of data with any number of branches + * + * The #GNode struct and its associated functions provide a N-ary tree + * data structure, where nodes in the tree can contain arbitrary data. + * + * To create a new tree use g_node_new(). + * + * To insert a node into a tree use g_node_insert(), + * g_node_insert_before(), g_node_append() and g_node_prepend(). + * + * To create a new node and insert it into a tree use + * g_node_insert_data(), g_node_insert_data_before(), + * g_node_append_data() and g_node_prepend_data(). + * + * To reverse the children of a node use g_node_reverse_children(). + * + * To find a node use g_node_get_root(), g_node_find(), + * g_node_find_child(), g_node_child_index(), g_node_child_position(), + * g_node_first_child(), g_node_last_child(), g_node_nth_child(), + * g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() + * or g_node_last_sibling(). + * + * To get information about a node or tree use G_NODE_IS_LEAF(), + * G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), + * g_node_n_children(), g_node_is_ancestor() or g_node_max_height(). + * + * To traverse a tree, calling a function for each node visited in the + * traversal, use g_node_traverse() or g_node_children_foreach(). + * + * To remove a node or subtree from a tree use g_node_unlink() or + * g_node_destroy(). + **/ + +/** + * GNode: + * @data: contains the actual data of the node. + * @next: points to the node's next sibling (a sibling is another + * #GNode with the same parent). + * @prev: points to the node's previous sibling. + * @parent: points to the parent of the #GNode, or is %NULL if the + * #GNode is the root of the tree. + * @children: points to the first child of the #GNode. The other + * children are accessed by using the @next pointer of each + * child. + * + * The #GNode struct represents one node in a + * N-ary Tree. fields + **/ + +/** + * g_node_push_allocator: + * @dummy: the #GAllocator to use when allocating #GNode elements. + * + * Sets the allocator to use to allocate #GNode elements. Use + * g_node_pop_allocator() to restore the previous allocator. + * + * Note that this function is not available if GLib has been compiled + * with + * + * Deprecated:2.10: It does nothing, since #GNode has been converted to + * the slice + * allocator + **/ void g_node_push_allocator (gpointer dummy) { /* present for binary compat only */ } + +/** + * g_node_pop_allocator: + * + * Restores the previous #GAllocator, used when allocating #GNode + * elements. + * + * Note that this function is not available if GLib has been compiled + * with + * + * Deprecated:2.10: It does nothing, since #GNode has been converted to + * the slice + * allocator + **/ void g_node_pop_allocator (void) { /* present for binary compat only */ } #define g_node_alloc0() g_slice_new0 (GNode) @@ -767,6 +847,33 @@ g_node_depth_traverse_level (GNode *node, * It calls the given function for each node visited. * The traversal can be halted at any point by returning %TRUE from @func. */ +/** + * GTraverseFlags: + * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has + * been introduced in 2.6, for older version use + * %G_TRAVERSE_LEAFS. + * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This + * name has been introduced in 2.6, for older + * version use %G_TRAVERSE_NON_LEAFS. + * @G_TRAVERSE_ALL: all nodes should be visited. + * @G_TRAVERSE_MASK: a mask of all traverse flags. + * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES. + * @G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES. + * + * Specifies which nodes are visited during several of the tree + * functions, including g_node_traverse() and g_node_find(). + **/ +/** + * GNodeTraverseFunc: + * @node: a #GNode. + * @data: user data passed to g_node_traverse(). + * @Returns: %TRUE to stop the traversal. + * + * Specifies the type of function passed to g_node_traverse(). The + * function is called with each of the nodes visited, together with the + * user data passed to g_node_traverse(). If the function returns + * %TRUE, then the traversal is stopped. + **/ void g_node_traverse (GNode *root, GTraverseType order, @@ -1131,6 +1238,15 @@ g_node_last_sibling (GNode *node) * Calls a function for each of the children of a #GNode. * Note that it doesn't descend beneath the child nodes. */ +/** + * GNodeForeachFunc: + * @node: a #GNode. + * @data: user data passed to g_node_children_foreach(). + * + * Specifies the type of function passed to g_node_children_foreach(). + * The function is called with each child node, together with the user + * data passed to g_node_children_foreach(). + **/ void g_node_children_foreach (GNode *node, GTraverseFlags flags, diff --git a/glib/gtree.c b/glib/gtree.c index fd984ee41..17bfb824f 100644 --- a/glib/gtree.c +++ b/glib/gtree.c @@ -33,12 +33,48 @@ #include "glib.h" #include "galias.h" +/** + * SECTION: trees-binary + * @title: Balanced Binary Trees + * @short_description: a sorted collection of key/value pairs optimized + * for searching and traversing in order + * + * The #GTree structure and its associated functions provide a sorted + * collection of key/value pairs optimized for searching and traversing + * in order. + * + * To create a new #GTree use g_tree_new(). + * + * To insert a key/value pair into a #GTree use g_tree_insert(). + * + * To lookup the value corresponding to a given key, use + * g_tree_lookup() and g_tree_lookup_extended(). + * + * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To + * get the height of a #GTree, use g_tree_height(). + * + * To traverse a #GTree, calling a function for each node visited in + * the traversal, use g_tree_foreach(). + * + * To remove a key/value pair use g_tree_remove(). + * + * To destroy a #GTree, use g_tree_destroy(). + **/ + #undef G_TREE_DEBUG #define MAX_GTREE_HEIGHT 40 typedef struct _GTreeNode GTreeNode; +/** + * GTree: + * + * The GTree struct is an opaque data + * structure representing a Balanced Binary Tree. It + * should be accessed only by using the following functions. + **/ struct _GTree { GTreeNode *root; @@ -901,6 +937,37 @@ g_tree_foreach (GTree *tree, * instead. If you really need to visit nodes in a different order, consider * using an N-ary Tree. **/ +/** + * GTraverseFunc: + * @key: a key of a #GTree node. + * @value: the value corresponding to the key. + * @data: user data passed to g_tree_traverse(). + * @Returns: %TRUE to stop the traversal. + * + * 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 + * parameter passed to g_tree_traverse(). If the function returns + * %TRUE, the traversal is stopped. + **/ +/** + * 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 Balanced Binary + * Trees. For N-ary Trees, 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 g_tree_traverse (GTree *tree, GTraverseFunc traverse_func,