luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-10 04:45:48 +01:00
Code Issues Packages Projects Releases Wiki Activity

tag: documentation enhancement for novice application developers

Browse Source 
Adds some code examples how functions can be used. Adds a hint
to look at GQueue if access to the start and the end of the list
is required.

applying comments from Emmanuele Bassi and adds some more
improvements to clarify how functions should be used.

https://bugzilla.gnome.org/show_bug.cgi?id=683388
This commit is contained in:
Olivier Sessink 2012-09-05 09:52:23 +02:00 committed by Matthias Clasen
parent 84f3147f43
commit 86de6f0ebc
1 changed files with 113 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

162
glib/glist.c
View File

@ -51,6 +51,12 @@
* linkend="glib-Singly-Linked-Lists">Singly-Linked Lists</link> which * linkend="glib-Singly-Linked-Lists">Singly-Linked Lists</link> which
* only allows movement through the list in the forward direction). * only allows movement through the list in the forward direction).
* *
* The double linked list does not keep track of the number of items
* and does not keep track of both the start and end of the list. If
* you want fast access to both the start and the end of the list,
* and/or the number of items in the list, use <link
* linkend="glib-Double-ended-Queues.html">Double ended Queues</link>.
*
* The data contained in each element can be either integer values, by * The data contained in each element can be either integer values, by
* using one of the <link linkend="glib-Type-Conversion-Macros">Type * using one of the <link linkend="glib-Type-Conversion-Macros">Type
* Conversion Macros</link>, or simply pointers to any type of data. * Conversion Macros</link>, or simply pointers to any type of data.
@ -69,6 +75,30 @@
* To add elements, use g_list_append(), g_list_prepend(), * To add elements, use g_list_append(), g_list_prepend(),
* g_list_insert() and g_list_insert_sorted(). * g_list_insert() and g_list_insert_sorted().
* *
* To visit all elements in the list, use a loop over the list:
* |[
* GList *tmplist;
* for (tmplist = list; tmplist; tmplist = tmplist->next) {
* /&ast; do something with tmplist->data &ast;/
* }
* ]|
*
* To call a function for each element in the list use g_list_foreach().
*
* To loop over the list and modify it (e.g. remove a certain element)
* a while loop is more appropriate, for example:
* |[
* GList *tmplist = list;
* while (tmplist) {
* GList *nextlist = tmplist->next;
* if (specialcondition) {
* /&ast; possibly free tmplist->data &ast;/
* list = g_list_delete_link (list, tmplist);
* }
* tmplist = nextlist;
* }
* ]|
*
* To remove elements, use g_list_remove(). * To remove elements, use g_list_remove().
* *
* To find elements in the list use g_list_first(), g_list_last(), * To find elements in the list use g_list_first(), g_list_last(),
@ -78,8 +108,6 @@
* To find the index of an element use g_list_position() and * To find the index of an element use g_list_position() and
* g_list_index(). * g_list_index().
* *
* To call a function for each element in the list use g_list_foreach().
*
* To free the entire list, use g_list_free(). * To free the entire list, use g_list_free().
**/ **/
@ -196,15 +224,16 @@ g_list_free_full (GList *list,
* Adds a new element on to the end of the list. * Adds a new element on to the end of the list.
* *
* <note><para> * <note><para>
* The return value is the new start of the list, which * The return value is either @list, or the new start of the list if @list
* may have changed, so make sure you store the new value. * was %NULL; make sure you store the new value.
* </para></note> * </para></note>
* *
* <note><para> * <note><para>
* Note that g_list_append() has to traverse the entire list * Note that g_list_append() has to traverse the entire list
* to find the end, which is inefficient when adding multiple * to find the end, which is inefficient when adding multiple
* elements. A common idiom to avoid the inefficiency is to prepend * elements. A common idiom to avoid the inefficiency is to use
* the elements and reverse the list when all elements have been added. * g_list_prepend() and reverse the list with g_list_reverse()
* when all elements have been added.
* </para></note> * </para></note>
* *
* |[ * |[
@ -220,7 +249,7 @@ g_list_free_full (GList *list,
* number_list = g_list_append (number_list, GINT_TO_POINTER (14)); * number_list = g_list_append (number_list, GINT_TO_POINTER (14));
* ]| * ]|
* *
* Returns: the new start of the #GList * Returns: either @list or the new start of the #GList if @list was %NULL
*/ */
GList* GList*
g_list_append (GList *list, g_list_append (GList *list,
@ -251,14 +280,14 @@ g_list_append (GList *list,
/** /**
* g_list_prepend: * g_list_prepend:
* @list: a pointer to a #GList * @list: a pointer to a #GList, this must point to the top of the list
* @data: the data for the new element * @data: the data for the new element
* *
* Adds a new element on to the start of the list. * Prepends a new element on to the start of the list.
* *
* <note><para> * <note><para>
* The return value is the new start of the list, which * The return value is the new start of the list, which
* may have changed, so make sure you store the new value. * will have changed, so make sure you store the new value.
* </para></note> * </para></note>
* *
* |[ * |[
@ -268,7 +297,13 @@ g_list_append (GList *list,
* list = g_list_prepend (list, "first"); * list = g_list_prepend (list, "first");
* ]| * ]|
* *
* Returns: the new start of the #GList * <note><para>
* Do not use this function to prepend a new element to a different element
* than the start of the list. Use g_list_insert_before() instead.
* </para></note>
*
* Returns: a pointer to the newly prepended element, which is the new
* start of the #GList.
*/ */
GList* GList*
g_list_prepend (GList *list, g_list_prepend (GList *list,
@ -295,7 +330,7 @@ g_list_prepend (GList *list,
/** /**
* g_list_insert: * g_list_insert:
* @list: a pointer to a #GList * @list: a pointer to a #GList, this must point to the top of the list
* @data: the data for the new element * @data: the data for the new element
* @position: the position to insert the element. If this is * @position: the position to insert the element. If this is
* negative, or is larger than the number of elements in the * negative, or is larger than the number of elements in the
@ -303,7 +338,7 @@ g_list_prepend (GList *list,
* *
* Inserts a new element into the list at the given position. * Inserts a new element into the list at the given position.
* *
* Returns: the new start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList*
g_list_insert (GList *list, g_list_insert (GList *list,
@ -334,14 +369,14 @@ g_list_insert (GList *list,
/** /**
* g_list_insert_before: * g_list_insert_before:
* @list: a pointer to a #GList * @list: a pointer to a #GList, this must point to the top of the list
* @sibling: the list element before which the new element * @sibling: the list element before which the new element
* is inserted or %NULL to insert at the end of the list * is inserted or %NULL to insert at the end of the list
* @data: the data for the new element * @data: the data for the new element
* *
* Inserts a new element into the list before the given position. * Inserts a new element into the list before the given position.
* *
* Returns: the new start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList*
g_list_insert_before (GList *list, g_list_insert_before (GList *list,
@ -394,14 +429,22 @@ g_list_insert_before (GList *list,
/** /**
* g_list_concat: * g_list_concat:
* @list1: a #GList * @list1: a #GList, this must point to the top of the list
* @list2: the #GList to add to the end of the first #GList * @list2: the #GList to add to the end of the first #GList, this must point
* to the top of the list
* *
* Adds the second #GList onto the end of the first #GList. * Adds the second #GList onto the end of the first #GList.
* Note that the elements of the second #GList are not copied. * Note that the elements of the second #GList are not copied.
* They are used directly. * They are used directly.
* *
* Returns: the start of the new #GList * This function is for example used to move an element in the list.
* The following example moves an element to the top of the list:
* |[
* list = g_list_remove_link (list, llink);
* list = g_list_concat (llink, list);
* ]|
*
* Returns: the start of the new #GList, which equals @list1 if not %NULL
*/ */
GList * GList *
g_list_concat (GList *list1, GList *list2) g_list_concat (GList *list1, GList *list2)
@ -454,14 +497,14 @@ _g_list_remove_link (GList *list,
/** /**
* g_list_remove: * g_list_remove:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @data: the data of the element to remove * @data: the data of the element to remove
* *
* Removes an element from a #GList. * Removes an element from a #GList.
* If two elements contain the same data, only the first is removed. * If two elements contain the same data, only the first is removed.
* If none of the elements contain the data, the #GList is unchanged. * If none of the elements contain the data, the #GList is unchanged.
* *
* Returns: the new start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList*
g_list_remove (GList *list, g_list_remove (GList *list,
@ -487,7 +530,7 @@ g_list_remove (GList *list,
/** /**
* g_list_remove_all: * g_list_remove_all:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @data: data to remove * @data: data to remove
* *
* Removes all list nodes with data equal to @data. * Removes all list nodes with data equal to @data.
@ -495,7 +538,7 @@ g_list_remove (GList *list,
* g_list_remove() which removes only the first node * g_list_remove() which removes only the first node
* matching the given data. * matching the given data.
* *
* Returns: new head of @list * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList*
g_list_remove_all (GList *list, g_list_remove_all (GList *list,
@ -527,14 +570,23 @@ g_list_remove_all (GList *list,
/** /**
* g_list_remove_link: * g_list_remove_link:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @llink: an element in the #GList * @llink: an element in the #GList
* *
* Removes an element from a #GList, without freeing the element. * Removes an element from a #GList, without freeing the element.
* The removed element's prev and next links are set to %NULL, so * The removed element's prev and next links are set to %NULL, so
* that it becomes a self-contained list with one element. * that it becomes a self-contained list with one element.
* *
* Returns: the new start of the #GList, without the element * This function is for example used to move an element in the list (see the
* example at g_list_concat()) or to remove an element in the list before
* freeing its data:
* |[
* list = g_list_remove_link (list, llink);
* free_some_data_that_may_access_the_list_again (llink->data);
* g_list_free (llink);
* ]|
*
* Returns: the (possibly changed) start of the #GList
*/ */
GList* GList*
g_list_remove_link (GList *list, g_list_remove_link (GList *list,
@ -545,14 +597,14 @@ g_list_remove_link (GList *list,
/** /**
* g_list_delete_link: * g_list_delete_link:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @link_: node to delete from @list * @link_: node to delete from @list
* *
* Removes the node link_ from the list and frees it. * Removes the node link_ from the list and frees it.
* Compare this to g_list_remove_link() which removes the node * Compare this to g_list_remove_link() which removes the node
* without freeing it. * without freeing it.
* *
* Returns: the new head of @list * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList*
g_list_delete_link (GList *list, g_list_delete_link (GList *list,
@ -566,7 +618,7 @@ g_list_delete_link (GList *list,
/** /**
* g_list_copy: * g_list_copy:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* *
* Copies a #GList. * Copies a #GList.
* *
@ -577,7 +629,7 @@ g_list_delete_link (GList *list,
* to copy the data as well. * to copy the data as well.
* </para></note> * </para></note>
* *
* Returns: a copy of @list * Returns: the start of the new list that holds the same data as @list
*/ */
GList* GList*
g_list_copy (GList *list) g_list_copy (GList *list)
@ -587,7 +639,7 @@ g_list_copy (GList *list)
/** /**
* g_list_copy_deep: * g_list_copy_deep:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @func: a copy function used to copy every element in the list * @func: a copy function used to copy every element in the list
* @user_data: user data passed to the copy function @func, or #NULL * @user_data: user data passed to the copy function @func, or #NULL
* *
@ -610,7 +662,8 @@ g_list_copy (GList *list)
* g_list_free_full (another_list, g_object_unref); * g_list_free_full (another_list, g_object_unref);
* ]| * ]|
* *
* Returns: a full copy of @list, use #g_list_free_full to free it * Returns: the start of the new list that holds a full copy of @list,
* use #g_list_free_full to free it
* *
* Since: 2.34 * Since: 2.34
*/ */
@ -650,7 +703,7 @@ g_list_copy_deep (GList *list, GCopyFunc func, gpointer user_data)
/** /**
* g_list_reverse: * g_list_reverse:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* *
* Reverses a #GList. * Reverses a #GList.
* It simply switches the next and prev pointers of each element. * It simply switches the next and prev pointers of each element.
@ -676,7 +729,7 @@ g_list_reverse (GList *list)
/** /**
* g_list_nth: * g_list_nth:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @n: the position of the element, counting from 0 * @n: the position of the element, counting from 0
* *
* Gets the element at the given position in a #GList. * Gets the element at the given position in a #GList.
@ -716,7 +769,7 @@ g_list_nth_prev (GList *list,
/** /**
* g_list_nth_data: * g_list_nth_data:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @n: the position of the element * @n: the position of the element
* *
* Gets the data of the element at the given position. * Gets the data of the element at the given position.
@ -736,7 +789,7 @@ g_list_nth_data (GList *list,
/** /**
* g_list_find: * g_list_find:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @data: the element data to find * @data: the element data to find
* *
* Finds the element in a #GList which * Finds the element in a #GList which
@ -761,7 +814,7 @@ g_list_find (GList *list,
/** /**
* g_list_find_custom: * g_list_find_custom:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @data: user data passed to the function * @data: user data passed to the function
* @func: the function to call for each element. * @func: the function to call for each element.
* It should return 0 when the desired element is found * It should return 0 when the desired element is found
@ -795,7 +848,7 @@ g_list_find_custom (GList *list,
/** /**
* g_list_position: * g_list_position:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @llink: an element in the #GList * @llink: an element in the #GList
* *
* Gets the position of the given element * Gets the position of the given element
@ -824,7 +877,7 @@ g_list_position (GList *list,
/** /**
* g_list_index: * g_list_index:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @data: the data to find * @data: the data to find
* *
* Gets the position of the element containing * Gets the position of the element containing
@ -853,7 +906,7 @@ g_list_index (GList *list,
/** /**
* g_list_last: * g_list_last:
* @list: a #GList * @list: any #GList element
* *
* Gets the last element in a #GList. * Gets the last element in a #GList.
* *
@ -874,7 +927,7 @@ g_list_last (GList *list)
/** /**
* g_list_first: * g_list_first:
* @list: a #GList * @list: any #GList element
* *
* Gets the first element in a #GList. * Gets the first element in a #GList.
* *
@ -895,13 +948,15 @@ g_list_first (GList *list)
/** /**
* g_list_length: * g_list_length:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* *
* Gets the number of elements in a #GList. * Gets the number of elements in a #GList.
* *
* <note><para> * <note><para>
* This function iterates over the whole list to * This function iterates over the whole list to
* count its elements. * count its elements. Use <link
* linkend="glib-Double-ended-Queues.html">Double ended Queues</link> instead
* of a double linked list if you regularly need the number of items.
* </para></note> * </para></note>
* *
* Returns: the number of elements in the #GList * Returns: the number of elements in the #GList
@ -923,7 +978,7 @@ g_list_length (GList *list)
/** /**
* g_list_foreach: * g_list_foreach:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @func: the function to call with each element's data * @func: the function to call with each element's data
* @user_data: user data to pass to the function * @user_data: user data to pass to the function
* *
@ -1005,7 +1060,8 @@ g_list_insert_sorted_real (GList *list,
/** /**
* g_list_insert_sorted: * g_list_insert_sorted:
* @list: a pointer to a #GList * @list: a pointer to a #GList, this must point to the top of the already
* sorted list
* @data: the data for the new element * @data: the data for the new element
* @func: the function to compare elements in the list. It should * @func: the function to compare elements in the list. It should
* return a number > 0 if the first parameter comes after the * return a number > 0 if the first parameter comes after the
@ -1014,7 +1070,13 @@ g_list_insert_sorted_real (GList *list,
* Inserts a new element into the list, using the given comparison * Inserts a new element into the list, using the given comparison
* function to determine its position. * function to determine its position.
* *
* Returns: the new start of the #GList * <note><para>
* If you are adding many new elements to a list, and the number of new
* elements is much larger than the length of the list, use g_list_prepend()
* to add the new items and sort the list afterwards with g_list_sort()
* </para></note>
*
* Returns: the (possibly changed) start of the #GList
*/ */
GList* GList*
g_list_insert_sorted (GList *list, g_list_insert_sorted (GList *list,
@ -1026,7 +1088,7 @@ g_list_insert_sorted (GList *list,
/** /**
* g_list_insert_sorted_with_data: * g_list_insert_sorted_with_data:
* @list: a pointer to a #GList * @list: a pointer to a #GList, this must point to the top of the list
* @data: the data for the new element * @data: the data for the new element
* @func: the function to compare elements in the list. * @func: the function to compare elements in the list.
* It should return a number > 0 if the first parameter * It should return a number > 0 if the first parameter
@ -1036,7 +1098,7 @@ g_list_insert_sorted (GList *list,
* Inserts a new element into the list, using the given comparison * Inserts a new element into the list, using the given comparison
* function to determine its position. * function to determine its position.
* *
* Returns: the new start of the #GList * Returns: the (possibly changed) start of the #GList
* *
* Since: 2.10 * Since: 2.10
*/ */
@ -1117,7 +1179,7 @@ g_list_sort_real (GList *list,
/** /**
* g_list_sort: * g_list_sort:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @compare_func: the comparison function used to sort the #GList. * @compare_func: the comparison function used to sort the #GList.
* This function is passed the data from 2 elements of the #GList * This function is passed the data from 2 elements of the #GList
* and should return 0 if they are equal, a negative value if the * and should return 0 if they are equal, a negative value if the
@ -1127,7 +1189,7 @@ g_list_sort_real (GList *list,
* Sorts a #GList using the given comparison function. The algorithm * Sorts a #GList using the given comparison function. The algorithm
* used is a stable sort. * used is a stable sort.
* *
* Returns: the start of the sorted #GList * Returns: the (possibly changed) start of the #GList
*/ */
/** /**
* GCompareFunc: * GCompareFunc:
@ -1152,14 +1214,14 @@ g_list_sort (GList *list,
/** /**
* g_list_sort_with_data: * g_list_sort_with_data:
* @list: a #GList * @list: a #GList, this must point to the top of the list
* @compare_func: comparison function * @compare_func: comparison function
* @user_data: user data to pass to comparison function * @user_data: user data to pass to comparison function
* *
* Like g_list_sort(), but the comparison function accepts * Like g_list_sort(), but the comparison function accepts
* a user data argument. * a user data argument.
* *
* Returns: the new head of @list * Returns: the (possibly changed) start of the #GList
*/ */
/** /**
* GCompareDataFunc: * GCompareDataFunc: