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:

  1. The function iterates by all element from the source enumeration.
  2. For each element, the function generates a key using the subquery provided in uniqueKeyQuery parameter. The element is associated with that key.
  3. Using a special hashmap, the function checks if such a key was already produced on one of the previous iterations.
  4. If not, the element is added to the result enumeration and the function goes to the next element.
  5. When that key has been already generated, the function tests the preference condition, which is calculated by the boolean subquery specified in 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.

Parameters:

sourceElements

The enumeration of the source elements.

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

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.

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