Property :: nextKey - Locate next key value

The function tries to locate the next key value according to the selected access key starting at the located instance or a key offset.

The function locates the key value next to the offset or currently located instance. The function returns the next key value located. When calling the function for indexes allowing duplicate key values, nextKey() also returns duplicates.

When a filter or key filter has been set, the function locates the next key value or instance fulfilling the filter condition.

Usually, the instance will be located but not selected. In case of instance filters or unordered collections, however, the instance will be selected. In order to select the instance located one may call get().

The function returns the key value. In case of success, the property handle is located, i.e. Property::located() returns true. When no key is defined (e.g. for untyped collections), or when an error occurred while reading data, the function throws an exception. When no more key could be located, the function returns an null string (String::isNull()) and property handle state is not located.

... fragment( odaba::Property &person ) {

odaba::Key key;

person.top(); // start from beginning

while ( !(key = person.nextKey()).isNull() ) {

// process located key

}

Return value: New key value for instance ( odaba::Key )

The key passed for renaming the instance must be structured according to the currently selected sort order. Key components within a key must be separated by '|' or ';'. An empty string can be passed in order to indicate no key value.

In order to pass no key value, an empty string ( String() ) has to be passed.

Implementation overview

Locate next key value from current position
Property :: nextKey ( )
Locate next key value for passed offset
Property :: nextKey ( vSortKey )
Locate next key value from offset on key level
Property :: nextKey ( vSortKey, iKeyLevel )
Locate next instance for key level
Property :: nextKey ( iKeyLevel )

Implementation details

Locate next key value from current position
odaba::Key Property :: nextKey ( )

The function locates the next key value starting at current position (last instance located). When no instance is located, the function returns the first key.

to list

Locate next key value for passed offset
odaba::Key Property :: nextKey ( odaba::Key vSortKey )

The function tries to locate the next key value starting at key offset passed in vSortKey. When the key is not yet located in the collection, the function locates the first key. Otherwise, it tries to locate the next instance with the same key value. If there is no such key, the function throws an exception.
- 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 next key value from offset on key level
odaba::Key Property :: nextKey ( odaba::Key vSortKey, int32 iKeyLevel )

The function tries to locate the next key value starting at key offset passed in vSortKey.

The switch level (iKeyLevel) allows defining the last key components that must alter. This allows e.g. reading all key values without duplicates when fixing the last key component. The key level may be also set by calling fixKeyComponents().
- 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 next instance for key level
odaba::Key Property :: nextKey ( int32 iKeyLevel )

The switch level (iKeyLevel) allows defining the last key components that must alter. This allows e.g. providing all instances without duplicate key values, when fixing the last key component.
- 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

to top Comment