luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 03:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

GTree, GNode: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie 2010-01-31 00:27:28 -05:00
parent d81506a154
commit 4353151449
5 changed files with 185 additions and 751 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -20,4 +20,6 @@ shell.sgml
string_chunks.sgml
thread_pools.sgml
threads.sgml
trees-binary.sgml
trees-nary.sgml
timers.sgml

250
docs/reference/glib/tmpl/trees-binary.sgml
View File

@ -1,250 +0,0 @@
<!-- ##### SECTION Title ##### -->
Balanced Binary Trees
<!-- ##### SECTION Short_Description ##### -->
a sorted collection of key/value pairs optimized for searching
and traversing in order
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GTree structure and its associated functions provide a sorted collection
of key/value pairs optimized for searching and traversing in order.
</para>
<para>
To create a new #GTree use g_tree_new().
</para>
<para>
To insert a key/value pair into a #GTree use g_tree_insert().
</para>
<para>
To lookup the value corresponding to a given key, use g_tree_lookup() and
g_tree_lookup_extended().
</para>
<para>
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().
</para>
<para>
To traverse a #GTree, calling a function for each node visited in the
traversal, use g_tree_foreach().
</para>
<para>
To remove a key/value pair use g_tree_remove().
</para>
<para>
To destroy a #GTree, use g_tree_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GTree ##### -->
<para>
The <structname>GTree</structname> struct is an opaque data structure representing a
<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
It should be accessed only by using the following functions.
</para>
<!-- ##### FUNCTION g_tree_new ##### -->
<para>
</para>
@key_compare_func:
@Returns:
<!-- ##### FUNCTION g_tree_ref ##### -->
<para>
</para>
@tree:
@Returns:
<!-- ##### FUNCTION g_tree_unref ##### -->
<para>
</para>
@tree:
<!-- ##### FUNCTION g_tree_new_with_data ##### -->
<para>
</para>
@key_compare_func:
@key_compare_data:
@Returns:
<!-- ##### FUNCTION g_tree_new_full ##### -->
<para>
</para>
@key_compare_func:
@key_compare_data:
@key_destroy_func:
@value_destroy_func:
@Returns:
<!-- ##### FUNCTION g_tree_insert ##### -->
<para>
</para>
@tree:
@key:
@value:
<!-- ##### FUNCTION g_tree_replace ##### -->
<para>
</para>
@tree:
@key:
@value:
<!-- ##### FUNCTION g_tree_nnodes ##### -->
<para>
</para>
@tree:
@Returns:
<!-- ##### FUNCTION g_tree_height ##### -->
<para>
</para>
@tree:
@Returns:
<!-- ##### FUNCTION g_tree_lookup ##### -->
<para>
</para>
@tree:
@key:
@Returns:
<!-- ##### FUNCTION g_tree_lookup_extended ##### -->
@tree:
@lookup_key:
@orig_key:
@value:
@Returns:
<!-- ##### FUNCTION g_tree_foreach ##### -->
<para>
</para>
@tree:
@func:
@user_data:
<!-- ##### FUNCTION g_tree_traverse ##### -->
<para>
</para>
@tree:
@traverse_func:
@traverse_type:
@user_data:
<!-- ##### USER_FUNCTION GTraverseFunc ##### -->
<para>
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.
</para>
@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.
<!-- ##### ENUM GTraverseType ##### -->
<para>
Specifies the type of traveral performed by g_tree_traverse(),
g_node_traverse() and g_node_find().
</para>
@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.
<!-- ##### FUNCTION g_tree_search ##### -->
<para>
</para>
@tree:
@search_func:
@user_data:
@Returns:
<!-- ##### FUNCTION g_tree_remove ##### -->
<para>
</para>
@tree:
@key:
@Returns:
<!-- ##### FUNCTION g_tree_steal ##### -->
<para>
</para>
@tree:
@key:
@Returns:
<!-- ##### FUNCTION g_tree_destroy ##### -->
<para>
</para>
@tree:

501
docs/reference/glib/tmpl/trees-nary.sgml
View File

@ -1,501 +0,0 @@
<!-- ##### SECTION Title ##### -->
N-ary Trees
<!-- ##### SECTION Short_Description ##### -->
trees of data with any number of branches
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GNode 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 g_node_new().
</para>
<para>
To insert a node into a tree use g_node_insert(), g_node_insert_before(),
g_node_append() and g_node_prepend().
</para>
<para>
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().
</para>
<para>
To reverse the children of a node use g_node_reverse_children().
</para>
<para>
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().
</para>
<para>
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().
</para>
<para>
To traverse a tree, calling a function for each node visited in the
traversal, use g_node_traverse() or g_node_children_foreach().
</para>
<para>
To remove a node or subtree from a tree use g_node_unlink() or
g_node_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GNode ##### -->
<para>
The <structname>GNode</structname> struct represents one node in a
<link linkend="glib-N-ary-Trees">N-ary Tree</link>.
fields
</para>
@data: contains the actual data of the node.
@next: points to the node's next sibling (a sibling is another
<structname>GNode</structname> with the same parent).
@prev: points to the node's previous sibling.
@parent: points to the parent of the <structname>GNode</structname>,
or is %NULL if the <structname>GNode</structname> is the root of the tree.
@children: 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.
<!-- ##### FUNCTION g_node_new ##### -->
<para>
</para>
@data:
@Returns:
<!-- ##### FUNCTION g_node_copy ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### USER_FUNCTION GCopyFunc ##### -->
<para>
</para>
@src:
@data:
@Returns:
<!-- ##### FUNCTION g_node_copy_deep ##### -->
<para>
</para>
@node:
@copy_func:
@data:
@Returns:
<!-- ##### FUNCTION g_node_insert ##### -->
<para>
</para>
@parent:
@position:
@node:
@Returns:
<!-- ##### FUNCTION g_node_insert_before ##### -->
<para>
</para>
@parent:
@sibling:
@node:
@Returns:
<!-- ##### FUNCTION g_node_insert_after ##### -->
<para>
</para>
@parent:
@sibling:
@node:
@Returns:
<!-- ##### MACRO g_node_append ##### -->
<para>
</para>
@parent:
@node:
@Returns:
<!-- ##### FUNCTION g_node_prepend ##### -->
<para>
</para>
@parent:
@node:
@Returns:
<!-- ##### MACRO g_node_insert_data ##### -->
<para>
</para>
@parent:
@position:
@data:
@Returns:
<!-- ##### MACRO g_node_insert_data_before ##### -->
<para>
</para>
@parent:
@sibling:
@data:
@Returns:
<!-- ##### MACRO g_node_append_data ##### -->
<para>
</para>
@parent:
@data:
@Returns:
<!-- ##### MACRO g_node_prepend_data ##### -->
<para>
</para>
@parent:
@data:
@Returns:
<!-- ##### FUNCTION g_node_reverse_children ##### -->
<para>
</para>
@node:
<!-- ##### FUNCTION g_node_traverse ##### -->
<para>
</para>
@root:
@order:
@flags:
@max_depth:
@func:
@data:
<!-- ##### ENUM GTraverseFlags ##### -->
<para>
Specifies which nodes are visited during several of the tree functions,
including g_node_traverse() and g_node_find().
</para>
@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.
<!-- ##### USER_FUNCTION GNodeTraverseFunc ##### -->
<para>
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.
</para>
@node: a #GNode.
@data: user data passed to g_node_traverse().
@Returns: %TRUE to stop the traversal.
<!-- ##### FUNCTION g_node_children_foreach ##### -->
<para>
</para>
@node:
@flags:
@func:
@data:
<!-- ##### USER_FUNCTION GNodeForeachFunc ##### -->
<para>
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().
</para>
@node: a #GNode.
@data: user data passed to g_node_children_foreach().
<!-- ##### FUNCTION g_node_get_root ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### FUNCTION g_node_find ##### -->
<para>
</para>
@root:
@order:
@flags:
@data:
@Returns:
<!-- ##### FUNCTION g_node_find_child ##### -->
<para>
</para>
@node:
@flags:
@data:
@Returns:
<!-- ##### FUNCTION g_node_child_index ##### -->
<para>
</para>
@node:
@data:
@Returns:
<!-- ##### FUNCTION g_node_child_position ##### -->
<para>
</para>
@node:
@child:
@Returns:
<!-- ##### MACRO g_node_first_child ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### FUNCTION g_node_last_child ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### FUNCTION g_node_nth_child ##### -->
<para>
</para>
@node:
@n:
@Returns:
<!-- ##### FUNCTION g_node_first_sibling ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### MACRO g_node_next_sibling ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### MACRO g_node_prev_sibling ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### FUNCTION g_node_last_sibling ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### MACRO G_NODE_IS_LEAF ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### MACRO G_NODE_IS_ROOT ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### FUNCTION g_node_depth ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### FUNCTION g_node_n_nodes ##### -->
<para>
</para>
@root:
@flags:
@Returns:
<!-- ##### FUNCTION g_node_n_children ##### -->
<para>
</para>
@node:
@Returns:
<!-- ##### FUNCTION g_node_is_ancestor ##### -->
<para>
</para>
@node:
@descendant:
@Returns:
<!-- ##### FUNCTION g_node_max_height ##### -->
<para>
</para>
@root:
@Returns:
<!-- ##### FUNCTION g_node_unlink ##### -->
<para>
</para>
@node:
<!-- ##### FUNCTION g_node_destroy ##### -->
<para>
</para>
@root:
<!-- ##### FUNCTION g_node_push_allocator ##### -->
<para>
Sets the allocator to use to allocate #GNode elements.
Use g_node_pop_allocator() 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>
@dummy: the #GAllocator to use when allocating #GNode elements.
@Deprecated: 2.10: It does nothing, since #GNode has been converted
to the <link linkend="glib-Memory-Slices">slice allocator</link>
<!-- ##### FUNCTION g_node_pop_allocator ##### -->
<para>
Restores the previous #GAllocator, used when allocating #GNode elements.
</para>
<para>
Note that this function is not available if GLib has been compiled
with <option>--disable-mem-pools</option>
</para>
@Deprecated: 2.10: It does nothing, since #GNode has been converted
to the <link linkend="glib-Memory-Slices">slice allocator</link>

116
glib/gnode.c
View File

@ -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
* <link linkend="glib-N-ary-Trees">N-ary Tree</link>. 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 <option>--disable-mem-pools</option>
*
* Deprecated:2.10: It does nothing, since #GNode has been converted to
* the <link linkend="glib-Memory-Slices">slice
* allocator</link>
**/
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 <option>--disable-mem-pools</option>
*
* Deprecated:2.10: It does nothing, since #GNode has been converted to
* the <link linkend="glib-Memory-Slices">slice
* allocator</link>
**/
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,

67
glib/gtree.c
View File

@ -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 <structname>GTree</structname> struct is an opaque data
* structure representing a <link
* linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. 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 <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
**/
/**
* 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 <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
g_tree_traverse (GTree *tree,
GTraverseFunc traverse_func,