in

The in filter is a binary infix filter that takes either two set filters or two string filters as arguments. The argument on the left of the keyword in is the left argument; the argument on the right is the right argument:

  N in A
  "h" in "hello"

in with set filter arguments

It the left and right arguments to in are set filters, the filter matches the position if the set of squares represented by its left argument is a subset of the set of squares represented by its right argument. For example, the following code:

  A in {. attacked by a}

will match a position in which every white piece is attacked by a black piece. It is equivalent to:

  square all z in A
   z attacked by a

Note: the in filter with set arguments is rarely used and never needed in CQL. Its functionality can easily be replicated using more fundamental CQL filters, like square all , set equality (set equality) and &.

in with string filter arguments

When the left and right arguments to the in filter are both string filters, the in filter matches the position when the string value of the left argument is a substring of the string value of the right argument. The filter fails to match if either its left or right arguments fails to match:

  x="zugzwang"
  y="ug"
  x in y

The in filter does not use regular expressions

Note: "in" as a filter distinguished from "in" as a parameter

The in filter has nothing to do with the in parameters that are used with the filters piece, square and echo.

Thus, the in before the A in the examples is not related to the in filter. That usage of in before the A is instead a parameter to the square filter. It is not its own filter.

Use of the in filter with a piece variable

Use care when using the in filter with a left argument that is a piece variable. The value of the piece variable can be empty in the current position (if it was captured), which makes the in filter match the current position. To check if a piece variable represents a piece on a set of squares, use &:

  piece x in Pa-h2 //find pawns that eventually promote
   {find x in a-h8 //wrong! x might be empty (captured)
    find x&a-h8 // correct
  }

Examples

The in filter is used in modelmate.cql, where the line

  [RNBQ] in WhiteParticipants

checks that each white non-pawn non-King piece is a member of the set represented by the user variable named WhiteParticipants, as in the following position: Korolkov 1937, after 8. c8N model mate
(found from CQL file: modelmate.cql)

Here, [RNBQ] is the same N, which also represents the white pieces participating in the mate.