EST_KVL Example

Table of Contents

• Adding items to a KVL
• Accessing EST_KVL
• EST_Option

Example of Key-Value list

Adding items to a KVL

EST_KVL::add_item simply appends key value pairs onto the end of the list. This function is useful for the initial building of a list.

    //@ code
      kvl.add_item("street", "South Bbridge");
      kvl.add_item("city", "Edinburgh");
      kvl.add_item("post code", "EH1 1HN");
      kvl.add_item("country", "United Kingdom");

    //@ endcode

By default, if a new entry has the same key name as an existing key, it will not overwrite this, leaving 2 items with the same key. The first will be the one accessed. You can overwrite existing keys by adding a flag to this function. Note that this is much slower as all the existing keys must be checked.

    //@ code

      kvl.add_item("country", "Scotland", 1);
      
    //@ endcode

This is equivalent to the EST_KVL::change_item function, which is used to overwrite existing entries:

    //@ code

      kvl.change_val("country", "Caledonia");

    //@ endcode

Accessing EST_KVL

The usual way to access the list is to pass in the name of the key to the EST_StrStr_KVL::val function, which then returns the value associated with that key.

    //@ code
    
    cout << kvl.val("country") << endl;
    //@ endcode

Items are accessed by the val function, indexed by the key: This prints the value associated with the key "country".

    //@ code
    cout << kvl.val("state") << endl;
    //@ endcode

An error is given if the key doesn't exist:

    //@ code
    cout << kvl.val("state", 0) << endl;
    //@ endcode

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

    //@ code
    cout << kvl.val_def("state", "unknown") << endl;
    //@ endcode

A on-the fly default value can be specified by putting using the EST_KVL::val_def function:

    //@ code
    if (kvl.present("state"))
        cout << kvl.val("state") << endl;;
    //@ endcode

EST_TKVL::present() returns true of the key exists.

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

    //@ code
    for (p=kvl.head(); p != 0; p=p->next())
     cout << kvl.val(p) << " " << kvl.key(p) << endl;
    //@ endcode

This can also be used to change values: the following changes the value of the pair pointed to by p to "Scotland".

    //@ code
    kvl.change_val(p, "Scotland");
    //@ endcode

The name of the key can be changed similarly:

    //@ code
    kvl.change_key(p, "Nation");
    //@ endcode

EST_Option

The EST_Option class is a high level version of the EST_TKVL class with strings for both keys and values. It is often used for lists of options, especially command line arguments.

Load in options from file. The file is in the form of one key value pair per line. The key ends at the end of the first whitespace delimited token, which allows the values to have spaces. Eg.

Country  Scotland
Street South Bridge
Number 80
Height 23.45

Load in file:

    //@ code
    op.load(DATA "/options.file");
    //@ endcode

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

    //@ code
    cout << op.val("Street") << endl;
    //@ endcode

Print out number as an integer:

    //@ code
    cout << op.ival("Number") << endl;
    //@ endcode

Print out height as a float:

    //@ code
    cout << op.fval("Height") << endl;
    //@ endcode

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

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

This is quicker than the alternative:

    //@ code
    op.add_fitem("length", 39.78);

    if (al.present("-l"))
    op.override_fval("length", al.fval("-l", 0));

    //@ endcode