fn:matches

fn:matches(
    $input as xs:string?, 
    $pattern as xs:string
) as xs:boolean

fn:matches(
    $input as xs:string?, 
    $pattern as xs:string, 
    $flags as xs:string
) as xs:boolean

This function is deterministic, context-independent, and focus-independent.

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string. Flags are defined in Flags.

If $input is the empty sequence, it is interpreted as the zero-length string.

The function returns true if $input or some substring of $input matches the regular expression supplied as $pattern. Otherwise, the function returns false. The matching rules are influenced by the value of $flags if present.

A dynamic error is raised [ERRFORX0002] if the value of $pattern is invalid according to the rules described in Regular expression syntax.

A dynamic error is raised [ERRFORX0001] if the value of $flags is invalid according to the rules described in Flags.

Unless the metacharacters ^ and $ are used as anchors, the string is considered to match the pattern if any substring matches the pattern. But if anchors are used, the anchors must match the start/end of the string (in string mode), or the start/end of a line (in multi-line mode).

This is different from the behavior of patterns in [XML Schema Part 2: Datatypes Second Edition], where regular expressions are implicitly anchored.

Regular expression matching is defined on the basis of Unicode code points; it takes no account of collations.

The expression fn:matches("abracadabra", "bra") returns true().

The expression fn:matches("abracadabra", "^a.*a$") returns true().

The expression fn:matches("abracadabra", "^bra") returns false().

Given the source document:

let $poem := 
<poem author="Wilhelm Busch">
Kaum hat dies der Hahn gesehen,
Fängt er auch schon an zu krähen:
Kikeriki! Kikikerikih!!
Tak, tak, tak! - da kommen sie.
</poem>

the following function calls produce the following results, with the poem element as the context node:

The expression fn:matches($poem, "Kaum.*krähen") returns false().

The expression fn:matches($poem, "Kaum.*krähen", "s") returns true().

The expression fn:matches($poem, "^Kaum.*gesehen,$", "m") returns true().

The expression fn:matches($poem, "^Kaum.*gesehen,$") returns false().

The expression fn:matches($poem, "kiki", "i") returns true().