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

GList: Some further documentation and formatting tweaks

Browse Source
This commit is contained in:
Matthias Clasen 2014-01-19 21:10:25 -05:00
parent 86de6f0ebc
commit a918519328
1 changed files with 233 additions and 222 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

247
glib/glist.c
View File

@ -47,15 +47,15 @@
* Each element in the list contains a piece of data, together with * Each element in the list contains a piece of data, together with
* pointers which link to the previous and next elements in the list. * pointers which link to the previous and next elements in the list.
* Using these pointers it is possible to move through the list in both * Using these pointers it is possible to move through the list in both
* directions (unlike the <link * directions (unlike the singly-linked <link
* linkend="glib-Singly-Linked-Lists">Singly-Linked Lists</link> which * linkend="glib-Singly-Linked-Lists">#GSList</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 * 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 * 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, * 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 * and/or the number of items in the list, use a
* linkend="glib-Double-ended-Queues.html">Double ended Queues</link>. * <link linkend="glib-Double-ended-Queues">GQueue</link> instead.
* *
* 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
@ -70,46 +70,52 @@
* elements return the new start of the list, which may have changed. * elements return the new start of the list, which may have changed.
* *
* There is no function to create a #GList. %NULL is considered to be * There is no function to create a #GList. %NULL is considered to be
* the empty list so you simply set a #GList* to %NULL. * a valid, empty list so you simply set a #GList* to %NULL to initialize
* it.
* *
* 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: * To visit all elements in the list, use a loop over the list:
* |[ * |[
* GList *tmplist; * GList *l;
* for (tmplist = list; tmplist; tmplist = tmplist->next) { * for (l = list; l != NULL; l = l->next)
* /&ast; do something with tmplist->data &ast;/ * {
* /&ast; do something with l->data &ast;/
* } * }
* ]| * ]|
* *
* To call a function for each element in the list use g_list_foreach(). * 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) * To loop over the list and modify it (e.g. remove a certain element)
* a while loop is more appropriate, for example: * a while loop is more appropriate, for example:
* |[ * |[
* GList *tmplist = list; * GList *l = list;
* while (tmplist) { * while (l != NULL)
* GList *nextlist = tmplist->next; * {
* if (specialcondition) { * GList *next = l->next;
* /&ast; possibly free tmplist->data &ast;/ * if (should_be_removed (l))
* list = g_list_delete_link (list, tmplist); * {
* /&ast; possibly free l->data &ast;/
* list = g_list_delete_link (list, l);
* } * }
* tmplist = nextlist; * l = next;
* } * }
* ]| * ]|
* *
* 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 navigate in a list, use g_list_first(), g_list_last(),
* g_list_next(), g_list_previous(), g_list_nth(), g_list_nth_data(), * g_list_next(), g_list_previous().
*
* To find elements in the list use g_list_nth(), g_list_nth_data(),
* g_list_find() and g_list_find_custom(). * g_list_find() and g_list_find_custom().
* *
* 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 free the entire list, use g_list_free(). * To free the entire list, use g_list_free() or g_list_free_full().
**/ */
/** /**
* GList: * GList:
@ -117,29 +123,33 @@
* of data, or any integer value using the <link * of data, or any integer value using the <link
* linkend="glib-Type-Conversion-Macros">Type Conversion * linkend="glib-Type-Conversion-Macros">Type Conversion
* Macros</link>. * Macros</link>.
* @next: contains the link to the next element in the list. * @next: contains the link to the next element in the list
* @prev: contains the link to the previous element in the list. * @prev: contains the link to the previous element in the list
* *
* The #GList struct is used for each element in a doubly-linked list. * The #GList struct is used for each element in a doubly-linked list.
**/ **/
/** /**
* g_list_previous: * g_list_previous:
* @list: an element in a #GList. * @list: an element in a #GList
* *
* A convenience macro to get the previous element in a #GList. * A convenience macro to get the previous element in a #GList.
* Note that it is considered perfectly acceptable to access
* @list->previous directly.
* *
* Returns: the previous element, or %NULL if there are no previous * Returns: the previous element, or %NULL if there are no previous
* elements. * elements
**/ **/
/** /**
* g_list_next: * g_list_next:
* @list: an element in a #GList. * @list: an element in a #GList
* *
* A convenience macro to get the next element in a #GList. * A convenience macro to get the next element in a #GList.
* Note that it is considered perfectly acceptable to access
* @list->next directly.
* *
* Returns: the next element, or %NULL if there are no more elements. * Returns: the next element, or %NULL if there are no more elements
**/ **/
#define _g_list_alloc() g_slice_new (GList) #define _g_list_alloc() g_slice_new (GList)
@ -153,9 +163,9 @@
* g_list_append(), g_list_prepend(), g_list_insert() and * g_list_append(), g_list_prepend(), g_list_insert() and
* g_list_insert_sorted() and so is rarely used on its own. * g_list_insert_sorted() and so is rarely used on its own.
* *
* Returns: a pointer to the newly-allocated #GList element. * Returns: a pointer to the newly-allocated #GList element
**/ **/
GList* GList *
g_list_alloc (void) g_list_alloc (void)
{ {
return _g_list_alloc0 (); return _g_list_alloc0 ();
@ -166,7 +176,7 @@ g_list_alloc (void)
* @list: a #GList * @list: a #GList
* *
* Frees all of the memory used by a #GList. * Frees all of the memory used by a #GList.
* The freed elements are returned to the slice allocator. * The freed elements are returned to the slice allocator
* *
* <note><para> * <note><para>
* If list elements contain dynamically-allocated memory, * If list elements contain dynamically-allocated memory,
@ -203,8 +213,8 @@ g_list_free_1 (GList *list)
* @list: a pointer to a #GList * @list: a pointer to a #GList
* @free_func: the function to be called to free each element's data * @free_func: the function to be called to free each element's data
* *
* Convenience method, which frees all the memory used by a #GList, and * Convenience method, which frees all the memory used by a #GList,
* calls the specified destroy function on every element's data. * and calls @free_func on every element's data.
* *
* Since: 2.28 * Since: 2.28
*/ */
@ -223,26 +233,21 @@ 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 that the return value is the new start of the list,
* The return value is either @list, or the new start of the list if @list * if @list was empty; make sure you store the new value.
* was %NULL; make sure you store the new value.
* </para></note>
* *
* <note><para> * g_list_append() has to traverse the entire list to find the end,
* Note that g_list_append() has to traverse the entire list * which is inefficient when adding multiple elements. A common idiom
* to find the end, which is inefficient when adding multiple * to avoid the inefficiency is to use g_list_prepend() and reverse
* elements. A common idiom to avoid the inefficiency is to use * the list with g_list_reverse() 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>
* *
* |[ * |[
* /&ast; Notice that these are initialized to the empty list. &ast;/ * /&ast; Notice that these are initialized to the empty list. &ast;/
* GList *list = NULL, *number_list = NULL; * GList *string_list = NULL, *number_list = NULL;
* *
* /&ast; This is a list of strings. &ast;/ * /&ast; This is a list of strings. &ast;/
* list = g_list_append (list, "first"); * string_list = g_list_append (string_list, "first");
* list = g_list_append (list, "second"); * string_list = g_list_append (string_list, "second");
* *
* /&ast; This is a list of integers. &ast;/ * /&ast; This is a list of integers. &ast;/
* number_list = g_list_append (number_list, GINT_TO_POINTER (27)); * number_list = g_list_append (number_list, GINT_TO_POINTER (27));
@ -251,7 +256,7 @@ g_list_free_full (GList *list,
* *
* Returns: either @list or the new start of the #GList if @list was %NULL * 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,
gpointer data) gpointer data)
{ {
@ -285,14 +290,13 @@ g_list_append (GList *list,
* *
* Prepends a new element on to the start of the list. * Prepends a new element on to the start of the list.
* *
* <note><para> * Note that the return value is the new start of the list,
* The return value is the new start of the list, which * which will have changed, so make sure you store the new value.
* will have changed, so make sure you store the new value.
* </para></note>
* *
* |[ * |[
* /&ast; Notice that it is initialized to the empty list. &ast;/ * /&ast; Notice that it is initialized to the empty list. &ast;/
* GList *list = NULL; * GList *list = NULL;
*
* list = g_list_prepend (list, "last"); * list = g_list_prepend (list, "last");
* list = g_list_prepend (list, "first"); * list = g_list_prepend (list, "first");
* ]| * ]|
@ -303,9 +307,9 @@ g_list_append (GList *list,
* </para></note> * </para></note>
* *
* Returns: a pointer to the newly prepended element, which is the new * Returns: a pointer to the newly prepended element, which is the new
* start of the #GList. * start of the #GList
*/ */
GList* GList *
g_list_prepend (GList *list, g_list_prepend (GList *list,
gpointer data) gpointer data)
{ {
@ -340,7 +344,7 @@ g_list_prepend (GList *list,
* *
* Returns: the (possibly changed) start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList *
g_list_insert (GList *list, g_list_insert (GList *list,
gpointer data, gpointer data,
gint position) gint position)
@ -378,7 +382,7 @@ g_list_insert (GList *list,
* *
* Returns: the (possibly changed) 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,
GList *sibling, GList *sibling,
gpointer data) gpointer data)
@ -430,8 +434,8 @@ g_list_insert_before (GList *list,
/** /**
* g_list_concat: * g_list_concat:
* @list1: a #GList, this must point to the top of the list * @list1: a #GList, this must point to the top of the list
* @list2: the #GList to add to the end of the first #GList, this must point * @list2: the #GList to add to the end of the first #GList,
* to the top of the list * 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.
@ -447,7 +451,8 @@ g_list_insert_before (GList *list,
* Returns: the start of the new #GList, which equals @list1 if not %NULL * 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)
{ {
GList *tmp_list; GList *tmp_list;
@ -464,7 +469,7 @@ g_list_concat (GList *list1, GList *list2)
return list1; return list1;
} }
static inline GList* static inline GList *
_g_list_remove_link (GList *list, _g_list_remove_link (GList *list,
GList *link) GList *link)
{ {
@ -506,7 +511,7 @@ _g_list_remove_link (GList *list,
* *
* Returns: the (possibly changed) start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList *
g_list_remove (GList *list, g_list_remove (GList *list,
gconstpointer data) gconstpointer data)
{ {
@ -540,7 +545,7 @@ g_list_remove (GList *list,
* *
* Returns: the (possibly changed) start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList *
g_list_remove_all (GList *list, g_list_remove_all (GList *list,
gconstpointer data) gconstpointer data)
{ {
@ -577,9 +582,9 @@ g_list_remove_all (GList *list,
* 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.
* *
* This function is for example used to move an element in the list (see the * This function is for example used to move an element in the list
* example at g_list_concat()) or to remove an element in the list before * (see the example for g_list_concat()) or to remove an element in
* freeing its data: * the list before freeing its data:
* |[ * |[
* list = g_list_remove_link (list, llink); * list = g_list_remove_link (list, llink);
* free_some_data_that_may_access_the_list_again (llink->data); * free_some_data_that_may_access_the_list_again (llink->data);
@ -588,7 +593,7 @@ g_list_remove_all (GList *list,
* *
* Returns: the (possibly changed) start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList *
g_list_remove_link (GList *list, g_list_remove_link (GList *list,
GList *llink) GList *llink)
{ {
@ -606,7 +611,7 @@ g_list_remove_link (GList *list,
* *
* Returns: the (possibly changed) start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList *
g_list_delete_link (GList *list, g_list_delete_link (GList *list,
GList *link_) GList *link_)
{ {
@ -631,7 +636,7 @@ g_list_delete_link (GList *list,
* *
* Returns: the start of the new list that holds the same data as @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)
{ {
return g_list_copy_deep (list, NULL, NULL); return g_list_copy_deep (list, NULL, NULL);
@ -641,16 +646,17 @@ g_list_copy (GList *list)
* g_list_copy_deep: * g_list_copy_deep:
* @list: a #GList, this must point to the top of the list * @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
* *
* Makes a full (deep) copy of a #GList. * Makes a full (deep) copy of a #GList.
* *
* In contrast with g_list_copy(), this function uses @func to make a copy of * In contrast with g_list_copy(), this function uses @func to make
* each list element, in addition to copying the list container itself. * a copy of each list element, in addition to copying the list
* container itself.
* *
* @func, as a #GCopyFunc, takes two arguments, the data to be copied and a user * @func, as a #GCopyFunc, takes two arguments, the data to be copied
* pointer. It's safe to pass #NULL as user_data, if the copy function takes only * and a @user_data pointer. It's safe to pass %NULL as user_data,
* one argument. * if the copy function takes only one argument.
* *
* For instance, if @list holds a list of GObjects, you can do: * For instance, if @list holds a list of GObjects, you can do:
* |[ * |[
@ -663,12 +669,14 @@ g_list_copy (GList *list)
* ]| * ]|
* *
* Returns: the start of the new list that holds a full copy of @list, * Returns: the start of the new list that holds a full copy of @list,
* use #g_list_free_full to free it * use g_list_free_full() to free it
* *
* Since: 2.34 * Since: 2.34
*/ */
GList* GList *
g_list_copy_deep (GList *list, GCopyFunc func, gpointer user_data) g_list_copy_deep (GList *list,
GCopyFunc func,
gpointer user_data)
{ {
GList *new_list = NULL; GList *new_list = NULL;
@ -710,7 +718,7 @@ g_list_copy_deep (GList *list, GCopyFunc func, gpointer user_data)
* *
* Returns: the start of the reversed #GList * Returns: the start of the reversed #GList
*/ */
GList* GList *
g_list_reverse (GList *list) g_list_reverse (GList *list)
{ {
GList *last; GList *last;
@ -737,7 +745,7 @@ g_list_reverse (GList *list)
* Returns: the element, or %NULL if the position is off * Returns: the element, or %NULL if the position is off
* the end of the #GList * the end of the #GList
*/ */
GList* GList *
g_list_nth (GList *list, g_list_nth (GList *list,
guint n) guint n)
{ {
@ -757,7 +765,7 @@ g_list_nth (GList *list,
* Returns: the element, or %NULL if the position is * Returns: the element, or %NULL if the position is
* off the end of the #GList * off the end of the #GList
*/ */
GList* GList *
g_list_nth_prev (GList *list, g_list_nth_prev (GList *list,
guint n) guint n)
{ {
@ -792,13 +800,11 @@ g_list_nth_data (GList *list,
* @list: a #GList, this must point to the top of the list * @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 contains the given data.
* contains the given data.
* *
* Returns: the found #GList element, * Returns: the found #GList element, or %NULL if it is not found
* or %NULL if it is not found
*/ */
GList* GList *
g_list_find (GList *list, g_list_find (GList *list,
gconstpointer data) gconstpointer data)
{ {
@ -828,7 +834,7 @@ g_list_find (GList *list,
* *
* Returns: the found #GList element, or %NULL if it is not found * Returns: the found #GList element, or %NULL if it is not found
*/ */
GList* GList *
g_list_find_custom (GList *list, g_list_find_custom (GList *list,
gconstpointer data, gconstpointer data,
GCompareFunc func) GCompareFunc func)
@ -845,7 +851,6 @@ g_list_find_custom (GList *list,
return NULL; return NULL;
} }
/** /**
* g_list_position: * g_list_position:
* @list: a #GList, this must point to the top of the list * @list: a #GList, this must point to the top of the list
@ -913,7 +918,7 @@ g_list_index (GList *list,
* Returns: the last element in the #GList, * Returns: the last element in the #GList,
* or %NULL if the #GList has no elements * or %NULL if the #GList has no elements
*/ */
GList* GList *
g_list_last (GList *list) g_list_last (GList *list)
{ {
if (list) if (list)
@ -934,7 +939,7 @@ g_list_last (GList *list)
* Returns: the first element in the #GList, * Returns: the first element in the #GList,
* or %NULL if the #GList has no elements * or %NULL if the #GList has no elements
*/ */
GList* GList *
g_list_first (GList *list) g_list_first (GList *list)
{ {
if (list) if (list)
@ -953,10 +958,9 @@ g_list_first (GList *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 * Use a <link linkend="glib-Double-ended-Queues">GQueue</link> instead
* linkend="glib-Double-ended-Queues.html">Double ended Queues</link> instead * of a GList if you regularly need the number of items.
* 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
@ -986,13 +990,12 @@ g_list_length (GList *list)
*/ */
/** /**
* GFunc: * GFunc:
* @data: the element's data. * @data: the element's data
* @user_data: user data passed to g_list_foreach() or * @user_data: user data passed to g_list_foreach() or g_slist_foreach()
* g_slist_foreach().
* *
* Specifies the type of functions passed to g_list_foreach() and * Specifies the type of functions passed to g_list_foreach() and
* g_slist_foreach(). * g_slist_foreach().
**/ */
void void
g_list_foreach (GList *list, g_list_foreach (GList *list,
GFunc func, GFunc func,
@ -1060,8 +1063,8 @@ g_list_insert_sorted_real (GList *list,
/** /**
* g_list_insert_sorted: * g_list_insert_sorted:
* @list: a pointer to a #GList, this must point to the top of the already * @list: a pointer to a #GList, this must point to the top of the
* sorted list * 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
@ -1071,14 +1074,15 @@ g_list_insert_sorted_real (GList *list,
* function to determine its position. * function to determine its position.
* *
* <note><para> * <note><para>
* If you are adding many new elements to a list, and the number of new * If you are adding many new elements to a list, and the number of
* elements is much larger than the length of the list, use g_list_prepend() * new elements is much larger than the length of the list, use
* to add the new items and sort the list afterwards with g_list_sort() * g_list_prepend() to add the new items and sort the list afterwards
* with g_list_sort()
* </para></note> * </para></note>
* *
* Returns: the (possibly changed) start of the #GList * Returns: the (possibly changed) start of the #GList
*/ */
GList* GList *
g_list_insert_sorted (GList *list, g_list_insert_sorted (GList *list,
gpointer data, gpointer data,
GCompareFunc func) GCompareFunc func)
@ -1088,21 +1092,29 @@ g_list_insert_sorted (GList *list,
/** /**
* g_list_insert_sorted_with_data: * g_list_insert_sorted_with_data:
* @list: a pointer to a #GList, this must point to the top of the list * @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. * @func: the function to compare elements in the list. It should
* It should return a number > 0 if the first parameter * return a number > 0 if the first parameter comes after the
* comes after the second parameter in the sort order. * second parameter in the sort order.
* @user_data: user data to pass to comparison function. * @user_data: user data to pass to comparison function
* *
* 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.
* *
* <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 * Returns: the (possibly changed) start of the #GList
* *
* Since: 2.10 * Since: 2.10
*/ */
GList* GList *
g_list_insert_sorted_with_data (GList *list, g_list_insert_sorted_with_data (GList *list,
gpointer data, gpointer data,
GCompareDataFunc func, GCompareDataFunc func,
@ -1147,7 +1159,7 @@ g_list_sort_merge (GList *l1,
return list.next; return list.next;
} }
static GList* static GList *
g_list_sort_real (GList *list, g_list_sort_real (GList *list,
GFunc compare_func, GFunc compare_func,
gpointer user_data) gpointer user_data)
@ -1193,8 +1205,8 @@ g_list_sort_real (GList *list,
*/ */
/** /**
* GCompareFunc: * GCompareFunc:
* @a: a value. * @a: a value
* @b: a value to compare with. * @b: a value to compare with
* *
* Specifies the type of a comparison function used to compare two * Specifies the type of a comparison function used to compare two
* values. The function should return a negative integer if the first * values. The function should return a negative integer if the first
@ -1202,14 +1214,13 @@ g_list_sort_real (GList *list,
* integer if the first value comes after the second. * integer if the first value comes after the second.
* *
* Returns: negative value if @a &lt; @b; zero if @a = @b; positive * Returns: negative value if @a &lt; @b; zero if @a = @b; positive
* value if @a > @b. * value if @a > @b
**/ */
GList * GList *
g_list_sort (GList *list, g_list_sort (GList *list,
GCompareFunc compare_func) GCompareFunc compare_func)
{ {
return g_list_sort_real (list, (GFunc) compare_func, NULL); return g_list_sort_real (list, (GFunc) compare_func, NULL);
} }
/** /**
@ -1225,9 +1236,9 @@ g_list_sort (GList *list,
*/ */
/** /**
* GCompareDataFunc: * GCompareDataFunc:
* @a: a value. * @a: a value
* @b: a value to compare with. * @b: a value to compare with
* @user_data: user data to pass to comparison function. * @user_data: user data
* *
* Specifies the type of a comparison function used to compare two * Specifies the type of a comparison function used to compare two
* values. The function should return a negative integer if the first * values. The function should return a negative integer if the first
@ -1235,8 +1246,8 @@ g_list_sort (GList *list,
* integer if the first value comes after the second. * integer if the first value comes after the second.
* *
* Returns: negative value if @a &lt; @b; zero if @a = @b; positive * Returns: negative value if @a &lt; @b; zero if @a = @b; positive
* value if @a > @b. * value if @a > @b
**/ */
GList * GList *
g_list_sort_with_data (GList *list, g_list_sort_with_data (GList *list,
GCompareDataFunc compare_func, GCompareDataFunc compare_func,