mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-28 10:30:03 +01:00
e773d7dba6
Mon Dec 11 04:44:11 2000 Tim Janik <timj@gtk.org> * gboxed.c: fixed dealing with collection/lcopy of NULL values. * gclosure.h: removed insane ramblings, added G_CALLBACK() a casting convenience macro. * Makefile.am: cleanups, marshaller generation rules. * gmarshal.[hc]: new files with GRuntime standard marshallers. * glib-genmarshal.c: fix log domain, support gruntime standard marshallers, suport G_TYPE_PARAM, come with extern "C" and #include gmarshal.h. * glib-genmarshal.1: reflect glib-genmarshal.c updates. * gobject.[hc]: implement object constructor. rework parameter changed notification queueing, we support queue freezes now and don't dispatch from an idle handler anymore. parameter->property rename hassle. implemented ::properties_changed and ::notify::* signals for property change notification (the later supports property names as details). added signal connection and named data properties. (g_signal_connect_object): new function to setup while_alive connections. (g_object_class_install_property): sink properties now, since they are initially floating. (g_object_steal_data): (g_object_set_data_full): (g_object_set_data): (g_object_get_data): set/get data by using g_datalist_*() functions directly. (g_object_queue_param_changed): nuked. (g_object_freeze_notify): start queueing of property changes (freeze/ thaw calls stack). (g_object_notify): announce changes of a certain property directly. (g_object_thaw_notify): process queue of property changes, therefore emitting GObject::notify::detail with detail being the changed properties names. (G_OBJECT_WARN_INVALID_PROPERTY_ID): saner macro variant of former G_WARN_INVALID_PARAM_ID(). * gparam.[hc]: param specs are now initially floating and need to be sunken with g_param_spec_sink(), support G_TYPE_PARAM values. added G_PARAM_CONSTRUCT and G_PARAM_CONSTRUCT_ONLY parameter flags, required by GObjectClass.constructor(). * gparamspecs.[hc]: added GParamSpecParam, GParamSpecPointer and GParamSpecCCallback, param specs for G_TYPE_PARAM, G_TYPE_POINTER and G_TYPE_CCALLBACK respectively. * gsignal.[hc]: cleanups. (signal_id_lookup): after walking the anchestry, try interfaces as well. (g_signal_new): new function to create signals from varargs type list. (g_signal_connect_closure): closure connection variant that works from signal name+detail. (g_signal_connect_data): c handler connection variant that works from signal name+detail. (g_signal_emit_valist): emit signal for an instance with paraneters collected from a va_list. (g_signal_emit): emit signal, taking parameters from varargs list. (g_signal_emit_by_name): same as g_signal_emit, working from signal name+detail. (signal_emit_R): return whether return_value needs to be altered. * gtype.[hc]: set log-domain to GRuntime, i'm slowly getting to all the points that need to reflect the upcoming rename. melt g_type_conforms_to() functionality into g_type_is_a(), as that is what we really want (liskov substitution principle). assorted changes to other files due to conforms_to->is_a. * gvalue.[hc]: implemented g_value_set_instance() that sets a value from an instantiatable type via the value_table's collect_value() function (based on an idea from James Henstridge <james@daa.com.au>). cleanups/fixes. * gvaluetypes.[hc]: implement G_TYPE_CCALLBACK and G_TYPE_PARAM.
401 lines
10 KiB
Plaintext
401 lines
10 KiB
Plaintext
<!-- ##### 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 #GListAllocator, 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>
|
|
|
|
<!-- ##### 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>
|
|
|
|
</para>
|
|
|
|
@slist:
|
|
@sibling:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### 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>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@link:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_slist_free ##### -->
|
|
<para>
|
|
Frees all of the memory used by a #GSList.
|
|
The freed elements are added to the #GListAllocator 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: the comparison function used to sort the #GSList. This function
|
|
is passed 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.
|
|
@Returns: the start of the sorted #GList.
|
|
|
|
|
|
<!-- ##### 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>
|
|
|
|
@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>
|
|
|
|
|
|
|