DB2 Version 9.7 for Linux, UNIX, and Windows

matches function

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

Syntax


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

source-string

A string that is compared to a pattern.

source-string is 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, wildcards, and operators that define a string or group of strings in a search pattern.

pattern is an xs:string value.

flags

An xs:string value 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 (X'0A').
m: Indicates that the caret (^) matches the start of a line (the position after a new line character), and the dollar sign ($) matches the end of a line (the position before a new line character).
If the m flag is not specified, the caret (^) matches the start of the string, and the dollar sign ($) matches the end of the string.
i: Indicates that matching is case-insensitive.
If the i flag is not specified, case-sensitive matching is done.
x: Indicates that whitespace characters within pattern are ignored.
If the x flag is not specified, whitespace characters are used for matching.

Limitation of length

The length of source-string and pattern is limited to 32000 bytes.

Returned value

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

If pattern does not contain the string- or line-starting character caret (^), or the string- or line-ending character dollar sign ($), source-string matches pattern if any substring of source-string matches pattern. If pattern contains the string- 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- 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 the match occurs from the beginning of the string or the beginning of a line.

If source-string is the empty sequence, the returned value is false.

Examples

Example of matching a pattern to any substring within a string: The following function determines whether the characters "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 characters "ac" or "bd" match the string "bd".

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

The returned value is true.

Example of ignoring spaces and capitalization when matching a pattern: The following function uses the i and x flags to ignore capitalization and spaces when determining whether the string "abc1234" matches the pattern "ABC 1234."

fn:matches("abc1234","ABC 1234", "ix")

The returned value is true.