fn:matches function

The fn:matches function determines whether a string matches a given pattern.

Syntax


>>-fn:matches(source-string,pattern-+--------+-)---------------><
                                    '-,flags-'

source-string

A string that is compared to a pattern.

source-string is a literal string, or an XQuery expression that resolves to an xs:string value or the empty sequence.

pattern

A regular expression that is compared to source-string. A regular expression is a set of characters, pattern-matching characters, and operators that define a string or group of strings in a search pattern.

pattern is string literal.

flags

A string literal that can contain any of the following values that control matching of pattern to source-string:

s: Indicates that the dot (.) matches any character.
If the s flag is not specified, the dot (.) matches any character except the new line character (#x0A).
m: Indicates that the caret (^) matches the start of any line (the position after a new line character), and the dollar sign ($) matches the end of any line (the position before a new line character).
If the m flag is not specified, the caret (^) matches the start of the entire string, and the dollar sign ($) matches the end of the entire string.
i: Indicates that matching is case-insensitive for the letters "a" through "z" and "A" through "Z".
If the i flag is not specified, case-sensitive matching is done.
x: Indicates that whitespace characters (#x09, #x0A, #x0D, and #x20) within pattern are ignored, unless they are within a character class. Whitespace characters in a character class are never ignored.
If the x flag is not specified, whitespace characters are used for matching.

Returned value

If source-string is not the empty sequence, the returned value is an xs:boolean value that is true if source-string matches pattern. The returned value is false if source-string does not match pattern.

The rules for matching are:

If pattern does not contain the string-starting or line-starting character caret (^), or the string-ending or line-ending character dollar sign ($), source-string matches pattern if any substring of source-string matches pattern.
If pattern contains the string-starting or line-starting character caret (^), source-string matches pattern only if source-string matches pattern from the beginning of source-string or the beginning of a line in source-string.
If pattern contains the string-ending or line-ending character dollar sign ($), source-string matches pattern only if source-string matches pattern at the end of source-string or at the end of a line of source-string.
The m flag determines:
- Whether a match occurs from the beginning of the string or the beginning of a line
- Whether a match occurs from the end of the string or the end of a line.

If source-string is the empty sequence, source-string is considered to be a string of length 0, and source-string matches pattern if pattern matches a string of length 0.

Examples

Example of matching a pattern to any substring within a string: The following function determines whether the strings "ac" or "bd" appear anywhere within the string "abbcacadbdcd".

fn:matches("abbcacadbdcd","(ac)|(bd)")

The returned value is true.

Example of matching a pattern to an entire string: The following function determines whether the strings "ac" or "bd" match the string "bd". The caret (^) character and the dollar sign ($) character indicate that the match must start at the beginning of the source string and end at the end of the source string.

fn:matches("bd","^(ac)|(bd)$")

The returned value is true.