<sect1>
	<title>EST_TList:example</title>

    <para>
 
 some stuff about lists
    </para>
      <formalpara>
        <title>See also</title><para>
        <itemizedlist>
        <listitem><para>EST_TList</para></listitem>
        <listitem><para>EST_TKVL</para></listitem>
        <listitem><para>EST_Option</para></listitem>
        </itemizedlist>
      </para></formalpara>
    <simplesect>
      <title>Inserting items into a list</title>
    <para>
There is no easy way to initialise a list so we'll just set it
from the strings array.
    </para>
    </simplesect>
    <programlisting arch='c'>    // <lineannotation>append adds items on to the end of a list</lineannotation>
    for (unsigned int i1 = 0; i1 &lt; sizeof(strings) /sizeof(strings[0]); i1++)
	slist.append(strings[i1]);

    // <lineannotation>add item to start of list</lineannotation>
    slist.prepend("dove");

    // <lineannotation>find pointer to "eagle", add "hawk" before it, and then add sparrow</lineannotation>
    // <lineannotation>after "hawk"</lineannotation>
    for (p = slist.head(); p != 0; p = next(p))
	if (slist(p) == "eagle")
	{
	    p = slist.insert_before(p,"hawk");
	    p = slist.insert_after(p,"sparrow");
	}    </programlisting>
    <simplesect>
      <title>Iteration over a list</title>
    <para>
A dummy pointer of type \Ref{EST_Litem} is used to iterate
through a list. This acts somewhat like the index in an array in
that it is used to access an item, in the list but does not
contain a value itself.
Iteration is usually done in a for loop. Initialisation involves
setting the pointer to the head() function. Increments are done
by the next() function. At the end of the list, the pointer will
be set to null, and this can be used to check for the end.
Items in the list are accessed by passing the pointer is as the
argument to the function operator(), as in the following example.
    </para>
    </simplesect>
    <programlisting arch='c'>    cout &lt;&lt; "[ List Accessed by LItem\n";
    // <lineannotation>print out contents of array.</lineannotation>
    for (p = slist.head(); p != 0; p = next(p))
      cout &lt;&lt; "  " &lt;&lt; slist(p) &lt;&lt; "\n";
    cout &lt;&lt; "]\n";

    // <lineannotation>items can also be accessed by their position in the list by using the</lineannotation>
    // <lineannotation>nth() function. The length() function returns the number of items</lineannotation>
    // <lineannotation>in a list.</lineannotation>
    cout &lt;&lt; "\n[ List Accessed by integer index\n";
    for (int i2 = 0; i2 &lt; slist.length(); ++i2)
	cout &lt;&lt; "  " &lt;&lt; slist.nth(i2) &lt;&lt; "\n";
    cout &lt;&lt; "]\n";    </programlisting>
    <simplesect>
      <title>Accessing elements of a list</title>
    <para>
The normal way to access an item is to use the \Ref{EST_Litem}
in conjunction with the () operator. Other functions also exist,
eg. first(), last() and nth(). Const and non-const version of
each access function exist, allowing both reading and writing.
    </para>
    </simplesect>
    <programlisting arch='c'>    // <lineannotation>Capital;ise all 'e's in all strings</lineannotation>
    for (p = slist.head(); p != 0; p = next(p))
	slist(p).gsub("e", "E");

    // <lineannotation>print out last item in list</lineannotation>
    p = slist.tail();
    cout &lt;&lt; "Last item: " &lt;&lt; slist(p) &lt;&lt; endl;

    // <lineannotation>but a more direct method is</lineannotation>
    cout &lt;&lt; "Last item: " &lt;&lt; slist.last() &lt;&lt; endl;

    // <lineannotation>likewise with the head of the list:</lineannotation>
    cout &lt;&lt; "First item: " &lt;&lt; slist.first() &lt;&lt; endl;

    // <lineannotation>print out the 4th item:</lineannotation>
    cout &lt;&lt; "4th item: " &lt;&lt; slist.nth(4) &lt;&lt; endl;

    // <lineannotation>All these can be used for overwriting existing members in the list.</lineannotation>
    // <lineannotation>To add new members use append(), prepend(), insert_before() or </lineannotation>
    // <lineannotation>insert_after() as shown in \Ref{Addition}</lineannotation>
    
    slist.first() = "Swallow";
    slist.last() = "TurkEy";
    slist.nth(2) = "SEagull";    </programlisting>
    <simplesect>
      <title>Removing items from a list.</title>
    <para>
Removing items from lists is done by having the EST_Litem point
to a particular item, and then passing this pointer to the
remove function. This can be tricky as this leaves the EST_Litem
pointer pointing to a non-existant item. To get round this, the
remove() function returns a pointer to the previous item in the
list.
    </para>
    </simplesect>
    <programlisting arch='c'>    // <lineannotation>In the following example, the item "eagle" is removed and a </lineannotation>
    // <lineannotation>pointer to the previous item is returned. The for loop then</lineannotation>
    // <lineannotation>points this to the next item in the loop, giving the appearance</lineannotation>
    // <lineannotation>of seamless iteration.</lineannotation>

    for (p = slist.head(); p != 0; p = next(p))
      if (slist(p) == "EaglE")
	p = slist.remove(p);    </programlisting>
    <sect2>
      <title>reverse the list.</title>
      <para>
      </para>
    </sect2>
    <simplesect>
      <title>Sorting a list</title>
    <para>
 
 A number of sort routines for lists are defined. The most useful
 are probably sort (a simple bubble sort, quick for small lists)
 and qsort (quick-sort, faster for long lists).
 
 If the default collation order is not what you want you can pass
 a comparison operator to the sort routine.
    </para>
    </simplesect>
    <programlisting arch='c'>    // <lineannotation>Sort into alphbetical order</lineannotation>
    sort(slist);
 
   cout &lt;&lt; "\n[ Sorted\n";
   for(p=slist.head(); p ; p=next(p))
     cout &lt;&lt; "  " &lt;&lt; slist(p) &lt;&lt; "\n";
   cout &lt;&lt; "]\n";
 
    // <lineannotation>Sort by second character.</lineannotation>
   qsort(slist,&amp;second_char_gt );
 
   cout &lt;&lt; "\n[ Sorted by second character\n";
   for(p=slist.head(); p ; p=next(p))
     cout &lt;&lt; "  " &lt;&lt; slist(p) &lt;&lt; "\n";
   cout &lt;&lt; "]\n";    </programlisting>
    <simplesect>
      <title>Comparison Operation Used in Sort</title>
    <para>
 
 Compares the second character of Strings.
    </para>
    </simplesect>
    <programlisting arch='c'>bool second_char_gt(const EST_UItem *uv1, const EST_UItem *uv2)
{
  const EST_TItem&lt;EST_String&gt; *val1 = (const EST_TItem&lt;EST_String&gt; *)uv1;
  const EST_TItem&lt;EST_String&gt; *val2 = (const EST_TItem&lt;EST_String&gt; *)uv2;
   
  return (bool)(val1-&gt;val(1) &gt; val2-&gt;val(1));
}    </programlisting>
  </sect1>