mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-07-23 02:17:51 +02:00
fixed a typo in a comment.
2001-05-04 Sven Neumann <sven@convergence.de> * ghash.c: fixed a typo in a comment. * gtree.[ch]: added new functions g_tree_new_full(), g_tree_replace(), g_tree_steal() and g_tree_foreach() to adapt GTree to the GHashTable API. Moved comments into the C file. * docs/reference/glib/glib-sections.txt * docs/reference/glib/tmpl/glib-unused.sgml * docs/reference/glib/tmpl/hash_tables.sgml * docs/reference/glib/tmpl/linked_lists_double.sgml * docs/reference/glib/tmpl/linked_lists_single.sgml * docs/reference/glib/tmpl/macros_misc.sgml * docs/reference/glib/tmpl/trees-binary.sgml: updated documentation
This commit is contained in:
Sven Neumann
committed by
Sven Neumann
Sven Neumann
parent
0402b625ee
commit
d18b364dd7
@@ -1214,6 +1214,7 @@ g_list_insert_sorted
|
||||
g_list_remove
|
||||
g_list_remove_link
|
||||
g_list_delete_link
|
||||
g_list_remove_all
|
||||
g_list_free
|
||||
|
||||
<SUBSECTION>
|
||||
@@ -1238,6 +1239,7 @@ g_list_previous
|
||||
g_list_next
|
||||
g_list_nth
|
||||
g_list_nth_data
|
||||
g_list_nth_prev
|
||||
|
||||
<SUBSECTION>
|
||||
g_list_find
|
||||
@@ -1265,6 +1267,7 @@ g_slist_insert_sorted
|
||||
g_slist_remove
|
||||
g_slist_remove_link
|
||||
g_slist_delete_link
|
||||
g_slist_remove_all
|
||||
g_slist_free
|
||||
g_slist_free_1
|
||||
|
||||
@@ -1330,16 +1333,20 @@ g_trash_stack_height
|
||||
<FILE>hash_tables</FILE>
|
||||
GHashTable
|
||||
g_hash_table_new
|
||||
g_hash_table_new_full
|
||||
GHashFunc
|
||||
GEqualFunc
|
||||
g_hash_table_insert
|
||||
g_hash_table_replace
|
||||
g_hash_table_size
|
||||
g_hash_table_lookup
|
||||
g_hash_table_lookup_extended
|
||||
g_hash_table_foreach
|
||||
GHFunc
|
||||
g_hash_table_remove
|
||||
g_hash_table_steal
|
||||
g_hash_table_foreach_remove
|
||||
g_hash_table_foreach_steal
|
||||
GHRFunc
|
||||
g_hash_table_freeze
|
||||
g_hash_table_thaw
|
||||
@@ -1462,15 +1469,21 @@ g_byte_array_free
|
||||
GTree
|
||||
g_tree_new
|
||||
g_tree_new_with_data
|
||||
g_tree_new_full
|
||||
GCompareDataFunc
|
||||
g_tree_insert
|
||||
g_tree_replace
|
||||
g_tree_nnodes
|
||||
g_tree_height
|
||||
g_tree_lookup
|
||||
g_tree_search
|
||||
g_tree_lookup_extended
|
||||
g_tree_foreach
|
||||
g_tree_traverse
|
||||
GTraverseFunc
|
||||
GTraverseType
|
||||
g_tree_search
|
||||
g_tree_remove
|
||||
g_tree_steal
|
||||
g_tree_destroy
|
||||
</SECTION>
|
||||
|
||||
|
||||
@@ -175,21 +175,6 @@ Turns the argument into a string literal by using the '#' stringizing operator.
|
||||
|
||||
@x: text to convert to a literal string.
|
||||
|
||||
<!-- ##### FUNCTION g_tree_lookup_extended ##### -->
|
||||
<para>
|
||||
Gets the original key and the associated value and a gboolean which is
|
||||
TRUE if the key was found. This is useful if you need to free the memory
|
||||
allocated for the original key, for example before calling g_tree_remove().
|
||||
Since a #GTree is automatically balanced as key/value pairs are added,
|
||||
key lookup is very fast.
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@lookup_key: the key to look up.
|
||||
@orig_key: returns the original key.
|
||||
@value: returns the value associated with the key.
|
||||
@Returns: TRUE if the key was found in the #GTree.
|
||||
|
||||
<!-- ##### MACRO getcwd ##### -->
|
||||
<para>
|
||||
|
||||
|
||||
@@ -69,6 +69,18 @@ It should only be accessed via the following functions.
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_hash_table_new_full ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@hash_func:
|
||||
@key_equal_func:
|
||||
@key_destroy_func:
|
||||
@value_destroy_func:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GHashFunc ##### -->
|
||||
<para>
|
||||
Specifies the type of the hash function which is passed to
|
||||
@@ -115,6 +127,16 @@ FALSE otherwise.
|
||||
@value:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_hash_table_replace ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@hash_table:
|
||||
@key:
|
||||
@value:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_hash_table_size ##### -->
|
||||
<para>
|
||||
|
||||
@@ -178,6 +200,16 @@ which is passed to g_hash_table_foreach().
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_hash_table_steal ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@hash_table:
|
||||
@key:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_hash_table_foreach_remove ##### -->
|
||||
<para>
|
||||
|
||||
@@ -189,6 +221,17 @@ which is passed to g_hash_table_foreach().
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_hash_table_foreach_steal ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@hash_table:
|
||||
@func:
|
||||
@user_data:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GHRFunc ##### -->
|
||||
<para>
|
||||
Specifies the type of the function passed to g_hash_table_foreach_remove().
|
||||
|
||||
@@ -189,6 +189,16 @@ Deletes the node @link from @list.
|
||||
@Returns: the new head of @list
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_list_remove_all ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list:
|
||||
@data:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_list_free ##### -->
|
||||
<para>
|
||||
Frees all of the memory used by a #GList.
|
||||
@@ -383,6 +393,16 @@ Gets the data of the element at the given position.
|
||||
#GList.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_list_nth_prev ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list:
|
||||
@n:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_list_find ##### -->
|
||||
<para>
|
||||
Finds the element in a #GList which contains the given data.
|
||||
|
||||
@@ -209,6 +209,16 @@ Deletes a node of @list. Returns the new list head.
|
||||
@Returns: new head of @list
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_remove_all ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@list:
|
||||
@data:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_free ##### -->
|
||||
<para>
|
||||
Frees all of the memory used by a #GSList.
|
||||
|
||||
@@ -66,7 +66,6 @@ only one statement is expected by the compiler.
|
||||
Portable way to copy <type>va_list</type> variables.
|
||||
</para>
|
||||
|
||||
<!-- # Unused Parameters # -->
|
||||
@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
|
||||
@ap2: a <type>va_list</type>.
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ 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_traverse().
|
||||
traversal, use g_tree_foreach().
|
||||
</para>
|
||||
<para>
|
||||
To remove a key/value pair use g_tree_remove().
|
||||
@@ -50,115 +50,123 @@ It should be accessed only by using the following functions.
|
||||
|
||||
<!-- ##### FUNCTION g_tree_new ##### -->
|
||||
<para>
|
||||
Creates a new #GTree.
|
||||
|
||||
</para>
|
||||
|
||||
@key_compare_func: the function used to order the nodes in the #GTree.
|
||||
It should return values similar to the standard <function>strcmp()</function>
|
||||
function -
|
||||
0 if the two arguments are equal, a negative value if the first argument comes
|
||||
before the second, or a positive value if the first argument comes after the
|
||||
second.
|
||||
@Returns: a new #GTree.
|
||||
@key_compare_func:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_new_with_data ##### -->
|
||||
<para>
|
||||
Creates a new #GTree with a comparison function that accepts user data.
|
||||
See g_tree_new() for more details.
|
||||
|
||||
</para>
|
||||
|
||||
@key_compare_func: qsort()-style comparison function
|
||||
@user_data: data to pass to comparison function
|
||||
@Returns: a new #GTree
|
||||
@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:
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GCompareDataFunc ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@a:
|
||||
@b:
|
||||
@user_data:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_insert ##### -->
|
||||
<para>
|
||||
Inserts a key/value pair into a #GTree.
|
||||
If the given key already exists in the #GTree it is set to the new value.
|
||||
(If you are using dynamically allocated keys and values you should be careful
|
||||
to ensure that the old values are freed.)
|
||||
</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>
|
||||
|
||||
@tree: a #GTree.
|
||||
@key: the key to insert.
|
||||
@value: the value corresponding to the key.
|
||||
@tree:
|
||||
@key:
|
||||
@value:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_replace ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree:
|
||||
@key:
|
||||
@value:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_nnodes ##### -->
|
||||
<para>
|
||||
Gets the number of nodes in a #GTree.
|
||||
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@Returns: the number of nodes in the #GTree.
|
||||
@tree:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_height ##### -->
|
||||
<para>
|
||||
Gets the height of a #GTree.
|
||||
</para>
|
||||
<para>
|
||||
If the #GTree contains no nodes, the height is 0.
|
||||
If the #GTree contains only one root node the height is 1.
|
||||
If the root node has children the height is 2, etc.
|
||||
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@Returns: the height of the #GTree.
|
||||
@tree:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_lookup ##### -->
|
||||
<para>
|
||||
Gets the value corresponding to the given key.
|
||||
Since a #GTree is automatically balanced as key/value pairs are
|
||||
added, key lookup is very fast.
|
||||
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@key: the key to look up.
|
||||
@Returns: the value corresponding to the key.
|
||||
@tree:
|
||||
@key:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_search ##### -->
|
||||
<!-- ##### FUNCTION g_tree_lookup_extended ##### -->
|
||||
|
||||
|
||||
@tree:
|
||||
@lookup_key:
|
||||
@orig_key:
|
||||
@value:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_foreach ##### -->
|
||||
<para>
|
||||
Searches a #GTree 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 @key_compare_func
|
||||
function passed to g_tree_new(), the function you pass to g_tree_search() 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 g_tree_traverse().
|
||||
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@search_func: the comparison function used to search the #GTree.
|
||||
@data: the data passed as the second argument to the @search_func function.
|
||||
@Returns: the value corresponding to the found key, or NULL if the key is
|
||||
not found.
|
||||
@tree:
|
||||
@func:
|
||||
@user_data:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_traverse ##### -->
|
||||
<para>
|
||||
Calls the given function for each node in the GTree.
|
||||
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@traverse_func: the function to call for each node visited. If this function
|
||||
returns TRUE, the traversal is stopped.
|
||||
@traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
|
||||
%G_PRE_ORDER and %G_POST_ORDER.
|
||||
@data: user data to pass to the traverse function.
|
||||
@tree:
|
||||
@traverse_func:
|
||||
@traverse_type:
|
||||
@user_data:
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GTraverseFunc ##### -->
|
||||
@@ -206,23 +214,42 @@ each child.
|
||||
@G_POST_ORDER:
|
||||
@G_LEVEL_ORDER:
|
||||
|
||||
<!-- ##### FUNCTION g_tree_remove ##### -->
|
||||
<!-- ##### FUNCTION g_tree_search ##### -->
|
||||
<para>
|
||||
Removes a key/value pair from a #GTree.
|
||||
If the key or value is dynamically allocated you must remember to free them
|
||||
yourself.
|
||||
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@key: the key to remove.
|
||||
@tree:
|
||||
@search_func:
|
||||
@user_data:
|
||||
@Returns:
|
||||
<!-- # Unused Parameters # -->
|
||||
@data:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_remove ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree:
|
||||
@key:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_steal ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree:
|
||||
@key:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_tree_destroy ##### -->
|
||||
<para>
|
||||
Destroys the #GTree, freeing all of the memory allocated.
|
||||
But it doesn't free keys or values.
|
||||
|
||||
</para>
|
||||
|
||||
@tree: a #GTree.
|
||||
@tree:
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user