Finds an element in the specified array or vector according to the specified condition.

The function iterates by all elements (starting from the first one) and on each step assigns the current element to a special external variable, whose reference is passed in the elemVar parameter (using special '@' operator). That variable is also accessible within the subquery specified in acceptQuery parameter. The function executes that subquery for each element. When it returns true for some element, the iterations stop and the function returns the index of that element. If the subquery returned false for all elements, the function return -1.

Basically, the function works as the following pseudo code:


index = 0;
while (index < a.length())
{
  elem_var = a[index];

  if ({ acceptQuery operators })
    return index;

  index = index + 1;
}

return -1;

Parameters:

a / v

Specifies the array or vector to be searched in.

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

elemVar
The reference to the variable via which the current iterated element is passed to the subquery.

The variable reference must be produced using '@' operator (see example below).

acceptQuery
Specifies the subquery that implements the acceptance condition for the elements.

This should be a boolean subquery created with BooleanQuery() function. The subquery will be processed against each iterated element. It must return true when the element complies with some necesary condition and false otherwise.

Returns:

The index of the found element (i.e. the first element that complies with acceptQuery) or -1, if no such elements has been found.

See Also:

BooleanQuery()

Example:

The following expression finds the first non-null element in the array passed in 'a' variable:


search (
  a, 
  @el,
  BooleanQuery (el != null)
)