Property :: locateKey - Locate instance according to key

The instance with the passed value will be located for the currently selected access key. The selected access key must refer to an ordered index. When no access key is selected or when the access key refers to an unordered index, the function will throw an exception

Usually, the function tries to locate the instance with the key value requested in vSortKey or rProperty, or the next higher key value, when the requested key value could not be found. In order to locate only key values, that matches exactly the requested key value, bExact should be passed (true).

When a filter or key filter has been set, the function locates instances, only, which fulfill the filter condition. In case of instance filters, the instance will be positioned.

In case of error or when no instance could be located, the function throws an exception.Otherwise the instance is located in the property handle and can be selected later on by calling get().

When an instance is already positioned, the key value is checked and the function does not change the selection, when the selected instance matches the key value. This might cause unexpected results in case of indexes allowing duplicate key values. In order to locate the first key with the passed key value, the selection in the property handle should be reset (top()).

The function returns true, when an instance has been located successfully and false otherwise. After terminating successfully, an instance is located in the property handle.

Return value: Success ( bool )

The value is true when the function was executed successfully. Otherwise the value is set to false.

Implementation overview

Locate key by key value
Property :: locateKey ( vSortKey )
Locate partial key value
Property :: locateKey ( vSortKey, iKeyLevel )
Locate partial key value exactly
Property :: locateKey ( vSortKey, iKeyLevel, bExact )
Locate instance precisely
Property :: locateKey ( vSortKey, bExact )

Implementation details

Locate key by key value
bool Property :: locateKey ( odaba::Key vSortKey )

The function tries to locate the instance with a key value as being passed in vSortKey or the next in index. When the key passed contains less key components than defined for the currently selected access key, missing key components are filled with "empty" values.
- vSortKey - Access key
  The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.
  
  // key: name;first_name
  
  Miller;Paul // simple positioned CSV key
  
  "Miller";"Paul Mary" // special characters must be quoted

to list

Locate partial key value
bool Property :: locateKey ( odaba::Key vSortKey, int32 iKeyLevel )

The function tries to locate the instance with a partial key value as being passed in vSortKey or the next in index. The number of key components included in the operation depends on the value passed in iKeyLevel. When the key passed contains less key components than requested, missing key components are filled with "empty" values.
- vSortKey - Access key
  The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.
  
  // key: name;first_name
  
  Miller;Paul // simple positioned CSV key
  
  "Miller";"Paul Mary" // special characters must be quoted
- iKeyLevel - Number of fixed key component
  The switch level defines the key component number that need not change when calling next() or locateKey() beginning with 1 for the first key component.

to list

Locate partial key value exactly
bool Property :: locateKey ( odaba::Key vSortKey, int32 iKeyLevel, bool bExact )

The function tries to locate the instance with a partial key value as being passed in vSortKey. The number of key components included in the operation depends on the value passed in iKeyLevel. When the key passed contains less key components than requested, missing key components are filled with "empty" values.
- vSortKey - Access key
  The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.
  
  // key: name;first_name
  
  Miller;Paul // simple positioned CSV key
  
  "Miller";"Paul Mary" // special characters must be quoted
- iKeyLevel - Number of fixed key component
  The switch level defines the key component number that need not change when calling next() or locateKey() beginning with 1 for the first key component.
- bExact - Exact option
  The exact option (true) forces the function to locate the instance with the exact key.

to list

Locate instance precisely
bool Property :: locateKey ( odaba::Key vSortKey, bool bExact )

The function tries to locate the instance with exactly the key value passed in vSortKey. When the key passed contains less key components than defined for the currently selected access key, missing key components are filled with "empty" values.
- vSortKey - Access key
  The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.
  
  // key: name;first_name
  
  Miller;Paul // simple positioned CSV key
  
  "Miller";"Paul Mary" // special characters must be quoted
- bExact - Exact option
  The exact option (true) forces the function to locate the instance with the exact key.

to list

to top Comment