From: Matthias Clasen Date: Fri, 29 Feb 2008 21:16:21 +0000 (+0000) Subject: Move docs inline X-Git-Tag: GLIB_2_16_0~53 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=66c0f542218b566b3b5fc965fc94b1b176cbad17;p=platform%2Fupstream%2Fglib.git Move docs inline svn path=/trunk/; revision=6607 --- diff --git a/ChangeLog b/ChangeLog index 0ee7d3e..e3e9e71 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2008-02-29 Matthias Clasen + + * glib/gslist.c: + * glib/glist.c: Move docs inline, and improve the + g_[s]list_delete_link docs. (#519352, Owen Taylor) + 2008-02-29 Tor Lillqvist * glib/win_iconv.c (name_to_codepage): Add some GNU libiconv diff --git a/glib/glist.c b/glib/glist.c index 40f1dd6..a7d60df 100644 --- a/glib/glist.c +++ b/glib/glist.c @@ -47,18 +47,71 @@ g_list_alloc (void) return _g_list_alloc0 (); } +/** + * g_list_free: + * @list: a #GList + * + * Frees all of the memory used by a #GList. + * The freed elements are returned to the slice allocator. + * + * + * If list elements contain dynamically-allocated memory, + * they should be freed first. + * + */ void g_list_free (GList *list) { g_slice_free_chain (GList, list, next); } +/** + * g_list_free_1: + * @list: a #GList element + * + * Frees one #GList element. + * It is usually used after g_list_remove_link(). + */ void g_list_free_1 (GList *list) { _g_list_free1 (list); } +/** + * g_list_append: + * @list: a pointer to a #GList + * @data: the data for the new element + * + * Adds a new element on to the end of the list. + * + * + * The return value is the new start of the list, which + * may have changed, so make sure you store the new value. + * + * + * + * Note that g_list_append() has to traverse the entire list + * to find the end, which is inefficient when adding multiple + * elements. A common idiom to avoid the inefficiency is to prepend + * the elements and reverse the list when all elements have been added. + * + * + * |[ + * /* Notice that these are initialized to the empty list. */ + * GList *list = NULL, *number_list = NULL; + * + * /* This is a list of strings. */ + * list = g_list_append (list, "first"); + * list = g_list_append (list, "second"); + * + * /* This is a list of integers. */ + * number_list = g_list_append (number_list, GINT_TO_POINTER (27)); + * number_list = g_list_append (number_list, GINT_TO_POINTER (14)); + * ]| + * + * Returns: the new start of the #GList + */ GList* g_list_append (GList *list, gpointer data) @@ -86,6 +139,27 @@ g_list_append (GList *list, } } +/** + * g_list_prepend: + * @list: a pointer to a #GList + * @data: the data for the new element + * + * Adds a new element on to the start of the list. + * + * + * The return value is the new start of the list, which + * may have changed, so make sure you store the new value. + * + * + * |[ + * /* Notice that it is initialized to the empty list. */ + * GList *list = NULL; + * list = g_list_prepend (list, "last"); + * list = g_list_prepend (list, "first"); + * ]| + * + * Returns: the new start of the #GList + */ GList* g_list_prepend (GList *list, gpointer data) @@ -109,6 +183,18 @@ g_list_prepend (GList *list, return new_list; } +/** + * g_list_insert: + * @list: a pointer to a #GList + * @data: the data for the new element + * @position: the position to insert the element. If this is + * negative, or is larger than the number of elements in the + * list, the new element is added on to the end of the list. + * + * Inserts a new element into the list at the given position. + * + * Returns: the new start of the #GList + */ GList* g_list_insert (GList *list, gpointer data, @@ -140,6 +226,17 @@ g_list_insert (GList *list, return list; } +/** + * g_list_insert_before: + * @list: a pointer to a #GList + * @sibling: the list element before which the new element + * is inserted or %NULL to insert at the end of the list + * @data: the data for the new element + * + * Inserts a new element into the list before the given position. + * + * Returns: the new start of the #GList + */ GList* g_list_insert_before (GList *list, GList *sibling, @@ -189,6 +286,17 @@ g_list_insert_before (GList *list, } } +/** + * g_list_concat: + * @list1: a #GList + * @list2: the #GList to add to 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. + * They are used directly. + * + * Returns: the start of the new #GList + */ GList * g_list_concat (GList *list1, GList *list2) { @@ -207,6 +315,17 @@ g_list_concat (GList *list1, GList *list2) return list1; } +/** + * g_list_remove: + * @list: a #GList + * @data: the data of the element to remove + * + * Removes an element from a #GList. + * If two elements contain the same data, only the first is removed. + * If none of the elements contain the data, the #GList is unchanged. + * + * Return: the new start of the #GList + */ GList* g_list_remove (GList *list, gconstpointer data) @@ -236,6 +355,18 @@ g_list_remove (GList *list, return list; } +/** + * g_list_remove_all: + * @list: a #GList + * @data: data to remove + * + * Removes all list nodes with data equal to @data. + * Returns the new head of the list. Contrast with + * g_list_remove() which removes only the first node + * matching the given data. + * + * Returns: new head of @list + */ GList* g_list_remove_all (GList *list, gconstpointer data) @@ -285,23 +416,59 @@ _g_list_remove_link (GList *list, return list; } +/** + * g_list_remove_link: + * @list: a #GList + * @llink: an element in the #GList + * + * Removes an element from a #GList, without freeing the element. + * The removed element's prev and next links are set to %NULL, so + * that it becomes a self-contained list with one element. + * + * Returns: the new start of the #GList, without the element + */ GList* g_list_remove_link (GList *list, - GList *link) + GList *llink) { - return _g_list_remove_link (list, link); + return _g_list_remove_link (list, llink); } +/** + * g_list_delete_link: + * @list: a #GList + * @link_: node to delete from @list + * + * Removes the node link_ from the list and frees it. + * Compare this to g_list_remove_link() which removes the node + * without freeing it. + * + * Returns: the new head of @list + */ GList* g_list_delete_link (GList *list, - GList *link) + GList *link_) { - list = _g_list_remove_link (list, link); - _g_list_free1 (link); + list = _g_list_remove_link (list, link_); + _g_list_free1 (link_); return list; } +/** + * g_list_copy: + * @list: a #GList + * + * Copies a #GList. + * + * + * Note that this is a "shallow" copy. If the list elements + * consist of pointers to data, the pointers are copied but + * the actual data is not. + * + * + * Returns: a copy of @list + */ GList* g_list_copy (GList *list) { @@ -330,6 +497,15 @@ g_list_copy (GList *list) return new_list; } +/** + * g_list_reverse: + * @list: a #GList + * + * Reverses a #GList. + * It simply switches the next and prev pointers of each element. + * + * Returns: the start of the reversed #GList + */ GList* g_list_reverse (GList *list) { @@ -347,6 +523,16 @@ g_list_reverse (GList *list) return last; } +/** + * g_list_nth: + * @list: a #GList + * @n: the position of the element, counting from 0 + * + * Gets the element at the given position in a #GList. + * + * Returns: the element, or %NULL if the position is off + * the end of the #GList + */ GList* g_list_nth (GList *list, guint n) @@ -357,6 +543,16 @@ g_list_nth (GList *list, return list; } +/** + * g_list_nth_prev: + * @list: a #GList + * @n: the position of the element, counting from 0 + * + * Gets the element @n places before @list. + * + * Returns: the element, or %NULL if the position is + * off the end of the #GList + */ GList* g_list_nth_prev (GList *list, guint n) @@ -367,6 +563,16 @@ g_list_nth_prev (GList *list, return list; } +/** + * g_list_nth_data: + * @list: a #GList + * @n: the position of the element + * + * Gets the data of the element at the given position. + * + * Returns: the element's data, or %NULL if the position + * is off the end of the #GList + */ gpointer g_list_nth_data (GList *list, guint n) @@ -377,6 +583,17 @@ g_list_nth_data (GList *list, return list ? list->data : NULL; } +/** + * g_list_find: + * @list: a #GList + * @data: the element data to find + * + * Finds the element in a #GList which + * contains the given data. + * + * Returns: the found #GList element, + * or %NULL if it is not found + */ GList* g_list_find (GList *list, gconstpointer data) @@ -391,6 +608,22 @@ g_list_find (GList *list, return list; } +/** + * g_list_find_custom: + * @list: a #GList + * @data: user data passed to the function + * @func: the function to call for each element. + * It should return 0 when the desired element is found + * + * Finds an element in a #GList, using a supplied function to + * find the desired element. It iterates over the list, calling + * the given function which should return 0 when the desired + * element is found. The function takes two #gconstpointer arguments, + * the #GList element's data as the first argument and the + * given user data. + * + * Returns: the found #GList element, or %NULL if it is not found + */ GList* g_list_find_custom (GList *list, gconstpointer data, @@ -409,16 +642,27 @@ g_list_find_custom (GList *list, } +/** + * g_list_position: + * @list: a #GList + * @llink: an element in the #GList + * + * Gets the position of the given element + * in the #GList (starting from 0). + * + * Returns: the position of the element in the #GList, + * or -1 if the element is not found + */ gint g_list_position (GList *list, - GList *link) + GList *llink) { gint i; i = 0; while (list) { - if (list == link) + if (list == llink) return i; i++; list = list->next; @@ -427,6 +671,17 @@ g_list_position (GList *list, return -1; } +/** + * g_list_index: + * @list: a #GList + * @data: the data to find + * + * Gets the position of the element containing + * the given data (starting from 0). + * + * Returns: the index of the element containing the data, + * or -1 if the data is not found + */ gint g_list_index (GList *list, gconstpointer data) @@ -445,6 +700,15 @@ g_list_index (GList *list, return -1; } +/** + * g_list_last: + * @list: a #GList + * + * Gets the last element in a #GList. + * + * Returns: the last element in the #GList, + * or %NULL if the #GList has no elements + */ GList* g_list_last (GList *list) { @@ -457,6 +721,15 @@ g_list_last (GList *list) return list; } +/** + * g_list_first: + * @list: a #GList + * + * Gets the first element in a #GList. + * + * Returns: the last element in the #GList, + * or %NULL if the #GList has no elements + */ GList* g_list_first (GList *list) { @@ -469,6 +742,19 @@ g_list_first (GList *list) return list; } +/** + * g_list_length: + * @list: a #GList + * + * Gets the number of elements in a #GList. + * + * + * This function iterates over the whole list to + * count its elements. + * + * + * Returns: the number of elements in the #GList + */ guint g_list_length (GList *list) { @@ -484,6 +770,14 @@ g_list_length (GList *list) return length; } +/** + * g_list_foreach: + * @list: a #GList + * @func: the function to call with each element's data + * @user_data: user data to pass to the function + * + * Calls a function for each element of a #GList. + */ void g_list_foreach (GList *list, GFunc func, @@ -549,6 +843,19 @@ g_list_insert_sorted_real (GList *list, return list; } +/** + * g_list_insert_sorted: + * @list: a pointer to a #GList + * @data: the data for the new element + * @func: the function to compare elements in the list. It should + * return a number > 0 if the first parameter comes after the + * second parameter in the sort order. + * + * Inserts a new element into the list, using the given comparison + * function to determine its position. + * + * Returns: the new start of the #GList + */ GList* g_list_insert_sorted (GList *list, gpointer data, @@ -557,6 +864,22 @@ g_list_insert_sorted (GList *list, return g_list_insert_sorted_real (list, data, (GFunc) func, NULL); } +/** + * g_list_insert_sorted_with_data: + * @list: a pointer to a #GList + * @data: the data for the new element + * @func: the function to compare elements in the list. + * It should return a number > 0 if the first parameter + * comes after the second parameter in the sort order. + * @user_data: user data to pass to comparison function. + * + * Inserts a new element into the list, using the given comparison + * function to determine its position. + * + * Returns: the new start of the #GList + * + * Since: 2.10 + */ GList* g_list_insert_sorted_with_data (GList *list, gpointer data, @@ -632,6 +955,19 @@ g_list_sort_real (GList *list, user_data); } +/** + * g_list_sort: + * @list: a #GList + * @compare_func: the comparison function used to sort 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 + * first element comes before the second, or a positive value if + * the first element comes after the second. + * + * Sorts a #GList using the given comparison function. + * + * Returns: the start of the sorted #GList + */ GList * g_list_sort (GList *list, GCompareFunc compare_func) @@ -640,6 +976,17 @@ g_list_sort (GList *list, } +/** + * g_list_sort_with_data: + * @list: a #GList + * @compare_func: comparison function + * @user_data: user data to pass to comparison function + * + * Like g_list_sort(), but the comparison function accepts + * a user data argument. + * + * Returns: the new head of @list + */ GList * g_list_sort_with_data (GList *list, GCompareDataFunc compare_func, diff --git a/glib/gslist.c b/glib/gslist.c index 6fa196b..1e4f01f 100644 --- a/glib/gslist.c +++ b/glib/gslist.c @@ -47,18 +47,66 @@ g_slist_alloc (void) return _g_slist_alloc0 (); } +/** + * g_slist_free: + * @list: a #GSList + * + * Frees all of the memory used by a #GSList. + * The freed elements are returned to the slice allocator. + */ void -g_slist_free (GSList *slist) +g_slist_free (GSList *list) { - g_slice_free_chain (GSList, slist, next); + g_slice_free_chain (GSList, list, next); } +/** + * g_slist_free_1: + * @list: a #GSList element + * + * Frees one #GSList element. + * It is usually used after g_slist_remove_link(). + */ void -g_slist_free_1 (GSList *slist) +g_slist_free_1 (GSList *list) { - _g_slist_free1 (slist); + _g_slist_free1 (list); } +/** + * g_slist_append: + * @list: a #GSList + * @data: the data for the new element + * + * Adds a new element on to the end of the list. + * + * + * The return value is the new start of the list, which may + * have changed, so make sure you store the new value. + * + * + * + * Note that g_slist_append() has to traverse the entire list + * to find the end, which is inefficient when adding multiple + * elements. A common idiom to avoid the inefficiency is to prepend + * the elements and reverse the list when all elements have been added. + * + * + * |[ + * /* Notice that these are initialized to the empty list. */ + * GSList *list = NULL, *number_list = NULL; + * + * /* This is a list of strings. */ + * list = g_slist_append (list, "first"); + * list = g_slist_append (list, "second"); + * + * /* This is a list of integers. */ + * number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); + * number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); + * ]| + * + * Returns: the new start of the #GSList + */ GSList* g_slist_append (GSList *list, gpointer data) @@ -82,6 +130,27 @@ g_slist_append (GSList *list, return new_list; } +/** + * g_slist_prepend: + * @list: a #GSList + * @data: the data for the new element + * + * Adds a new element on to the start of the list. + * + * + * The return value is the new start of the list, which + * may have changed, so make sure you store the new value. + * + * + * |[ + * /* Notice that it is initialized to the empty list. */ + * GSList *list = NULL; + * list = g_slist_prepend (list, "last"); + * list = g_slist_prepend (list, "first"); + * ]| + * + * Returns: the new start of the #GSList + */ GSList* g_slist_prepend (GSList *list, gpointer data) @@ -95,6 +164,19 @@ g_slist_prepend (GSList *list, return new_list; } +/** + * g_slist_insert: + * @list: a #GSList + * @data: the data for the new element + * @position: the position to insert the element. + * If this is negative, or is larger than the number + * of elements in the list, the new element is added on + * to the end of the list. + * + * Inserts a new element into the list at the given position. + * + * Returns: the new start of the #GSList + */ GSList* g_slist_insert (GSList *list, gpointer data, @@ -141,6 +223,16 @@ g_slist_insert (GSList *list, return list; } +/** + * g_slist_insert_before: + * @slist: a #GSList + * @sibling: node to insert @data before + * @data: data to put in the newly-inserted node + * + * Inserts a node before @sibling containing @data. + * + * Returns: the new head of the list. + */ GSList* g_slist_insert_before (GSList *slist, GSList *sibling, @@ -181,6 +273,17 @@ g_slist_insert_before (GSList *slist, } } +/** + * g_slist_concat: + * @list1: a #GSList + * @list2: the #GSList to add to the end of the first #GSList + * + * Adds the second #GSList onto the end of the first #GSList. + * Note that the elements of the second #GSList are not copied. + * They are used directly. + * + * Returns: the start of the new #GSList + */ GSList * g_slist_concat (GSList *list1, GSList *list2) { @@ -195,6 +298,17 @@ g_slist_concat (GSList *list1, GSList *list2) return list1; } +/** + * g_slist_remove: + * @list: a #GSList + * @data: the data of the element to remove + * + * Removes an element from a #GSList. + * If two elements contain the same data, only the first is removed. + * If none of the elements contain the data, the #GSList is unchanged. + * + * Returns: the new start of the #GSList + */ GSList* g_slist_remove (GSList *list, gconstpointer data) @@ -221,6 +335,18 @@ g_slist_remove (GSList *list, return list; } +/** + * g_slist_remove_all: + * list: a #GSList + * @data: data to remove + * + * Removes all list nodes with data equal to @data. + * Returns the new head of the list. Contrast with + * g_slist_remove() which removes only the first node + * matching the given data. + * + * Returns: new head of @list + */ GSList* g_slist_remove_all (GSList *list, gconstpointer data) @@ -282,23 +408,60 @@ _g_slist_remove_link (GSList *list, return list; } +/** + * g_slist_remove_link: + * @list: a #GSList + * @link_: an element in the #GSList + * + * Removes an element from a #GSList, without + * freeing the element. The removed element's next + * link is set to %NULL, so that it becomes a + * self-contained list with one element. + * + * Returns: the new start of the #GSList, without the element + */ GSList* g_slist_remove_link (GSList *list, - GSList *link) + GSList *link_) { - return _g_slist_remove_link (list, link); + return _g_slist_remove_link (list, link_); } +/** + * g_slist_delete_link: + * @list: a #GSList + * @link_: node to delete + * + * Removes the node link_ from the list and frees it. + * Compare this to g_slist_remove_link() which removes the node + * without freeing it. + * + * Returns: the new head of @list + */ GSList* g_slist_delete_link (GSList *list, - GSList *link) + GSList *link_) { - list = _g_slist_remove_link (list, link); - _g_slist_free1 (link); + list = _g_slist_remove_link (list, link_); + _g_slist_free1 (link_); return list; } +/** + * g_slist_copy: + * @list: a #GSList + * + * Copies a #GSList. + * + * + * Note that this is a "shallow" copy. If the list elements + * consist of pointers to data, the pointers are copied but + * the actual data isn't. + * + * + * Returns: a copy of @list + */ GSList* g_slist_copy (GSList *list) { @@ -325,6 +488,14 @@ g_slist_copy (GSList *list) return new_list; } +/** + * g_slist_reverse: + * @list: a #GSList + * + * Reverses a #GSList. + * + * Returns: the start of the reversed #GSList + */ GSList* g_slist_reverse (GSList *list) { @@ -343,6 +514,16 @@ g_slist_reverse (GSList *list) return prev; } +/** + * g_slist_nth: + * @list: a #GSList + * @n: the position of the element, counting from 0 + * + * Gets the element at the given position in a #GSList. + * + * Returns: the element, or %NULL if the position is off + * the end of the #GSList + */ GSList* g_slist_nth (GSList *list, guint n) @@ -353,6 +534,16 @@ g_slist_nth (GSList *list, return list; } +/** + * g_slist_nth_data: + * @list: a #GSList + * @n: the position of the element + * + * Gets the data of the element at the given position. + * + * Returns: the element's data, or %NULL if the position + * is off the end of the #GSList + */ gpointer g_slist_nth_data (GSList *list, guint n) @@ -363,6 +554,17 @@ g_slist_nth_data (GSList *list, return list ? list->data : NULL; } +/** + * g_slist_find: + * @list: a #GSList + * @data: the element data to find + * + * Finds the element in a #GSList which + * contains the given data. + * + * Returns: the found #GSList element, + * or %NULL if it is not found + */ GSList* g_slist_find (GSList *list, gconstpointer data) @@ -377,6 +579,23 @@ g_slist_find (GSList *list, return list; } + +/** + * g_slist_find_custom: + * @list: a #GSList + * @data: user data passed to the function + * @func: the function to call for each element. + * It should return 0 when the desired element is found + * + * Finds an element in a #GSList, using a supplied function to + * find the desired element. It iterates over the list, calling + * the given function which should return 0 when the desired + * element is found. The function takes two #gconstpointer arguments, + * the #GSList element's data as the first argument and the + * given user data. + * + * Returns: the found #GSList element, or %NULL if it is not found + */ GSList* g_slist_find_custom (GSList *list, gconstpointer data, @@ -394,16 +613,27 @@ g_slist_find_custom (GSList *list, return NULL; } +/** + * g_slist_position: + * @list: a #GSList + * @llink: an element in the #GSList + * + * Gets the position of the given element + * in the #GSList (starting from 0). + * + * Returns: the position of the element in the #GSList, + * or -1 if the element is not found + */ gint g_slist_position (GSList *list, - GSList *link) + GSList *llink) { gint i; i = 0; while (list) { - if (list == link) + if (list == llink) return i; i++; list = list->next; @@ -412,6 +642,17 @@ g_slist_position (GSList *list, return -1; } +/** + * g_slist_index: + * @list: a #GSList + * @data: the data to find + * + * Gets the position of the element containing + * the given data (starting from 0). + * + * Returns: the index of the element containing the data, + * or -1 if the data is not found + */ gint g_slist_index (GSList *list, gconstpointer data) @@ -430,6 +671,19 @@ g_slist_index (GSList *list, return -1; } +/** + * g_slist_last: + * @list: a #GSList + * + * Gets the last element in a #GSList. + * + * + * This function iterates over the whole list. + * + * + * Returns: the last element in the #GSList, + * or %NULL if the #GSList has no elements + */ GSList* g_slist_last (GSList *list) { @@ -442,6 +696,19 @@ g_slist_last (GSList *list) return list; } +/** + * g_slist_length: + * @list: a #GSList + * + * Gets the number of elements in a #GSList. + * + * + * This function iterates over the whole list to + * count its elements. + * + * + * Returns: the number of elements in the #GSList + */ guint g_slist_length (GSList *list) { @@ -457,6 +724,14 @@ g_slist_length (GSList *list) return length; } +/** + * g_slist_foreach: + * @list: a #GSList + * @func: the function to call with each element's data + * @user_data: user data to pass to the function + * + * Calls a function for each element of a #GSList. + */ void g_slist_foreach (GSList *list, GFunc func, @@ -524,6 +799,19 @@ g_slist_insert_sorted_real (GSList *list, } } +/** + * g_slist_insert_sorted: + * @list: a #GSList + * @data: the data for the new element + * @func: the function to compare elements in the list. + * It should return a number > 0 if the first parameter + * comes after the second parameter in the sort order. + * + * Inserts a new element into the list, using the given + * comparison function to determine its position. + * + * Returns: the new start of the #GSList + */ GSList* g_slist_insert_sorted (GSList *list, gpointer data, @@ -532,6 +820,22 @@ g_slist_insert_sorted (GSList *list, return g_slist_insert_sorted_real (list, data, (GFunc) func, NULL); } +/** + * g_slist_insert_sorted_with_data: + * @list: a #GSList + * @data: the data for the new element + * @func: the function to compare elements in the list. + * It should return a number > 0 if the first parameter + * comes after the second parameter in the sort order. + * @user_data: data to pass to comparison function + * + * Inserts a new element into the list, using the given + * comparison function to determine its position. + * + * Returns: the new start of the #GSList + * + * Since: 2.10 + */ GSList* g_slist_insert_sorted_with_data (GSList *list, gpointer data, @@ -602,6 +906,19 @@ g_slist_sort_real (GSList *list, user_data); } +/** + * g_slist_sort: + * @list: a #GSList + * @compare_func: the comparison function used to sort the #GSList. + * This function is passed the data from 2 elements of the #GSList + * and should return 0 if they are equal, a negative value if the + * first element comes before the second, or a positive value if + * the first element comes after the second. + * + * Sorts a #GSList using the given comparison function. + * + * Returns: the start of the sorted #GSList + */ GSList * g_slist_sort (GSList *list, GCompareFunc compare_func) @@ -609,6 +926,16 @@ g_slist_sort (GSList *list, return g_slist_sort_real (list, (GFunc) compare_func, NULL); } +/** + * g_slist_sort_with_data: + * @list: a #GSList + * @compare_func: comparison function + * @user_data: data to pass to comparison function + * + * Like g_slist_sort(), but the sort function accepts a user data argument. + * + * Returns: new head of the list + */ GSList * g_slist_sort_with_data (GSList *list, GCompareDataFunc compare_func,