str

The str filter has a list of arguments enclosed in parentheses. Its value is the concatenation of the result of converting each of its arguments into strings.

The str filter uses exactly the same conventions for string conversions as do message and comment.

The str filter always matches the current position.

    X=str("pin") // X is "hello"
    X=str("pin" "mate" 43) // X is "pinmate43"
    X=str(2<1 K) // X is "<false>e1" (if K is on e1)
    X=str("pin" \n "mate") // these words are separated by newlines

As with message and comment, parentheses may be omitted if str has only one argument:

    X="pin"
    str X ≡ "pin"

implicit search parameter; fen special treatment

When a quoted string appears after a filter that is an argument to str, it can be unclear whether the quoted string is intended to be a parameter to the filter or an argument to str. For example, consider

    message(site "is Malta")

The filter site "is Malta" is true when "is Malta" is a substring of the site, that is, site "isMalta" is a single filter, and the message filter thus has a single argument.

Most of the time this behavior is unwanted. CQL interprets quoted strings after certain filters specially to make sure that the quoted string is considered to be an argument to str and not a parameter to the filter.

More formally, Suppose F is a filter that takes an implicit search parameter. Let L be a string literal. Then

    str(F L)
    ≡
    str({F} L)

For example,

    message (player white " is playing white")

will output the name of the player playing white, because the arguments are parsed as

    message ({player white} " is playing white")

and not as

    message({player white " is playing white"})
       ≡
    message(" is playing white" in player white)

The effect of the last previous message above would be to output the string <false> since the string " is playing white" is presumably not substring of the value of player white.

The fen filter is likewise parsed so as to interpret its quoted string argument, if any, as being an argument to the str not to the fen:

    str(fen L)
     ≡
    str ({fen} L)

In practice, this is the natural and expected behavior virtually all the time, and does not to be considered explicitly by the user.