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

453
glib/glist.c
View File

@ -8,7 +8,7 @@
* *
* This library is distributed in the hope that it will be useful, * This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details. * Lesser General Public License for more details.
* *
* You should have received a copy of the GNU Lesser General Public * You should have received a copy of the GNU Lesser General Public
@ -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);
* }
* l = next;
* } * }
* 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 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,14 +213,14 @@ 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
*/ */
void void
g_list_free_full (GList *list, g_list_free_full (GList *list,
GDestroyNotify free_func) GDestroyNotify free_func)
{ {
g_list_foreach (list, (GFunc) free_func, NULL); g_list_foreach (list, (GFunc) free_func, NULL);
g_list_free (list); g_list_free (list);
@ -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,9 +256,9 @@ 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)
{ {
GList *new_list; GList *new_list;
GList *last; GList *last;
@ -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,11 +307,11 @@ 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)
{ {
GList *new_list; GList *new_list;
@ -319,7 +323,7 @@ g_list_prepend (GList *list,
{ {
new_list->prev = list->prev; new_list->prev = list->prev;
if (list->prev) if (list->prev)
list->prev->next = new_list; list->prev->next = new_list;
list->prev = new_list; list->prev = new_list;
} }
else else
@ -340,10 +344,10 @@ 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)
{ {
GList *new_list; GList *new_list;
GList *tmp_list; GList *tmp_list;
@ -378,10 +382,10 @@ 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)
{ {
if (!list) if (!list)
{ {
@ -400,15 +404,15 @@ g_list_insert_before (GList *list,
node->next = sibling; node->next = sibling;
sibling->prev = node; sibling->prev = node;
if (node->prev) if (node->prev)
{ {
node->prev->next = node; node->prev->next = node;
return list; return list;
} }
else else
{ {
g_return_val_if_fail (sibling == list, node); g_return_val_if_fail (sibling == list, node);
return node; return node;
} }
} }
else else
{ {
@ -416,7 +420,7 @@ g_list_insert_before (GList *list,
last = list; last = list;
while (last->next) while (last->next)
last = last->next; last = last->next;
last->next = _g_list_alloc (); last->next = _g_list_alloc ();
last->next->data = data; last->next->data = 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;
@ -455,18 +460,18 @@ g_list_concat (GList *list1, GList *list2)
{ {
tmp_list = g_list_last (list1); tmp_list = g_list_last (list1);
if (tmp_list) if (tmp_list)
tmp_list->next = list2; tmp_list->next = list2;
else else
list1 = list2; list1 = list2;
list2->prev = tmp_list; list2->prev = tmp_list;
} }
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)
{ {
if (link == NULL) if (link == NULL)
return list; return list;
@ -506,9 +511,9 @@ _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)
{ {
GList *tmp; GList *tmp;
@ -516,14 +521,14 @@ g_list_remove (GList *list,
while (tmp) while (tmp)
{ {
if (tmp->data != data) if (tmp->data != data)
tmp = tmp->next; tmp = tmp->next;
else else
{ {
list = _g_list_remove_link (list, tmp); list = _g_list_remove_link (list, tmp);
_g_list_free1 (tmp); _g_list_free1 (tmp);
break; break;
} }
} }
return list; return list;
} }
@ -540,30 +545,30 @@ 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)
{ {
GList *tmp = list; GList *tmp = list;
while (tmp) while (tmp)
{ {
if (tmp->data != data) if (tmp->data != data)
tmp = tmp->next; tmp = tmp->next;
else else
{ {
GList *next = tmp->next; GList *next = tmp->next;
if (tmp->prev) if (tmp->prev)
tmp->prev->next = next; tmp->prev->next = next;
else else
list = next; list = next;
if (next) if (next)
next->prev = tmp->prev; next->prev = tmp->prev;
_g_list_free1 (tmp); _g_list_free1 (tmp);
tmp = next; tmp = next;
} }
} }
return list; return list;
} }
@ -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,9 +593,9 @@ 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)
{ {
return _g_list_remove_link (list, llink); return _g_list_remove_link (list, llink);
} }
@ -606,9 +611,9 @@ 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_)
{ {
list = _g_list_remove_link (list, link_); list = _g_list_remove_link (list, link_);
_g_list_free1 (link_); _g_list_free1 (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;
@ -685,16 +693,16 @@ g_list_copy_deep (GList *list, GCopyFunc func, gpointer user_data)
last = new_list; last = new_list;
list = list->next; list = list->next;
while (list) while (list)
{ {
last->next = _g_list_alloc (); last->next = _g_list_alloc ();
last->next->prev = last; last->next->prev = last;
last = last->next; last = last->next;
if (func) if (func)
last->data = func (list->data, user_data); last->data = func (list->data, user_data);
else else
last->data = list->data; last->data = list->data;
list = list->next; list = list->next;
} }
last->next = NULL; last->next = 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,9 +745,9 @@ 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)
{ {
while ((n-- > 0) && list) while ((n-- > 0) && list)
list = list->next; list = list->next;
@ -757,9 +765,9 @@ 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)
{ {
while ((n-- > 0) && list) while ((n-- > 0) && list)
list = list->prev; list = list->prev;
@ -778,8 +786,8 @@ g_list_nth_prev (GList *list,
* is off the end of the #GList * is off the end of the #GList
*/ */
gpointer gpointer
g_list_nth_data (GList *list, g_list_nth_data (GList *list,
guint n) guint n)
{ {
while ((n-- > 0) && list) while ((n-- > 0) && list)
list = list->next; list = list->next;
@ -792,20 +800,18 @@ 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)
{ {
while (list) while (list)
{ {
if (list->data == data) if (list->data == data)
break; break;
list = list->next; list = list->next;
} }
@ -828,24 +834,23 @@ 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)
{ {
g_return_val_if_fail (func != NULL, list); g_return_val_if_fail (func != NULL, list);
while (list) while (list)
{ {
if (! func (list->data, data)) if (! func (list->data, data))
return list; return list;
list = list->next; list = list->next;
} }
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
@ -859,7 +864,7 @@ g_list_find_custom (GList *list,
*/ */
gint gint
g_list_position (GList *list, g_list_position (GList *list,
GList *llink) GList *llink)
{ {
gint i; gint i;
@ -867,7 +872,7 @@ g_list_position (GList *list,
while (list) while (list)
{ {
if (list == llink) if (list == llink)
return i; return i;
i++; i++;
list = list->next; list = list->next;
} }
@ -888,7 +893,7 @@ g_list_position (GList *list,
*/ */
gint gint
g_list_index (GList *list, g_list_index (GList *list,
gconstpointer data) gconstpointer data)
{ {
gint i; gint i;
@ -896,7 +901,7 @@ g_list_index (GList *list,
while (list) while (list)
{ {
if (list->data == data) if (list->data == data)
return i; return i;
i++; i++;
list = list->next; list = list->next;
} }
@ -913,13 +918,13 @@ 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)
{ {
while (list->next) while (list->next)
list = list->next; list = list->next;
} }
return list; return list;
@ -934,13 +939,13 @@ 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)
{ {
while (list->prev) while (list->prev)
list = list->prev; list = list->prev;
} }
return list; return 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,17 +990,16 @@ 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,
gpointer user_data) gpointer user_data)
{ {
while (list) while (list)
{ {
@ -1008,9 +1011,9 @@ g_list_foreach (GList *list,
static GList* static GList*
g_list_insert_sorted_real (GList *list, g_list_insert_sorted_real (GList *list,
gpointer data, gpointer data,
GFunc func, GFunc func,
gpointer user_data) gpointer user_data)
{ {
GList *tmp_list = list; GList *tmp_list = list;
GList *new_list; GList *new_list;
@ -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,51 +1074,60 @@ 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)
{ {
return g_list_insert_sorted_real (list, data, (GFunc) func, NULL); return g_list_insert_sorted_real (list, data, (GFunc) func, NULL);
} }
/** /**
* 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,
gpointer user_data) gpointer user_data)
{ {
return g_list_insert_sorted_real (list, data, (GFunc) func, user_data); return g_list_insert_sorted_real (list, data, (GFunc) func, user_data);
} }
static GList * static GList *
g_list_sort_merge (GList *l1, g_list_sort_merge (GList *l1,
GList *l2, GList *l2,
GFunc compare_func, GFunc compare_func,
gpointer user_data) gpointer user_data)
{ {
GList list, *l, *lprev; GList list, *l, *lprev;
gint cmp; gint cmp;
@ -1129,13 +1141,13 @@ g_list_sort_merge (GList *l1,
if (cmp <= 0) if (cmp <= 0)
{ {
l->next = l1; l->next = l1;
l1 = l1->next; l1 = l1->next;
} }
else else
{ {
l->next = l2; l->next = l2;
l2 = l2->next; l2 = l2->next;
} }
l = l->next; l = l->next;
l->prev = lprev; l->prev = lprev;
@ -1147,10 +1159,10 @@ 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)
{ {
GList *l1, *l2; GList *l1, *l2;
@ -1165,16 +1177,16 @@ g_list_sort_real (GList *list,
while ((l2 = l2->next) != NULL) while ((l2 = l2->next) != NULL)
{ {
if ((l2 = l2->next) == NULL) if ((l2 = l2->next) == NULL)
break; break;
l1 = l1->next; l1 = l1->next;
} }
l2 = l1->next; l2 = l1->next;
l1->next = NULL; l1->next = NULL;
return g_list_sort_merge (g_list_sort_real (list, compare_func, user_data), return g_list_sort_merge (g_list_sort_real (list, compare_func, user_data),
g_list_sort_real (l2, compare_func, user_data), g_list_sort_real (l2, compare_func, user_data),
compare_func, compare_func,
user_data); 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,12 +1246,12 @@ 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,
gpointer user_data) gpointer user_data)
{ {
return g_list_sort_real (list, (GFunc) compare_func, user_data); return g_list_sort_real (list, (GFunc) compare_func, user_data);
} }