QbKeyDatabaseClass is derived from the QbDatabaseClass and returns the results of queries and specifies a restriction list of keys. A restriction list is a list of keys used to restrict a query. For example, in a query such as "Find images by artist Picasso with this shade of red" with a text query on "Picasso" returns a set of keys of images associated with Picasso. These keys are then passed to the query engine as a restriction list together with the content-based query specification for "red" to obtain the final, ordered query results.
QbKeyDatabaseClass is a database of keys with distance values. Iterations on this database are required to return items in increasing distance order. Key order is used in the event of a tie.
The IsRanked and SetRanked methods allow you to find or set the ranked state of this database. Even though the database is always sorted by distance, this sort may not be valid.
The GetDistance and SetDistance methods return or set the distance of a value datum. When you use a QbKeyDatabaseClass instance to define a restriction list, use the same distance for all elements or call SetDistance with no distance argument (it defaults to use the distance of -1.0).
The GetNumberOfKeys method returns the number of keys (records) in the database. The return results of a query are always ranked.
The RetrieveMax method retrieves the element with the largest distance in the list. An efficient implementation of this method could greatly enhance query performance.
To pass restriction lists to a query, use the ToQueryString method. This process can be reversed using the FromQueryString method. In the current implementation, the ToQueryString method creates a blank terminated list of key distance pairs, and FromQueryString reinserts these into a QbKeyDatabaseClass object.
This chapter describes the following methods:
You can see coding examples in Appendix C, "Sample Code" on page 185. Other programs are located in the qbic/QbicApi
directory.
This is the constructor for the class.
QbKeyDatabaseClass( void )
This is the destructor for the class.
virtual ~QbKeyDatabaseClass( void )
This method decodes the string inside a QbDatumClass object to initialize the object. Distance values for all keys are set to zero.
virtual int FromKeyString( const QbDatumClass &datum )
datum-A reference to a QbDatumClass object whose byte string holds names of keys separated by spaces
An integer value: 0 indicates success; -1 indicates failure
This method decodes the byte string in the input QbDatumClass object and initializes the QbKeyDatabaseClass object.
virtual int FromQueryString( const QbDatumClass &datum )
datum-A reference to a QbDatumClass object that holds the encoded key-distance pairs
An integer value: 0 indicates success; -1 indicates failure
This method retrieves the distance value from the input QbDatumClass object.
virtual float GetDistance( const QbDatumClass &data )
data-A reference to a QbDatumClass object whose byte string holds the distance value
A float value that represents the distance
This method returns the number of elements in the object.
unsigned long GetNumberOfKeys( void )
An unsigned long integer that represents the number of elements
This method returns True if the database is set to order the keys based on the distance value, False if not.
Boolean IsRanked( void )
A Boolean value; True if the database is set to order the keys based on the distance value, False if it is not.
This method retrieves the key-value pair that contains the maximum distance in the object.
virtual int RetrieveMax( QbDatumClass &key, QbDatumClass &value )
An integer value: 0 indicates success; 1 indicates nonfatal error (for example, no keys in object); -1 indicates fatal error
This method assigns the distance value into the byte string in the input data object.
virtual int SetDistance( QbDatumClass &data, const float distance = -1 )
An integer value: 0 indicates success; -1 indicates failure
This method makes the object order keys based on the distance value if rank=True.
void SetRanked( const Boolean rank )
rank-A Boolean value; True means rank on distance, False means do not.
This method encodes keys inside an object to an ASCII string and assigns it to the byte string of the given QbDatumClass object. The distance records are not encoded.
virtual int ToKeyString( QbDatumClass &datum )
datum-A reference to a QbDatumClass object whose byte string will hold the encoded keys
An integer value: 0 indicates success; -1 indicates failure
This method encodes both key and distance values in the object to an ASCII string and assigns it to the a byte string in the input QbDatumClass object.
virtual int ToQueryString( QbDatumClass &datum )
datum-A reference to a QbDatumClass object whose byte string will hold encoded key-distance pairs
An integer value: 0 indicates success; -1 indicates failure