find

find is used to search for positions that match a specified filter. The find filter has one argument, the filter to search for.

    find check
    x= 1 + find all check
    find Ra3

find always starts its search at the currentposition.

The first form of find is used to locate a position in which a given filter is true:

find filter

This form of the find filter matches the current position if some future position (always including the current position of course) matches filter. If the find filter does find such a position, that position is returned as the value of the find filter. The find filter stops searching the positions when the first such position is found.

The second form of find is used to find all positions matching a specified filter:

find all filter

The presence of the all parameter to find indicates that the find returns a count of the number of future positions matching filter.However, the find filter will only match if this count is nonzero.

For example,

      find check

Will match the next position (starting its search from the current position) that is a check. The value of the find filter, if it matches, is that position.

On the other hand,

      find all check

will return the number of future positions that are checks (including the current positions), if that value is nonzero.

A variant of this form allows a range to be specified:

find range filter

This form matches the position if the number of future positions matching filter lies within range.

Thus,

      x=find 0 1000 check

will set x to the number of future positions that are checks.

searching backward

If the keyword find is immediately followed by a left arrow <-- then the find looks backward in the game tree instead of forward:

find <-- filter

comments in find

By default, find will comment on found positions. This can be turned off by specifying quiet in the CQL header.

Examples

The find filter is used in Qq-rotations-90-degree.cql, Qq-rotations.cql, averagedistance.cql, excelsior-comment.cql, excelsior-multiple.cql, excelsior-return.cql, excelsior-simple.cql, most-visited-square.cql, most-visited-square-2.cql, parallelpaths-simple.cql, parallelpaths.cql, platzwechseln1.cql, platzwechseln2.cql, rook-corners-1.cql, rook-corners-2.cql, rook-corners-rotate-with-range.cql.