PropertyHandle :: OrderBy - Order collection by attribute list
The collection will be ordered by key name or attributes passed in the attribute list (vExpression). When passing a key name (one element, only), the collection order is changed to the order defined for the collection.
When passing an attribute list (one or more attribute references or definitions), attributes in the attribute list must be separated by comma. When the attribute is calculated from other attributes, it has to be defined as attribute extension in the parameter list. The attribute list may refer to persistent, transient and extension attributes.
Attribute names referenced in the list but not defined in the data type are added to the property handle asattribute extensions (Property::createAttributeExtension()). Those attributes require a data type when being declared as parameter. In order to get proper key component values, the attribute extensions used in an oderBy() function call require a data source expression.
For controlling order sequence, extended options may be passed with each parameter:
- IC | IGNORE_CASE: use case-insensitive compare for key component
- DESC | DESCENDING: order component values in descending order
- NOT_EMPTY: suppress empty key values (not on component level but for whole key)
- UNIQUE: create index with unique keys. Duplicate key values will cause an exception.
When the property handle is not valid or when the attribute list contains invalid attribute definitions, the function throws an exception.
When the attribute list contains attribute definitions resulting in an extension attribute, the function will fail when being called again. In order to change the collection order to the new defined order one should refer to the key name returned by calling accessKeyDefinition.Name() or explicitly define the extension attribute before (see example).
person.orderBy("pk"); // order by defines index pk)
person.orderBy("DESC age,sex"); // order by transient key (descending age and sex)
person.orderBy("string age_group = (age < 20 ? 'young' :
age < 50 ? 'middle':
'old' ),sex");
// using explicitly defined extension attribute, instead
person.createAttributeExtension("STRING(10) age_group = ( age <= 20 ? 'young' :
age <= 50 ? 'middle': 'old') ");
person.orderBy("age_group,IC name"); // age_group is defined as transient attribute, case insensitive names
When updating collections which got an ad-hoc order (transient index), the order transient index will be maintained, too. In case of errors, however, changes made in transient indexes will not be reset (in contrast to temporary indexes). In order to avoid problems resulting from this fact, one should remove transient orders (removeOrder()) defined for a collection before updating the collection, or at least when an error han been encountered when updating the collection.
Implementation details
- attr_list
- Attribute definition list
The attribute definition list is a string containing attribute names for defined attributes or ODL attribute definitions, which, usually, got an initial value or expression assignment.
- uniopt - Indicates collection with unique entries
- empopt - Empty value allowed