Property :: 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 as attribute 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.
A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
Implementation overview
- Order by key or attribute list
Property :: orderBy ( vParameterList ) - Order by attribute list
Property :: orderBy ( vParameterList, bUnique, bEmpty )
Implementation details
-
Order by key or attribute list
odaba::Property & Property :: orderBy ( odaba::String &vParameterList )
The function orders the collection by the key name or by an attribute list passed in vExpression . When passing an attribute list, the transient index created is not unique (may contain duplicates) and allows empty key values.
- vParameterList
- OSI parameter list
An OSI parameter list is a list of comma separated parameters. Each parameter is a name, operation path, expression or variable declaration.
first_name, // name
children.count(), // operation path
(Date() - birth_date)/365.25, // expression
int days = Date() - birth_date // variable declaration
to list
- vParameterList
- OSI parameter list
-
Order by attribute list
odaba::Property & Property :: orderBy ( odaba::String &vParameterList, bool bUnique, bool bEmpty )
The function orders the list by attributes passed in vExpression .
Notes:When passing an index name instead of a attribute list, unique and empty options will be ignored and used according to the index definition.
- vParameterList
- OSI parameter list
An OSI parameter list is a list of comma separated parameters. Each parameter is a name, operation path, expression or variable declaration.
first_name, // name
children.count(), // operation path
(Date() - birth_date)/365.25, // expression
int days = Date() - birth_date // variable declaration
- bUnique
- Unique collection
The option indicates a unique collection or index when being set to true .
- bEmpty
- Allow empty values
When this option is true , empty attributes or key values are accepted.
to list
- vParameterList
- OSI parameter list