PropertyHandle :: SetFilter - Set selection (filter) condition

The function allows applying a filter expression to the collection. The expression must be a valid expression in the context of the structure defined for the property handle. When a filter is set, the property handle selects only those instances that return true (-> IsTrue ()) for the expression. Sequential retrievals as NextKey (), operators ++ and -- or Position() automatically search for the next valid instance. The Get () function that is requesting a specific instance by index or key returns an empty instance 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.

Setting a filter condition slows down key operations as e.g. NextKey (), since for checking the condition, the instance must be read. When a condition is based on key component attributes, only, performance can be improved by calling SetKeyFilter () instead.

Setting a filter will remove a filter or key filter previously set. You may also reset the filter by calling ResetFilter ().