<sect1>
	<title>EST_KVL:example</title>

    <para>
 
 some stuff about lists
    </para>
      <formalpara>
        <title>See also</title><para>
        <itemizedlist>
        <listitem><para>EST_KVL</para></listitem>
        <listitem><para>EST_KVI</para></listitem>
        <listitem><para>EST_Option</para></listitem>
        </itemizedlist>
      </para></formalpara>
    <simplesect>
      <title>KVL_Addition</title>
    <para>
    </para>
    </simplesect>
    <programlisting arch='c'>    // <lineannotation>add item simply appends key value pairs onto the end of the list.</lineannotation>
    // <lineannotation>This function is useful for the initial building of a list.</lineannotation>
      kvl.add_item("street", "South Bbridge");
      kvl.add_item("city", "Edinburgh");
      kvl.add_item("post code", "EH1 1HN");
      kvl.add_item("country", "United Kingdom");

    // <lineannotation>by default, if a new entry has the same key name as an existing key,</lineannotation>
    // <lineannotation>it will not overwrite this, leaving 2 items with the same key.</lineannotation>
    // <lineannotation>The first will be the one accessed.</lineannotation>
    // <lineannotation>You can overwrite existing keys by adding a flag to this function.</lineannotation>
    // <lineannotation>Note  that this is much slower as all the existing keys must</lineannotation>
    // <lineannotation>be checked.</lineannotation>
      kvl.add_item("country", "Scotland", 1);

    // <lineannotation>This is equivalent to the change_item function, which is</lineannotation>
    // <lineannotation>used to overwrite existing entries:</lineannotation>

      kvl.change_val("country", "Caledonia");    </programlisting>
    <simplesect>
      <title>KVL_Access</title>
    <para>
The usual way to access the list is to pass in the name of the
key to the {\tt val} function, which then returns the value
associated with that key.
    </para>
    </simplesect>
    <programlisting arch='c'>    // <lineannotation>Items are accessed by the val function, indexed by the key:</lineannotation>
    // <lineannotation>This prints the value associated with the key "country".</lineannotation>
    cout &lt;&lt; kvl.val("country") &lt;&lt; endl;

    // <lineannotation>An error is given if the key doesn't exist:</lineannotation>
    cout &lt;&lt; kvl.val("state") &lt;&lt; endl;

    // <lineannotation>This can be turned off by use of a flag. In this case the default</lineannotation>
    // <lineannotation>value is returned.</lineannotation>

    cout &lt;&lt; kvl.val("state", 0) &lt;&lt; endl;

    // <lineannotation>A on-the fly default value can be specified by putting using the</lineannotation>
    // <lineannotation>val_def function:</lineannotation>

    cout &lt;&lt; kvl.val_def("state", "unknown") &lt;&lt; endl;

    // <lineannotation>present() returns true of the key exists:</lineannotation>
    if (kvl.present("state"))
	cout &lt;&lt; kvl.val("state") &lt;&lt; endl;;

    // <lineannotation>Normally, direct access to the list is not needed, but for</lineannotation>
    // <lineannotation>efficiency's sake, it is sometimes useful to be able to directly</lineannotation>
    // <lineannotation>access items. The {\tt list} variable contains the key/value</lineannotation>
    // <lineannotation>list, from this, \Ref{EST_Litem} pointers can be set to items, and</lineannotation>
    // <lineannotation>then used in access functions:</lineannotation>

    for (p=kvl.head(); p != 0; p=next(p))
	 cout &lt;&lt; kvl.val(p) &lt;&lt; " " &lt;&lt; kvl.key(p) &lt;&lt; endl;

    // <lineannotation>this can also be used to change values: the following changes the</lineannotation>
    // <lineannotation>value of the pair pointed to by p to "Scotland".</lineannotation>

    kvl.change_val(p, "Scotland");

    // <lineannotation>The name of the key can be changed similarly:</lineannotation>

    kvl.change_key(p, "Nation");    </programlisting>
    <simplesect>
      <title>EST_Option_General</title>
    <para>
The EST_Option class is a high level version of the EST_KVL class with
strings for both keys and values. It is often used for lists of
options, especially command line arguments.
    </para>
    </simplesect>
    <programlisting arch='c'>    // <lineannotation>load in options from file. The file is in the form of one key</lineannotation>
    // <lineannotation>value pair per line. The key ends at the end of the first</lineannotation>
    // <lineannotation>whitespace delimited token, which allows the values to have</lineannotation>
    // <lineannotation>spaces. Eg.</lineannotation>
    // <lineannotation>Country  Scotland</lineannotation>
    // <lineannotation>Street South Bridge</lineannotation>
    // <lineannotation>Number 80</lineannotation>
    // <lineannotation>Height 23.45</lineannotation>

    // <lineannotation>load in file</lineannotation>
    op.load(DATA "/options.file");

    // <lineannotation>All the normal EST_KVL accessing and addition functions</lineannotation>
    // <lineannotation>work. Although the type of the value is a String, functions are</lineannotation>
    // <lineannotation>provided to allow easy casting to ints and floats.</lineannotation>

    cout &lt;&lt; op.val("Street") &lt;&lt; endl;
    // <lineannotation>print out number as an integer</lineannotation>
    cout &lt;&lt; op.ival("Number") &lt;&lt; endl;
    // <lineannotation>print out height as a float</lineannotation>
    cout &lt;&lt; op.fval("Height") &lt;&lt; endl;

    // <lineannotation>Often, one wishes to override an existing value if a new value</lineannotation>
    // <lineannotation>has been set. The override_val function is useful for this. In</lineannotation>
    // <lineannotation>the following example, the command line argument is held in the</lineannotation>
    // <lineannotation>{\tt al} object. A default value is put in the length field. If</lineannotation>
    // <lineannotation>the command line option is present, it overrides "length",</lineannotation>
    // <lineannotation>otherwise "length" is left unchanged:</lineannotation>

    op.add_fitem("length", 39.78);
    op.override_fval("length", al.fval("-l", 0));

    // <lineannotation>This is quicker than the alternative:</lineannotation>

    op.add_fitem("length", 39.78);

    if (al.present("-l"))
	op.override_fval("length", al.fval("-l", 0));    </programlisting>
  </sect1>