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 ♖a3

find always starts its search at the currentposition.

If find is followed by the keyword quiet, automatically generated comments are suppressed 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 find or find all is followed by a left arrow <-- then the find looks backward in the game tree instead of forward:

find <-- filter

Note: do not confuse the left arrow <-- with the left attack arrow →.

comments in find

By default, find will comment on found positions. This can be turned off by specifying quiet in the CQL header, or if quiet is a parameter to find.

      find quiet check

Examples

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