Accessing Keys
One of the important tasks of a database programmer is to 'sort' the data, 'find' a specific item or 'filter' a given set.
Keys are the most convenient way to do this, because they are backed by a fast search (indexes) and provide some interesting features.
Lets start with simple keys: A simple key is defined on an attribute of the current structure (or its bases).
When adding or removing data, the indexes (defined by the keys) always get updated.
Each collection (e.g. an extend) refers to one or more of defined keys and allows the programmer to change the access key for the property.
The changeAccessKey() function allows you changing the key by the name defined in the structure. After setting the key all iterative Property functions use the selected index ( e.g. next()/previous() get(iPosition) ).
As long as you access the collections by index this works quiet simple. when accessing the collection by a string (for example the name of all persons) keys get challenging:
You have to define a Key instance (that contains the string) and pass it to the get() function. Since keys may have multiple components and they need to be parsed in order to select the right data (and cannot have certain data in it).
Please be aware that passing keys from user input may lead to unexpected results.
In order to find a certain instance, it might be useful to call locateKey() rather than then get().
While get() is a exact function, locateKey() allows locating the key as exact as possible and provides a cursor position even if the key was not exact.
... fragment ( ) {
Property books;
Key ktitle, kisbn, kauthor;
// get a title (assume the titles are not unique)
books.changeAccessKey("sk_title");
ktitle = "Bible";
try {
books.get(ktitle);
while(books.accessKey() == ktitle){
printf("\nbook matching title: %s",books.value("isbn").toString());
books.next();
}
}catch(odaba::Exception e){
printf("not found");
}
// find a title that partly matches
books.changeAccessKey("sk_title");
ktitle = "Bib";
try {
books.get(ktitle);
while(ktitle.find(books.accessKey())>=0){
printf("\nbook matching title: %s (%s)"
, books.value("title").toString()
, books.value("isbn").toString()
);
books.next();
}
}catch(odaba::Exception e){
printf("not found");
}
// assume isbns are unique
books.changeAccessKey("ik_isbn");
kisbn = "1111-2222-3333-4444";
try{
books.get(kisbn);
printf("\nbook matching isbn: %s",books.value("title").toString());
}catch(odaba::Exception e){
printf("not found");
}
// the author can be found by a key of multiple components
books.changeAccessKey("sk_author");
kauthor = "Adams|Douglas";
books.get(kauthor);
while(books.accessKey() == kauthor){
books.next();
printf("\nbook by %s %s: %s"
, books.value("author.name").toString()
, books.value("author.surname").toString()
, books.value("title").toString()
);
}
// todo: examples for keys with ()[]%%
}