| <!-- ##### 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 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 #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. |
| </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. |
| |
| <!-- ##### 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> |
| |
| </para> |
| |
| @list: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_prepend ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_insert ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @position: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_insert_before ##### --> |
| <para> |
| |
| </para> |
| |
| @slist: |
| @sibling: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_insert_sorted ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @func: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_remove ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_remove_link ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @link_: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_delete_link ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @link_: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_remove_all ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_free ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| |
| |
| <!-- ##### FUNCTION g_slist_free_1 ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| |
| |
| <!-- ##### MACRO g_slist_free1 ##### --> |
| <para> |
| A macro which does the same as g_slist_free_1(). |
| </para> |
| |
| @Since: 2.10 |
| |
| |
| <!-- ##### FUNCTION g_slist_length ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_copy ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_reverse ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_insert_sorted_with_data ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @func: |
| @user_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_sort ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @compare_func: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_sort_with_data ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @compare_func: |
| @user_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_concat ##### --> |
| <para> |
| |
| </para> |
| |
| @list1: |
| @list2: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_foreach ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @func: |
| @user_data: |
| |
| |
| <!-- ##### FUNCTION g_slist_last ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @Returns: |
| |
| |
| <!-- ##### 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> |
| |
| </para> |
| |
| @list: |
| @n: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_nth_data ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @n: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_find ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_find_custom ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @func: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_position ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @llink: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_slist_index ##### --> |
| <para> |
| |
| </para> |
| |
| @list: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### 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> |
| |
| @dummy: the #GAllocator to use when allocating #GSList elements. |
| @Deprecated: 2.10: It does nothing, since #GSList has been |
| converted to the <link linkend="glib-Memory-Slices">slice allocator</link> |
| |
| |
| <!-- ##### 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> |
| |
| @Deprecated: 2.10: It does nothing, since #GSList has been |
| converted to the <link linkend="glib-Memory-Slices">slice allocator</link> |
| |
| |