Add_item simply appends key value pairs onto the end of the list.
This function is useful for the initial building of a list.
| kvl.add_item("street", "South Bbridge");
kvl.add_item("city", "Edinburgh");
kvl.add_item("post code", "EH1 1HN");
kvl.add_item("country", "United Kingdom"); |
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.
| kvl.add_item("country", "Scotland", 1); |
This is equivalent to the change_item function, which is
used to overwrite existing entries:
| kvl.change_val("country", "Caledonia"); |
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.
Items are accessed by the val function, indexed by the key:
This prints the value associated with the key "country".
| cout << kvl.val("country") << endl; |
An error is given if the key doesn't exist:
cout << kvl.val("state") << endl;
This can be turned off by use of a flag. In this case the default
value is returned.
| cout << kvl.val("state", 0) << endl; |
A on-the fly default value can be specified by putting using the
val_def function:
| cout << kvl.val_def("state", "unknown") << endl; |
present() returns true of the key exists:
| if (kvl.present("state"))
cout << kvl.val("state") << endl;; |
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 {\tt list} variable contains the key/value
list, from this, \Ref{EST_Litem} pointers can be set to items, and
then used in access functions:
| for (p=kvl.head(); p != 0; p=next(p))
cout << kvl.val(p) << " " << kvl.key(p) << endl; |
this can also be used to change values: the following changes the
value of the pair pointed to by p to "Scotland".
| kvl.change_val(p, "Scotland"); |
The name of the key can be changed similarly:
| kvl.change_key(p, "Nation"); |
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.
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
| op.load(DATA "/options.file"); |
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.
| cout << op.val("Street") << endl;
cout << op.ival("Number") << endl; // print out number as an integer
cout << op.fval("Height") << endl; // print out height as a float |
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:
| op.add_fitem("length", 39.78);
op.override_fval("length", al.fval("-l", 0)); |
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));
//@} code
//@}
}
//@}
