This function offers a different way of filtering elements (GOMElement
objects) provided by a source enumeration.
The idea of that filtering is the following. Each element is associated with a certain filtering key produced by that element. The result enumeration will contain only those elements whose filtering keys are unique. Those elements from the source enumeration whose filtering keys are repeating will be skipped over.
Precisely, the filtering works as follows:
filterKeyQuery
parameter.
The element is associated with that key.
prefCondQuery
parameter.
When that subquery is provided and it returns true
, the element associated with
the same key and added on one of the previous steps will be deleted from the result enumeration.
The current element will be added instead.
Otherwise, the iterations just proceed to the next source element.
sourceElements
Note: If this parameter is null
, the function does nothing
and returns null
.
filterKeyQuery
The element is passed to the subquery as the generator context element.
The value returned by the subquery should be an object good to be a hash key.
The null
value is also allowed.
The subquery may be created using FlexQuery()
function.
Note: If this parameter is null
, the function does nothing
and returns the original enumeration.
Note: When you need to filter elements by several keys
with different types so that only the whole set of keys generated for each element
must be unique, you can do it by creating a single compound filtering key
using HashKey()
function.
prefCondQuery
When specified, this subquery will be executed for each source element whose filtering key is repeating (that is, when there was an early processed element with the same key).
The element is passed to the subquery as the generator context element.
If the subquery returns true
, the old element
will be deleted from the result enumeration and the current element added instead.
If the preference condition subquery is not specified (i.e. omitted or
null
) or returns false
, the current element
with the repeating key will be filtered out (removed from the result enumeration).
The subquery may be created using BooleanQuery()
function.
For example, specifying in this parameter the subquery
BooleanQuery(true)
This expression will return an enumeration produced from the source one in which
all elements with the repeating value of "name"
attribute are removed:
e.filterElementsByKey (
FlexQuery (getAttrValue("name"))
);
FlexQuery(), BooleanQuery(), HashKey(), filterElementGroupsByKey()