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:

  1. All element from the source enumeration are iterated.
  2. For each element, a filtering key is generated using the subquery provided in filterKeyQuery parameter. The element is associated with that key.
  3. By a special hashmap, the key is checked if an equal key has been already produced on one of the previous iterations. If not, the element is added to the result enumeration and the iterations proceed to the next source element.
  4. When such a key has been already generated, the preference condition is tested that is calculated against the current iterated element by the boolean subquery specified in 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.

Parameters:

sourceElements

The enumeration of source elements.

Note: If this parameter is null, the function does nothing and returns null.

filterKeyQuery
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.

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)
will have the effect that for all source elements associated with the same filtering key, only the last of them will appear in the result enumeration.
Example:

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(), filterElementGroupsByKey()