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

Move docs inline

Browse Source 
svn path=/trunk/; revision=6607
This commit is contained in:
Matthias Clasen 2008-02-29 21:16:21 +00:00
parent a2bee32368
commit 66c0f54221
3 changed files with 698 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -1,3 +1,9 @@
2008-02-29 Matthias Clasen <mclasen@redhat.com>
* 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 <tml@novell.com> 2008-02-29 Tor Lillqvist <tml@novell.com>
* glib/win_iconv.c (name_to_codepage): Add some GNU libiconv * glib/win_iconv.c (name_to_codepage): Add some GNU libiconv

361
glib/glist.c
View File

@ -47,18 +47,71 @@ g_list_alloc (void)
return _g_list_alloc0 (); 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.
*
* <note><para>
* If list elements contain dynamically-allocated memory,
* they should be freed first.
* </para></note>
*/
void void
g_list_free (GList *list) g_list_free (GList *list)
{ {
g_slice_free_chain (GList, list, next); 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 void
g_list_free_1 (GList *list) g_list_free_1 (GList *list)
{ {
_g_list_free1 (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.
*
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para</note>
*
* <note><para>
* 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.
* </para></note>
*
* |[
* /&ast; Notice that these are initialized to the empty list. &ast;/
* GList *list = NULL, *number_list = NULL;
*
* /&ast; This is a list of strings. &ast;/
* list = g_list_append (list, "first");
* list = g_list_append (list, "second");
*
* /&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 (14));
* ]|
*
* Returns: the new start of the #GList
*/
GList* GList*
g_list_append (GList *list, g_list_append (GList *list,
gpointer data) 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.
*
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para></note>
*
* |[
* /&ast; Notice that it is initialized to the empty list. &ast;/
* GList *list = NULL;
* list = g_list_prepend (list, "last");
* list = g_list_prepend (list, "first");
* ]|
*
* Returns: the new start of the #GList
*/
GList* GList*
g_list_prepend (GList *list, g_list_prepend (GList *list,
gpointer data) gpointer data)
@ -109,6 +183,18 @@ g_list_prepend (GList *list,
return new_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* GList*
g_list_insert (GList *list, g_list_insert (GList *list,
gpointer data, gpointer data,
@ -140,6 +226,17 @@ g_list_insert (GList *list,
return 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* GList*
g_list_insert_before (GList *list, g_list_insert_before (GList *list,
GList *sibling, 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 * GList *
g_list_concat (GList *list1, GList *list2) g_list_concat (GList *list1, GList *list2)
{ {
@ -207,6 +315,17 @@ g_list_concat (GList *list1, GList *list2)
return list1; 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* GList*
g_list_remove (GList *list, g_list_remove (GList *list,
gconstpointer data) gconstpointer data)
@ -236,6 +355,18 @@ g_list_remove (GList *list,
return 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* GList*
g_list_remove_all (GList *list, g_list_remove_all (GList *list,
gconstpointer data) gconstpointer data)
@ -285,23 +416,59 @@ _g_list_remove_link (GList *list,
return 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* GList*
g_list_remove_link (GList *list, 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* 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_);
return list; return list;
} }
/**
* g_list_copy:
* @list: a #GList
*
* Copies a #GList.
*
* <note><para>
* 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.
* </para></note>
*
* Returns: a copy of @list
*/
GList* GList*
g_list_copy (GList *list) g_list_copy (GList *list)
{ {
@ -330,6 +497,15 @@ g_list_copy (GList *list)
return new_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* GList*
g_list_reverse (GList *list) g_list_reverse (GList *list)
{ {
@ -347,6 +523,16 @@ g_list_reverse (GList *list)
return last; 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* GList*
g_list_nth (GList *list, g_list_nth (GList *list,
guint n) guint n)
@ -357,6 +543,16 @@ g_list_nth (GList *list,
return 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* GList*
g_list_nth_prev (GList *list, g_list_nth_prev (GList *list,
guint n) guint n)
@ -367,6 +563,16 @@ g_list_nth_prev (GList *list,
return 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 gpointer
g_list_nth_data (GList *list, g_list_nth_data (GList *list,
guint n) guint n)
@ -377,6 +583,17 @@ g_list_nth_data (GList *list,
return list ? list->data : NULL; 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* GList*
g_list_find (GList *list, g_list_find (GList *list,
gconstpointer data) gconstpointer data)
@ -391,6 +608,22 @@ g_list_find (GList *list,
return 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* GList*
g_list_find_custom (GList *list, g_list_find_custom (GList *list,
gconstpointer data, 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 gint
g_list_position (GList *list, g_list_position (GList *list,
GList *link) GList *llink)
{ {
gint i; gint i;
i = 0; i = 0;
while (list) while (list)
{ {
if (list == link) if (list == llink)
return i; return i;
i++; i++;
list = list->next; list = list->next;
@ -427,6 +671,17 @@ g_list_position (GList *list,
return -1; 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 gint
g_list_index (GList *list, g_list_index (GList *list,
gconstpointer data) gconstpointer data)
@ -445,6 +700,15 @@ g_list_index (GList *list,
return -1; 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* GList*
g_list_last (GList *list) g_list_last (GList *list)
{ {
@ -457,6 +721,15 @@ g_list_last (GList *list)
return 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* GList*
g_list_first (GList *list) g_list_first (GList *list)
{ {
@ -469,6 +742,19 @@ g_list_first (GList *list)
return list; return list;
} }
/**
* g_list_length:
* @list: a #GList
*
* Gets the number of elements in a #GList.
*
* <note><para>
* This function iterates over the whole list to
* count its elements.
* </para></note>
*
* Returns: the number of elements in the #GList
*/
guint guint
g_list_length (GList *list) g_list_length (GList *list)
{ {
@ -484,6 +770,14 @@ g_list_length (GList *list)
return length; 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 void
g_list_foreach (GList *list, g_list_foreach (GList *list,
GFunc func, GFunc func,
@ -549,6 +843,19 @@ g_list_insert_sorted_real (GList *list,
return 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* GList*
g_list_insert_sorted (GList *list, g_list_insert_sorted (GList *list,
gpointer data, gpointer data,
@ -557,6 +864,22 @@ g_list_insert_sorted (GList *list,
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:
* @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* GList*
g_list_insert_sorted_with_data (GList *list, g_list_insert_sorted_with_data (GList *list,
gpointer data, gpointer data,
@ -632,6 +955,19 @@ g_list_sort_real (GList *list,
user_data); 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 * GList *
g_list_sort (GList *list, g_list_sort (GList *list,
GCompareFunc compare_func) 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 * GList *
g_list_sort_with_data (GList *list, g_list_sort_with_data (GList *list,
GCompareDataFunc compare_func, GCompareDataFunc compare_func,

349
glib/gslist.c
View File

@ -47,18 +47,66 @@ g_slist_alloc (void)
return _g_slist_alloc0 (); 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 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 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.
*
* <note><para>
* The return value is the new start of the list, which may
* have changed, so make sure you store the new value.
* </para></note>
*
* <note><para>
* 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.
* </para></note>
*
* |[
* /&ast; Notice that these are initialized to the empty list. &ast;/
* GSList *list = NULL, *number_list = NULL;
*
* /&ast; This is a list of strings. &ast;/
* list = g_slist_append (list, "first");
* list = g_slist_append (list, "second");
*
* /&ast; This is a list of integers. &ast;/
* 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* GSList*
g_slist_append (GSList *list, g_slist_append (GSList *list,
gpointer data) gpointer data)
@ -82,6 +130,27 @@ g_slist_append (GSList *list,
return new_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.
*
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para></note>
*
* |[
* /&ast; Notice that it is initialized to the empty list. &ast;/
* GSList *list = NULL;
* list = g_slist_prepend (list, "last");
* list = g_slist_prepend (list, "first");
* ]|
*
* Returns: the new start of the #GSList
*/
GSList* GSList*
g_slist_prepend (GSList *list, g_slist_prepend (GSList *list,
gpointer data) gpointer data)
@ -95,6 +164,19 @@ g_slist_prepend (GSList *list,
return new_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* GSList*
g_slist_insert (GSList *list, g_slist_insert (GSList *list,
gpointer data, gpointer data,
@ -141,6 +223,16 @@ g_slist_insert (GSList *list,
return 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* GSList*
g_slist_insert_before (GSList *slist, g_slist_insert_before (GSList *slist,
GSList *sibling, 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 * GSList *
g_slist_concat (GSList *list1, GSList *list2) g_slist_concat (GSList *list1, GSList *list2)
{ {
@ -195,6 +298,17 @@ g_slist_concat (GSList *list1, GSList *list2)
return list1; 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* GSList*
g_slist_remove (GSList *list, g_slist_remove (GSList *list,
gconstpointer data) gconstpointer data)
@ -221,6 +335,18 @@ g_slist_remove (GSList *list,
return 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* GSList*
g_slist_remove_all (GSList *list, g_slist_remove_all (GSList *list,
gconstpointer data) gconstpointer data)
@ -282,23 +408,60 @@ _g_slist_remove_link (GSList *list,
return 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* GSList*
g_slist_remove_link (GSList *list, 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* GSList*
g_slist_delete_link (GSList *list, g_slist_delete_link (GSList *list,
GSList *link) GSList *link_)
{ {
list = _g_slist_remove_link (list, link); list = _g_slist_remove_link (list, link_);
_g_slist_free1 (link); _g_slist_free1 (link_);
return list; return list;
} }
/**
* g_slist_copy:
* @list: a #GSList
*
* Copies a #GSList.
*
* <note><para>
* 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.
* </para></note>
*
* Returns: a copy of @list
*/
GSList* GSList*
g_slist_copy (GSList *list) g_slist_copy (GSList *list)
{ {
@ -325,6 +488,14 @@ g_slist_copy (GSList *list)
return new_list; return new_list;
} }
/**
* g_slist_reverse:
* @list: a #GSList
*
* Reverses a #GSList.
*
* Returns: the start of the reversed #GSList
*/
GSList* GSList*
g_slist_reverse (GSList *list) g_slist_reverse (GSList *list)
{ {
@ -343,6 +514,16 @@ g_slist_reverse (GSList *list)
return prev; 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* GSList*
g_slist_nth (GSList *list, g_slist_nth (GSList *list,
guint n) guint n)
@ -353,6 +534,16 @@ g_slist_nth (GSList *list,
return 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 gpointer
g_slist_nth_data (GSList *list, g_slist_nth_data (GSList *list,
guint n) guint n)
@ -363,6 +554,17 @@ g_slist_nth_data (GSList *list,
return list ? list->data : NULL; 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* GSList*
g_slist_find (GSList *list, g_slist_find (GSList *list,
gconstpointer data) gconstpointer data)
@ -377,6 +579,23 @@ g_slist_find (GSList *list,
return 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* GSList*
g_slist_find_custom (GSList *list, g_slist_find_custom (GSList *list,
gconstpointer data, gconstpointer data,
@ -394,16 +613,27 @@ g_slist_find_custom (GSList *list,
return NULL; 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 gint
g_slist_position (GSList *list, g_slist_position (GSList *list,
GSList *link) GSList *llink)
{ {
gint i; gint i;
i = 0; i = 0;
while (list) while (list)
{ {
if (list == link) if (list == llink)
return i; return i;
i++; i++;
list = list->next; list = list->next;
@ -412,6 +642,17 @@ g_slist_position (GSList *list,
return -1; 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 gint
g_slist_index (GSList *list, g_slist_index (GSList *list,
gconstpointer data) gconstpointer data)
@ -430,6 +671,19 @@ g_slist_index (GSList *list,
return -1; return -1;
} }
/**
* g_slist_last:
* @list: a #GSList
*
* Gets the last element in a #GSList.
*
* <note><para>
* This function iterates over the whole list.
* </para></note>
*
* Returns: the last element in the #GSList,
* or %NULL if the #GSList has no elements
*/
GSList* GSList*
g_slist_last (GSList *list) g_slist_last (GSList *list)
{ {
@ -442,6 +696,19 @@ g_slist_last (GSList *list)
return list; return list;
} }
/**
* g_slist_length:
* @list: a #GSList
*
* Gets the number of elements in a #GSList.
*
* <note><para>
* This function iterates over the whole list to
* count its elements.
* </para></note>
*
* Returns: the number of elements in the #GSList
*/
guint guint
g_slist_length (GSList *list) g_slist_length (GSList *list)
{ {
@ -457,6 +724,14 @@ g_slist_length (GSList *list)
return length; 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 void
g_slist_foreach (GSList *list, g_slist_foreach (GSList *list,
GFunc func, 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* GSList*
g_slist_insert_sorted (GSList *list, g_slist_insert_sorted (GSList *list,
gpointer data, gpointer data,
@ -532,6 +820,22 @@ g_slist_insert_sorted (GSList *list,
return g_slist_insert_sorted_real (list, data, (GFunc) func, NULL); 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* GSList*
g_slist_insert_sorted_with_data (GSList *list, g_slist_insert_sorted_with_data (GSList *list,
gpointer data, gpointer data,
@ -602,6 +906,19 @@ g_slist_sort_real (GSList *list,
user_data); 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 * GSList *
g_slist_sort (GSList *list, g_slist_sort (GSList *list,
GCompareFunc compare_func) GCompareFunc compare_func)
@ -609,6 +926,16 @@ g_slist_sort (GSList *list,
return g_slist_sort_real (list, (GFunc) compare_func, NULL); 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 * GSList *
g_slist_sort_with_data (GSList *list, g_slist_sort_with_data (GSList *list,
GCompareDataFunc compare_func, GCompareDataFunc compare_func,