Edinburgh Speech Tools  2.1-release
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
kvl_example.cc
1  /*************************************************************************/
2  /* */
3  /* Centre for Speech Technology Research */
4  /* University of Edinburgh, UK */
5  /* Copyright (c) 1996,1997 */
6  /* All Rights Reserved. */
7  /* Permission is hereby granted, free of charge, to use and distribute */
8  /* this software and its documentation without restriction, including */
9  /* without limitation the rights to use, copy, modify, merge, publish, */
10  /* distribute, sublicense, and/or sell copies of this work, and to */
11  /* permit persons to whom this work is furnished to do so, subject to */
12  /* the following conditions: */
13  /* 1. The code must retain the above copyright notice, this list of */
14  /* conditions and the following disclaimer. */
15  /* 2. Any modifications must be clearly marked as such. */
16  /* 3. Original authors' names are not deleted. */
17  /* 4. The authors' names are not used to endorse or promote products */
18  /* derived from this software without specific prior written */
19  /* permission. */
20  /* THE UNIVERSITY OF EDINBURGH AND THE CONTRIBUTORS TO THIS WORK */
21  /* DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING */
22  /* ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT */
23  /* SHALL THE UNIVERSITY OF EDINBURGH NOR THE CONTRIBUTORS BE LIABLE */
24  /* FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES */
25  /* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN */
26  /* AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, */
27  /* ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF */
28  /* THIS SOFTWARE. */
29  /* */
30  /*************************************************************************/
31  /* */
32  /* Author: Richard Caley (rjc@cstr.ed.ac.uk) */
33  /* Date: Tue Jul 22 1997 */
34  /* --------------------------------------------------------------------- */
35  /* Example of list class use. */
36  /* */
37  /*************************************************************************/
38 
39 #include <cstdlib>
40 #include <iostream>
41 #include "EST_TKVL.h"
42 #include "EST_Option.h"
43 #include "EST_util_class.h"
44 #include "EST_types.h"
45 
46 #if defined(DATAC)
47 # define __STRINGIZE(X) #X
48 # define DATA __STRINGIZE(DATAC)
49 #endif
50 
51 int main(void)
52 {
53  EST_StrStr_KVL kvl; // decl
54  EST_Litem *p; //decl
55  EST_Option al; //decl
56  EST_Option op; //decl
57 
58  // add item simply appends key value pairs onto the end of the list.
59  // This function is useful for the initial building of a list.
60 
61  //@ code
62  kvl.add_item("street", "South Bbridge");
63  kvl.add_item("city", "Edinburgh");
64  kvl.add_item("post code", "EH1 1HN");
65  kvl.add_item("country", "United Kingdom");
66 
67  //@ endcode
68 
69  // by default, if a new entry has the same key name as an existing key,
70  // it will not overwrite this, leaving 2 items with the same key.
71  // The first will be the one accessed.
72  // You can overwrite existing keys by adding a flag to this function.
73  // Note that this is much slower as all the existing keys must
74  // be checked.
75 
76  //@ code
77 
78  kvl.add_item("country", "Scotland", 1);
79 
80  //@ endcode
81 
82  // This is equivalent to the change_item function, which is
83  // used to overwrite existing entries:
84 
85  //@ code
86 
87  kvl.change_val("country", "Caledonia");
88 
89  //@ endcode
90 
91  // KVL_Access
92 
93  // Items are accessed by the val function, indexed by the key:
94  // This prints the value associated with the key "country".
95  //@ code
96 
97  cout << kvl.val("country") << endl;
98  //@ endcode
99 
100  // An error is given if the key doesn't exist:
101  //@ code
102  cout << kvl.val("state") << endl;
103  //@ endcode
104 
105  // This can be turned off by use of a flag. In this case the default
106  // value is returned.
107 
108  //@ code
109  cout << kvl.val("state", 0) << endl;
110  //@ endcode
111 
112  // A on-the fly default value can be specified by putting using the
113  // val_def function:
114 
115  //@ code
116  cout << kvl.val_def("state", "unknown") << endl;
117  //@ endcode
118 
119  // present() returns true of the key exists:
120  //@ code
121  if (kvl.present("state"))
122  cout << kvl.val("state") << endl;;
123  //@ endcode
124 
125  // Normally, direct access to the list is not needed, but for
126  // efficiency's sake, it is sometimes useful to be able to directly
127  // access items. The {\tt list} variable contains the key/value
128  // list, from this, \ref EST_Litem pointers can be set to items, and
129  // then used in access functions:
130 
131  //@ code
132  for (p=kvl.head(); p != 0; p=p->next())
133  cout << kvl.val(p) << " " << kvl.key(p) << endl;
134  //@ endcode
135 
136  // this can also be used to change values: the following changes the
137  // value of the pair pointed to by p to "Scotland".
138 
139  //@ code
140  kvl.change_val(p, "Scotland");
141  //@ endcode
142 
143  // The name of the key can be changed similarly:
144 
145  //@ code
146  kvl.change_key(p, "Nation");
147  //@ endcode
148 
149 
150  // load in options from file. The file is in the form of one key
151  // value pair per line. The key ends at the end of the first
152  // whitespace delimited token, which allows the values to have
153  // spaces. Eg.
154  // Country Scotland
155  // Street South Bridge
156  // Number 80
157  // Height 23.45
158 
159  // load in file
160  //@ code
161  op.load(DATA "/options.file");
162  //@ endcode
163 
164  // All the normal EST_KVL accessing and addition functions
165  // work. Although the type of the value is a String, functions are
166  // provided to allow easy casting to ints and floats.
167 
168  //@ code
169  cout << op.val("Street") << endl;
170  //@ endcode
171  // print out number as an integer
172 
173  //@ code
174  cout << op.ival("Number") << endl;
175  //@ endcode
176 
177  // print out height as a float
178  //@ code
179  cout << op.fval("Height") << endl;
180  //@ endcode
181  // Often, one wishes to override an existing value if a new value
182  // has been set. The override_val function is useful for this. In
183  // the following example, the command line argument is held in the
184  // {\tt al} object. A default value is put in the length field. If
185  // the command line option is present, it overrides "length",
186  // otherwise "length" is left unchanged:
187 
188  //@ code
189  op.add_fitem("length", 39.78);
190  op.override_fval("length", al.fval("-l", 0));
191  //@ endcode
192 
193  // This is quicker than the alternative:
194 
195  //@ code
196  op.add_fitem("length", 39.78);
197 
198  if (al.present("-l"))
199  op.override_fval("length", al.fval("-l", 0));
200 
201  //@ endcode
202 
203 }
204 
205 
206 
207 /** @page EST_KVL-example EST_KVL Example
208  @brief Example of Key-Value list
209  @tableofcontents
210  @dontinclude kvl_example.cc
211 
212  @section KVL_Addition Adding items to a KVL
213 
214  EST_KVL::add_item simply appends key value pairs onto the end of the list.
215  This function is useful for the initial building of a list.
216 
217  @skipline //@ code
218  @until //@ endcode
219 
220  By default, if a new entry has the same key name as an existing key,
221  it will not overwrite this, leaving 2 items with the same key.
222  The first will be the one accessed.
223  You can overwrite existing keys by adding a flag to this function.
224  Note that this is much slower as all the existing keys must
225  be checked.
226 
227  @skipline //@ code
228  @until //@ endcode
229 
230  This is equivalent to the EST_KVL::change_item function, which is
231  used to overwrite existing entries:
232 
233  @skipline //@ code
234  @until //@ endcode
235 
236 
237  @section KVL_Access Accessing EST_KVL
238  The usual way to access the list is to pass in the name of the
239  key to the EST_StrStr_KVL::val function, which then returns the value
240  associated with that key.
241  @skipline //@ code
242  @until //@ endcode
243 
244 
245  Items are accessed by the val function, indexed by the key: This
246  prints the value associated with the key "country".
247  @skipline //@ code
248  @until //@ endcode
249 
250  An error is given if the key doesn't exist:
251  @skipline //@ code
252  @until //@ endcode
253 
254  This can be turned off by use of a flag. In this case the default
255  value is returned.
256 
257  @skipline //@ code
258  @until //@ endcode
259 
260  A on-the fly default value can be specified by putting using the
261  EST_KVL::val_def function:
262 
263  @skipline //@ code
264  @until //@ endcode
265 
266  EST_TKVL::present() returns true of the key exists.
267 
268  Normally, direct access to the list is not needed, but for
269  efficiency's sake, it is sometimes useful to be able to directly
270  access items. The `list` variable contains the key/value
271  list, from this, EST_Litem pointers can be set to items, and
272  then used in access functions:
273 
274  @skipline //@ code
275  @until //@ endcode
276 
277  This can also be used to change values: the following changes the
278  value of the pair pointed to by p to "Scotland".
279 
280  @skipline //@ code
281  @until //@ endcode
282 
283  The name of the key can be changed similarly:
284 
285  @skipline //@ code
286  @until //@ endcode
287 
288 
289 
290  @section EST_Option EST_Option
291 
292  The EST_Option class is a high level version of the EST_TKVL class with
293  strings for both keys and values. It is often used for lists of
294  options, especially command line arguments.
295 
296  Load in options from file. The file is in the form of one key
297  value pair per line. The key ends at the end of the first
298  whitespace delimited token, which allows the values to have
299  spaces. Eg.
300 
301  Country Scotland
302  Street South Bridge
303  Number 80
304  Height 23.45
305 
306  Load in file:
307  @skipline //@ code
308  @until //@ endcode
309 
310  All the normal EST_KVL accessing and addition functions
311  work. Although the type of the value is a String, functions are
312  provided to allow easy casting to ints and floats.
313 
314  @skipline //@ code
315  @until //@ endcode
316 
317  Print out number as an integer:
318 
319  @skipline //@ code
320  @until //@ endcode
321 
322  Print out height as a float:
323  @skipline //@ code
324  @until //@ endcode
325 
326  Often, one wishes to override an existing value if a new value
327  has been set. The override_val function is useful for this. In
328  the following example, the command line argument is held in the
329  `al` object. A default value is put in the length field. If
330  the command line option is present, it overrides "length",
331  otherwise "length" is left unchanged:
332 
333  @skipline //@ code
334  @until //@ endcode
335 
336  This is quicker than the alternative:
337 
338  @skipline //@ code
339  @until //@ endcode
340 
341  */
342 
const K & key(EST_Litem *ptr, int m=1) const
find key, reference by ptr
Definition: EST_TKVL.cc:201
int change_key(EST_Litem *ptr, const K &rkey)
change name of key pair.
Definition: EST_TKVL.cc:99
int ival(const EST_String &rkey, int m=1) const
Definition: EST_Option.cc:76
int override_fval(const EST_String rkey, const float rval)
add to end of list or overwrite. If rval is empty, do nothing
Definition: EST_Option.cc:56
float fval(const EST_String &rkey, int m=1) const
Definition: EST_Option.cc:98
int change_val(const K &rkey, const V &rval)
Definition: EST_TKVL.cc:113
const V & val_def(const K &rkey, const V &def) const
value or default
Definition: EST_TKVL.cc:151
EST_read_status load(const EST_String &filename, const EST_String &comment=";")
Definition: EST_Option.cc:138
EST_Litem * head() const
Return First key value pair in list.
Definition: EST_TKVL.h:102
const int present(const K &rkey) const
Returns true if key is present.
Definition: EST_TKVL.cc:222
const V & val(const K &rkey, bool m=0) const
return value according to key (const)
Definition: EST_TKVL.cc:145
int add_item(const K &rkey, const V &rval, int no_search=0)
add key-val pair to list
Definition: EST_TKVL.cc:248