Property :: changeKeyFilter - Change filter condition based on key value
The function allows applying a filter expression to the collection. The expression must be a valid expression in the context of the access key structure defined for the property handle, i.e. the condition may refer to key component attributes of the selected access key, only.
When a key filter is set, the property handle selects only those instances that return true (isTrue()) for the expression. Sequential retrievals as nextKey() or position() automatically search for the next valid instance. In contrast to the filter() function, key function as nextKey() perform much better for key filter.
The get() function that is requesting a specific instance by index or key throws an exception, when the requested instance does not fulfill the filter condition. When setting a filter for an update or write property handle, updating an instance may lead to an invalid instance (i.e. an instance not fulfilling the defined constraint). In this case, the instance is unselected after storing the updated data and an exception is thrown as well..
Setting a key filter will remove a filter or key filter previously set. In order to reset the filter condition explicitly, one may pass an empty expression string (vExpression) to the function.
In contrast to the keyFilter() setter function, the function returns a reference to itself.
A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
Implementation details
The function allows applying a key filter expression to the collection. Setting a key filter will remove a filter or key filter previously set. In order to expand the filter condition, one may call expandFilter().
In order to reset the filter condition one may pass an empty expression string in vExpression to the function.
- vExpression
- OSI inline expression
An inline expression can be passed as operation path, as operand (something like a + b) or as complete expression. As operand, an expression may contain any expression, which is allowed in a statement, but no semicolon must be appended at the end.
Complete expressions include expression header (optional) and may include different sections in the expression body which is enclosed in { ... }.
In contrast to class expressions, inline expressions are not defined explicitly as class expressions but passed as strings to the application at run-time.
In order to pass no expression, an empty string ( String() ) has to be passed.