Add a note regarding inefficiency of repeated appends. (#166271, Olivier

2005-02-04  Matthias Clasen  <mclasen@redhat.com>

	* glib/tmpl/linked_lists_double.sgml:
	* glib/tmpl/linked_lists_single.sgml: Add a note
	regarding inefficiency of repeated appends. (#166271,
	Olivier Sessink)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index b2820f8..0dd4579 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2005-02-04  Matthias Clasen  <mclasen@redhat.com>
+
+       * glib/tmpl/linked_lists_double.sgml: 
+       * glib/tmpl/linked_lists_single.sgml: Add a note 
+       regarding inefficiency of repeated appends. (#166271,
+       Olivier Sessink)
+
 2005-02-03  Matthias Clasen  <mclasen@redhat.com>
 
        * glib/tmpl/quarks.sgml: Add a warning against

diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml
index e72fa3c..2890275 100644 (file)
--- a/docs/reference/glib/tmpl/linked_lists_double.sgml
+++ b/docs/reference/glib/tmpl/linked_lists_double.sgml
@@ -67,16 +67,13 @@ To free the entire list, use g_list_free().
 <!-- ##### STRUCT GList ##### -->
 <para>
 The #GList struct is used for each element in a doubly-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> and <structfield>prev</structfield>
-pointers are the links to the next and previous elements in the list.
 </para>
 
-@data: 
-@next: 
-@prev: 
+@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>
@@ -88,6 +85,14 @@ 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;

diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml
index 7e74451..17a004c 100644 (file)
--- a/docs/reference/glib/tmpl/linked_lists_single.sgml
+++ b/docs/reference/glib/tmpl/linked_lists_single.sgml
@@ -67,15 +67,13 @@ To free the entire list, use g_slist_free().
 <!-- ##### 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: 
+@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>
@@ -97,6 +95,14 @@ 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_slist_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. */
   GSList *list = NULL, *number_list = NULL;