This function offers a different way of filtering elements
(GOMElement
objects) provided by the source enumeration.
The idea of that filtering is the following. Each element is associated with a certain key produced from that element. The result enumeration will contain only those elements whose keys are unique. The elements from the source enumeration whose keys are repeating will be filtered out.
Precisely, the filtering works as the following:
uniqueKeyQuery
parameter.
The element is associated with that key.
prefCondQuery
parameter.
When that subquery is provided, it will be executed against the current iterated element.
If the subquery returns true
, the element associated with
the same key that was already added to the result enumeration on one of the previous steps
will be replaced with the current element.
In any other case, the function does nothing and continues with the next source element.
sourceElements
The enumeration of the source elements.Note: If this parameter is
null
, the function does nothing and returnsnull
.
uniqueKeyQuery
The subquery that will be execute for each source element to generate the element's filtering key.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
The boolean subquery that calculates the preference condition for the element.Example:When specified, this subquery will be executed for each source element whose 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 replaced with the current element in the result enumeration.If the preference condition subquery is not specified (i.e. omitted or
null
) or returnsfalse
, 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
will have the effect that for all source elements associated with the same key, only the last of them will appear in the result enumeration.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")) );
See Also:
FlexQuery(), BooleanQuery(), HashKey(), filterElements()