| <!-- ##### SECTION Title ##### --> |
| Singly-Linked Lists |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| linked lists containing integer values or pointers to data, limited to |
| iterating over the list in one direction. |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| The #GSList structure and its associated functions provide a standard |
| singly-linked list data structure. |
| </para> |
| <para> |
| Each element in the list contains a piece of data, together with a pointer |
| which links to the next element in the list. |
| Using this pointer it is possible to move through the list in one |
| direction only (unlike the |
| <link linkend="glib-Doubly-Linked-lists">Doubly-Linked Lists</link> |
| which allow movement in both directions). |
| </para> |
| <para> |
| The data contained in each element can be either integer values, by using one |
| of the |
| <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>, |
| or simply pointers to any type of data. |
| </para> |
| <para> |
| List elements are allocated in blocks using a #GAllocator, which is |
| more efficient than allocating elements individually. |
| </para> |
| <para> |
| Note that most of the #GSList functions expect to be passed a pointer to |
| the first element in the list. The functions which insert elements return |
| the new start of the list, which may have changed. |
| </para> |
| <para> |
| There is no function to create a #GSList. %NULL is considered to be the empty |
| list so you simply set a #GSList* to %NULL. |
| </para> |
| <para> |
| To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert() |
| and g_slist_insert_sorted(). |
| </para> |
| <para> |
| To remove elements, use g_slist_remove(). |
| </para> |
| <para> |
| To find elements in the list use g_slist_last(), g_slist_next(), |
| g_slist_nth(), g_slist_nth_data(), g_slist_find() and |
| g_slist_find_custom(). |
| </para> |
| <para> |
| To find the index of an element use g_slist_position() and g_slist_index(). |
| </para> |
| <para> |
| To call a function for each element in the list use g_slist_foreach(). |
| </para> |
| <para> |
| To free the entire list, use g_slist_free(). |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GSList ##### --> |
| <para> |
| The #GSList struct is used for each element in the singly-linked list. |
| The <structfield>data</structfield> field holds the element's data, which can |
| be a pointer to any kind of data, or any integer value using the |
| <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>. |
| The <structfield>next</structfield> field contains the link to the next |
| element in the list. |
| </para> |
| |
| @data: |
| @next: |
| |
| <!-- ##### FUNCTION g_slist_alloc ##### --> |
| <para> |
| Allocates space for one #GSList element. |
| It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and |
| g_slist_insert_sorted() functions and so is rarely used on its own. |
| </para> |
| |
| @Returns: a pointer to the newly-allocated #GSList element. |
| |
| |
| <!-- ##### FUNCTION g_slist_append ##### --> |
| <para> |
| Adds a new element on to the end of the list. |
| </para> |
| <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> |
| <informalexample><programlisting> |
| /* 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)); |
| </programlisting></informalexample> |
| |
| @list: a #GSList. |
| @data: the data for the new element. |
| @Returns: the new start of the #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_prepend ##### --> |
| <para> |
| Adds a new element on to the start of the list. |
| </para> |
| <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> |
| <informalexample><programlisting> |
| /* Notice that it is initialized to the empty list. */ |
| GSList *list = NULL; |
| list = g_slist_prepend (list, "last"); |
| list = g_slist_prepend (list, "first"); |
| </programlisting></informalexample> |
| |
| @list: a #GSList. |
| @data: the data for the new element. |
| @Returns: the new start of the #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_insert ##### --> |
| <para> |
| Inserts a new element into the list at the given position. |
| </para> |
| |
| @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. |
| @Returns: the new start of the #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_insert_before ##### --> |
| <para> |
| Inserts a node before @sibling containing @data. Returns the new head of the list. |
| </para> |
| |
| @slist: a #GSList. |
| @sibling: node to insert @data before. |
| @data: data to put in the newly-inserted node. |
| @Returns: new head of the list. |
| |
| |
| <!-- ##### FUNCTION g_slist_insert_sorted ##### --> |
| <para> |
| Inserts a new element into the list, using the given comparison function |
| to determine its position. |
| </para> |
| |
| @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. |
| @Returns: the new start of the #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_remove ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list: a #GSList. |
| @data: the data of the element to remove. |
| @Returns: the new start of the #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_remove_link ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list: a #GSList. |
| @link_: an element in the #GSList. |
| @Returns: the new start of the #GSList, without the element. |
| |
| |
| <!-- ##### FUNCTION g_slist_delete_link ##### --> |
| <para> |
| Deletes a node of @list. Returns the new list head. |
| </para> |
| |
| @list: a #GSList. |
| @link_: node to delete. |
| @Returns: new head of @list. |
| |
| |
| <!-- ##### FUNCTION g_slist_remove_all ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list: a #GSList. |
| @data: data to remove. |
| @Returns: new head of @list. |
| |
| |
| <!-- ##### FUNCTION g_slist_free ##### --> |
| <para> |
| Frees all of the memory used by a #GSList. |
| The freed elements are added to the #GAllocator free list. |
| </para> |
| |
| @list: a #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_free_1 ##### --> |
| <para> |
| Frees one #GSList element. |
| It is usually used after g_slist_remove_link(). |
| </para> |
| |
| @list: a #GSList element. |
| |
| |
| <!-- ##### FUNCTION g_slist_length ##### --> |
| <para> |
| Gets the number of elements in a #GSList. |
| </para> |
| |
| @list: a #GSList. |
| @Returns: the number of elements in the #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_copy ##### --> |
| <para> |
| Copies a #GSList. |
| </para> |
| <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> |
| |
| @list: a #GSList. |
| @Returns: a copy of @list. |
| |
| |
| <!-- ##### FUNCTION g_slist_reverse ##### --> |
| <para> |
| Reverses a #GSList. |
| </para> |
| |
| @list: a #GSList. |
| @Returns: the start of the reversed #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_sort ##### --> |
| <para> |
| Sorts a #GSList using the given comparison function. |
| </para> |
| |
| @list: a #GSList. |
| @compare_func: <function>qsort()</function>-style comparison function. |
| @Returns: the start of the sorted #GList. |
| |
| |
| <!-- ##### FUNCTION g_slist_sort_with_data ##### --> |
| <para> |
| Like g_slist_sort(), but the sort function accepts a user data argument. |
| </para> |
| |
| @list: a #GSList |
| @compare_func: comparison function. |
| @user_data: data to pass to comparison function. |
| @Returns: new head of the list. |
| |
| |
| <!-- ##### FUNCTION g_slist_concat ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list1: a #GSList. |
| @list2: the #GSList to add to the end of the first #GSList. |
| @Returns: the start of the new #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_foreach ##### --> |
| <para> |
| Calls a function for each element of a #GSList. |
| </para> |
| |
| @list: a #GSList. |
| @func: the function to call with each element's data. |
| @user_data: user data to pass to the function. |
| |
| |
| <!-- ##### FUNCTION g_slist_last ##### --> |
| <para> |
| Gets the last element in a #GSList. |
| </para> |
| |
| @list: a #GSList. |
| @Returns: the last element in the #GSList, or %NULL if the #GSList has no |
| elements. |
| |
| |
| <!-- ##### MACRO g_slist_next ##### --> |
| <para> |
| A convenience macro to gets the next element in a #GSList. |
| </para> |
| |
| @slist: an element in a #GSList. |
| @Returns: the next element, or %NULL if there are no more elements. |
| |
| |
| <!-- ##### FUNCTION g_slist_nth ##### --> |
| <para> |
| Gets the element at the given position in a #GSList. |
| </para> |
| |
| @list: a #GSList. |
| @n: the position of the element, counting from 0. |
| @Returns: the element, or %NULL if the position is off the end of the #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_nth_data ##### --> |
| <para> |
| Gets the data of the element at the given position. |
| </para> |
| |
| @list: a #GSList. |
| @n: the position of the element. |
| @Returns: the element's data, or %NULL if the position is off the end of the |
| #GSList. |
| |
| |
| <!-- ##### FUNCTION g_slist_find ##### --> |
| <para> |
| Finds the element in a #GSList which contains the given data. |
| </para> |
| |
| @list: a #GSList. |
| @data: the element data to find. |
| @Returns: the found #GSList element, or %NULL if it is not found. |
| |
| |
| <!-- ##### FUNCTION g_slist_find_custom ##### --> |
| <para> |
| 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 |
| and the given user data. |
| </para> |
| |
| @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. |
| @Returns: the found #GSList element, or %NULL if it is not found. |
| |
| |
| <!-- ##### FUNCTION g_slist_position ##### --> |
| <para> |
| Gets the position of the given element in the #GSList (starting from 0). |
| </para> |
| |
| @list: a #GSList. |
| @llink: an element in the #GSList. |
| @Returns: the position of the element in the #GSList, or -1 if the element |
| is not found. |
| |
| |
| <!-- ##### FUNCTION g_slist_index ##### --> |
| <para> |
| Gets the position of the element containing the given data (starting from 0). |
| </para> |
| |
| @list: a #GSList. |
| @data: the data to find. |
| @Returns: the index of the element containing the data, or -1 if the data |
| is not found. |
| |
| |
| <!-- ##### FUNCTION g_slist_push_allocator ##### --> |
| <para> |
| Sets the allocator to use to allocate #GSList elements. |
| Use g_slist_pop_allocator() to restore the previous allocator. |
| </para> |
| <para> |
| Note that this function is not available if GLib has been compiled |
| with <option>--disable-mem-pools</option> |
| </para> |
| |
| @allocator: the #GAllocator to use when allocating #GSList elements. |
| |
| |
| <!-- ##### FUNCTION g_slist_pop_allocator ##### --> |
| <para> |
| Restores the previous #GAllocator, used when allocating #GSList elements. |
| </para> |
| <para> |
| Note that this function is not available if GLib has been compiled |
| with <option>--disable-mem-pools</option> |
| </para> |
| |
| |
| |