linked_lists_single.sgml

this is a glib for c language

<!-- ##### 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>