| <!-- ##### SECTION Title ##### --> |
| Doubly-Linked Lists |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| linked lists containing integer values or pointers to data, with the ability |
| to iterate over the list in both directions. |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| The #GList structure and its associated functions provide a standard |
| doubly-linked list data structure. |
| </para> |
| <para> |
| Each element in the list contains a piece of data, together with 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 |
| directions (unlike the |
| <link linkend="glib-Singly-Linked-lists">Singly-Linked Lists</link> |
| which only allows movement through the list in the forward direction). |
| </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 from the <link linkend="glib-Memory-Slices">slice |
| allocator</link>, which is more efficient than allocating elements |
| individually. |
| </para> |
| <para> |
| Note that most of the #GList 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 #GList. %NULL is considered to be the empty |
| list so you simply set a #GList* to %NULL. |
| </para> |
| <para> |
| To add elements, use g_list_append(), g_list_prepend(), g_list_insert() |
| and g_list_insert_sorted(). |
| </para> |
| <para> |
| To remove elements, use g_list_remove(). |
| </para> |
| <para> |
| To find elements in the list use g_list_first(), g_list_last(), g_list_next(), |
| g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() and |
| g_list_find_custom(). |
| </para> |
| <para> |
| To find the index of an element use g_list_position() and g_list_index(). |
| </para> |
| <para> |
| To call a function for each element in the list use g_list_foreach(). |
| </para> |
| <para> |
| To free the entire list, use g_list_free(). |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GList ##### --> |
| <para> |
| The #GList struct is used for each element in a doubly-linked list. |
| </para> |
| |
| @data: 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>. |
| @next: contains the link to the next element in the list. |
| @prev: contains the link to the previous element in the list. |
| |
| <!-- ##### FUNCTION g_list_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> |
| <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> |
| <informalexample><programlisting> |
| /* 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)); |
| </programlisting></informalexample> |
| |
| @list: a pointer to a #GList. |
| @data: the data for the new element. |
| @Returns: the new start of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_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. */ |
| GList *list = NULL; |
| list = g_list_prepend (list, "last"); |
| list = g_list_prepend (list, "first"); |
| </programlisting></informalexample> |
| |
| @list: a pointer to a #GList. |
| @data: the data for the new element. |
| @Returns: the new start of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_insert ##### --> |
| <para> |
| Inserts a new element into the list at the given position. |
| </para> |
| |
| @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. |
| @Returns: the new start of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_insert_before ##### --> |
| <para> |
| Inserts a new element into the list before the given position. |
| </para> |
| |
| @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. |
| @Returns: the new start of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_insert_sorted ##### --> |
| <para> |
| Inserts a new element into the list, using the given comparison function |
| to determine its position. |
| </para> |
| |
| @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. |
| @Returns: the new start of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_remove ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list: a #GList. |
| @data: the data of the element to remove. |
| @Returns: the new start of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_remove_link ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list: a #GList. |
| @llink: an element in the #GList. |
| @Returns: the new start of the #GList, without the element. |
| |
| |
| <!-- ##### FUNCTION g_list_delete_link ##### --> |
| <para> |
| Deletes the node @link_ from @list. |
| </para> |
| |
| @list: a #GList. |
| @link_: node to delete from @list. |
| @Returns: the new head of @list. |
| |
| |
| <!-- ##### FUNCTION g_list_remove_all ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list: a #GList. |
| @data: data to remove. |
| @Returns: new head of @list. |
| |
| |
| <!-- ##### FUNCTION g_list_free ##### --> |
| <para> |
| Frees all of the memory used by a #GList. |
| The freed elements are returned to the slice allocator. |
| </para> |
| <note> |
| <para> |
| If list elements contain dynamically-allocated memory, they should be freed |
| first. |
| </para> |
| </note> |
| |
| @list: a #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_alloc ##### --> |
| <para> |
| Allocates space for one #GList element. |
| It is called by g_list_append(), g_list_prepend(), g_list_insert() and |
| g_list_insert_sorted() and so is rarely used on its own. |
| </para> |
| |
| @Returns: a pointer to the newly-allocated #GList element. |
| |
| |
| <!-- ##### FUNCTION g_list_free_1 ##### --> |
| <para> |
| Frees one #GList element. |
| It is usually used after g_list_remove_link(). |
| </para> |
| |
| @list: a #GList element. |
| |
| |
| <!-- ##### MACRO g_list_free1 ##### --> |
| <para> |
| Another name for g_list_free_1(). |
| </para> |
| |
| |
| |
| <!-- ##### FUNCTION g_list_length ##### --> |
| <para> |
| Gets the number of elements in a #GList. |
| </para> |
| |
| @list: a #GList. |
| @Returns: the number of elements in the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_copy ##### --> |
| <para> |
| Copies a #GList. |
| </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 #GList. |
| @Returns: a copy of @list. |
| |
| |
| <!-- ##### FUNCTION g_list_reverse ##### --> |
| <para> |
| Reverses a #GList. |
| It simply switches the next and prev pointers of each element. |
| </para> |
| |
| @list: a #GList. |
| @Returns: the start of the reversed #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_sort ##### --> |
| <para> |
| Sorts a #GList using the given comparison function. |
| </para> |
| |
| @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. |
| @Returns: the start of the sorted #GList. |
| |
| |
| <!-- ##### USER_FUNCTION GCompareFunc ##### --> |
| <para> |
| Specifies the type of a comparison function used to compare two |
| values. The function should return a negative integer if the first |
| value comes before the second, 0 if they are equal, or a positive |
| integer if the first value comes after the second. |
| </para> |
| |
| @a: a value. |
| @b: a value to compare with. |
| @Returns: negative value if @a < @b; zero if @a = @b; positive value |
| if @a > @b. |
| |
| |
| <!-- ##### FUNCTION g_list_insert_sorted_with_data ##### --> |
| <para> |
| Inserts a new element into the list, using the given comparison function |
| to determine its position. |
| </para> |
| |
| @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. |
| @Returns: the new start of the #GList. |
| @Since 2.10 |
| |
| |
| <!-- ##### FUNCTION g_list_sort_with_data ##### --> |
| <para> |
| Like g_list_sort(), but the comparison function accepts a user data argument. |
| </para> |
| |
| @list: a #GList. |
| @compare_func: comparison function. |
| @user_data: user data to pass to comparison function. |
| @Returns: the new head of @list. |
| |
| |
| <!-- ##### USER_FUNCTION GCompareDataFunc ##### --> |
| <para> |
| Specifies the type of a comparison function used to compare two |
| values. The function should return a negative integer if the first |
| value comes before the second, 0 if they are equal, or a positive |
| integer if the first value comes after the second. |
| </para> |
| |
| @a: a value. |
| @b: a value to compare with. |
| @user_data: user data to pass to comparison function. |
| @Returns: negative value if @a < @b; zero if @a = @b; positive value |
| if @a > @b. |
| |
| |
| <!-- ##### FUNCTION g_list_concat ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @list1: a #GList. |
| @list2: the #GList to add to the end of the first #GList. |
| @Returns: the start of the new #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_foreach ##### --> |
| <para> |
| Calls a function for each element of a #GList. |
| </para> |
| |
| @list: a #GList. |
| @func: the function to call with each element's data. |
| @user_data: user data to pass to the function. |
| |
| |
| <!-- ##### USER_FUNCTION GFunc ##### --> |
| <para> |
| Specifies the type of functions passed to g_list_foreach() and |
| g_slist_foreach(). |
| </para> |
| |
| @data: the element's data. |
| @user_data: user data passed to g_list_foreach() or g_slist_foreach(). |
| |
| |
| <!-- ##### FUNCTION g_list_first ##### --> |
| <para> |
| Gets the first element in a #GList. |
| </para> |
| |
| @list: a #GList. |
| @Returns: the first element in a #GList, or %NULL if the #GList has no elements. |
| |
| |
| <!-- ##### FUNCTION g_list_last ##### --> |
| <para> |
| Gets the last element in a #GList. |
| </para> |
| |
| @list: a #GList. |
| @Returns: the last element in the #GList, or %NULL if the #GList has no |
| elements. |
| |
| |
| <!-- ##### MACRO g_list_previous ##### --> |
| <para> |
| A convenience macro to gets the previous element in a #GList. |
| </para> |
| |
| @list: an element in a #GList. |
| @Returns: the previous element, or %NULL if there are no previous elements. |
| |
| |
| <!-- ##### MACRO g_list_next ##### --> |
| <para> |
| A convenience macro to gets the next element in a #GList. |
| </para> |
| |
| @list: an element in a #GList. |
| @Returns: the next element, or %NULL if there are no more elements. |
| |
| |
| <!-- ##### FUNCTION g_list_nth ##### --> |
| <para> |
| Gets the element at the given position in a #GList. |
| </para> |
| |
| @list: a #GList. |
| @n: the position of the element, counting from 0. |
| @Returns: the element, or %NULL if the position is off the end of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_nth_data ##### --> |
| <para> |
| Gets the data of the element at the given position. |
| </para> |
| |
| @list: a #GList. |
| @n: the position of the element. |
| @Returns: the element's data, or %NULL if the position is off the end of the |
| #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_nth_prev ##### --> |
| <para> |
| Gets the element @n places before @list. |
| </para> |
| |
| @list: a #GList. |
| @n: the position of the element, counting from 0. |
| @Returns: the element, or %NULL if the position is off the end of the #GList. |
| |
| |
| <!-- ##### FUNCTION g_list_find ##### --> |
| <para> |
| Finds the element in a #GList which contains the given data. |
| </para> |
| |
| @list: a #GList. |
| @data: the element data to find. |
| @Returns: the found #GList element, or %NULL if it is not found. |
| |
| |
| <!-- ##### FUNCTION g_list_find_custom ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @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. |
| @Returns: the found #GList element, or %NULL if it is not found. |
| |
| |
| <!-- ##### FUNCTION g_list_position ##### --> |
| <para> |
| Gets the position of the given element in the #GList (starting from 0). |
| </para> |
| |
| @list: a #GList. |
| @llink: an element in the #GList. |
| @Returns: the position of the element in the #GList, or -1 if the element is |
| not found. |
| |
| |
| <!-- ##### FUNCTION g_list_index ##### --> |
| <para> |
| Gets the position of the element containing the given data (starting from 0). |
| </para> |
| |
| @list: a #GList. |
| @data: the data to find. |
| @Returns: the index of the element containing the data, or -1 if the data |
| is not found. |
| |
| |
| <!-- ##### FUNCTION g_list_push_allocator ##### --> |
| <para> |
| Sets the allocator to use to allocate #GList elements. |
| Use g_list_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 #GList elements. |
| @Deprecated: 2.10: It does nothing, since #GList has been |
| converted to the <link linkend="glib-Memory-Slices">slice allocator</link> |
| |
| |
| <!-- ##### FUNCTION g_list_pop_allocator ##### --> |
| <para> |
| Restores the previous #GAllocator, used when allocating #GList elements. |
| </para> |
| <para> |
| Note that this function is not available if GLib has been compiled |
| with <option>--disable-mem-pools</option> |
| </para> |
| |
| @Deprecated: 2.10: It does nothing, since #GList has been |
| converted to the <link linkend="glib-Memory-Slices">slice allocator</link> |
| |
| |