xf:matches

Compares $string-var1 against the regular expression in string-var2.

If any character besides m or i is specified in $string-var3 (the flags string), the TransformException exception is raised with the RT_REGEXP_FLAGS fault code. In the mapper, the following error is displayed:

Error occurred while executing XQuery: Invalid regular expression syntax (flags: "a") 

If the value of $string-var1, $string-var2, or $string-var3 is the empty sequence, the empty sequence is returned. The empty sequence is a sequence containing zero items (), which is similar to null in SQL.

To learn more about using fault codes, see Getting the TransformException Fault Code Programmatically.

If $string-var2 (the regular expression string) has no anchors and is found anywhere in $string-var1 (the source string), the regular expression string is considered to match and the boolean true is returned. (To learn more, see the following String Matches Example.) However, if anchors (^ $) are used in $string-var2 (the regular expression string), the anchors must match the start/end of either the string (for string mode) or line (for multiline mode). (To learn more, see the following Beginning Anchor Matches and Beginning Anchor Does Not Match Examples.)

Signatures

xf:matches(xs:string? $string-var1, xs:string? $string-var2) —> xs:boolean?

xf:matches(xs:string? $string-var1, xs:string? $string-var2, xs:string? $string-var3) —> xs:boolean?

Arguments

Data Type
Argument
Description

xs:string?

$string-var1

Represents the source string.

xs:string?

$string-var2

Represents the regular expression string. To learn more, see W3C Regular Expresssions.

xs:string?

$string-var3

Specifies flags that affect the comparison to the regular expression. (Optional)



m

If specified the match operates in multiline mode. Otherwise, the match operates in string mode.

i

If specified the match operates in case-insensitive mode. By default, the match operates in case-sensitive mode.

Returns

Returns the boolean true if $string-var1 matches the regular expression supplied in $string-var2.

Returns the boolean false if $string-var1 does not matches the regular expression suppled in $string-var2.

Examples

Regular Expression Matches

Invoking matches("abc", "[cxy]") returns the boolean true because the character c of the regular expression [cxy] is found in the source string abc, as shown in the following example query:

<result>{xf:matches("abc", "[cxy]")}</result> 

The preceding query generates the following result:

<result>true</result> 

Regular Expression Does Not Match

Invoking matches("abc", "[xy]") returns the boolean false because none of the characters in the regular expression [xy] are in the source string abc, as shown in the following example query:

<result>{xf:matches("abc", "[xy]")}</result> 

The preceding query generates the following result:

<result>false</result> 

String Matches

Invoking matches("uvwxyz", "xyz") returns the boolean true because the regular expression string xyz is found in the source string uvwxyz, as shown in the following example query:

<result>{xf:matches("uvwxyz", "xyz")}</result> 

The preceding query generates the following result:

<result>true</result> 

Beginning Anchor Matches

Invoking matches("uvwxyz", "^uv") returns the boolean true because the source string uvwxyz does start with the string uv, as shown in the following example query:

<result>{xf:matches("uvwxyz", "^uv")}</result> 

The preceding query generates the following result:

<result>true</result> 

Note: The regular expression ^uv specifies that source string must start with the string uv to be a successful match.

Beginning Anchor Does Not Match

Invoking matches("uvwxyz", "^yz") returns the boolean false because the source string uvwxyz does not start with the string yz, as shown in the following example query:

<result>{xf:matches("uvwxyz", "^yz")}</result> 

The preceding query generates the following result:

<result>false</result> 

Note: The regular expression ^yz specifies that source string must start with the string yz to be a successful match.

Ending Anchor Matches

Invoking matches("uvwxyz", "yz$") returns the boolean true because the source string uvwxyz does end with the string uv, as shown in the following example query:

<result>{xf:matches("uvwxyz", "yz$")}</result> 

The preceding query generates the following result:

<result>true</result> 

Note: The regular expression yz$ specifies that source string must end with the string yz to be a successful match.

Ending Anchor Does Not Match

Invoking matches("uvwxyz", "vw$") returns the boolean false because the source string uvwxyz does not end with the string yz, as shown in the following example query:

<result>{xf:matches("uvwxyz", "vw$")}</result> 

The preceding query generates the following result:

<result>false</result> 

Note: The regular expression yz$ specifies that source string must end with the string yz to be a successful match.

Case-Insensitive Mode

Invoking matches("aBc", "abc", "i") returns the boolean true because the source string aBc does contain the string abc, if you ignore the case of the strings, as shown in the following example query:

<result>{xf:matches("aBc", "abc", "i")}</result> 

The preceding query generates the following result:

<result>true</result> 

Pass in Null

Invoking matches("abc", ()) returns the null string as shown in the following example query:

<result>{xf:matches("abc", ())}</result> 

Note: The string: () is the empty sequence (similar to a SQL null) which is a sequence containing zero items.

The preceding query generates the following result:

<result/> 

Related Topics

W3C matches function description.

W3C Regular Expressions description.