Caché ObjectScript Reference
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   

Matches a regular expression to a string.
string The string to be matched.
regexp A regular expression to match against string. A regular expression consists of one or more meta-characters, and may also contain literal characters.
$MATCH is a boolean function that returns 1 if string and regexp match, and 0 if string and regexp do not match. By default, matching is case-sensitive.
ObjectScript support for regular expressions consists of the $LOCATE and $MATCH functions:
The Match() method of the %Regex.Matcher class provides the same functionality. The %Regex.Matcher class provides additional functionality for using regular expressions.
Other ObjectScript matching operations use Caché pattern match operators.
An expression that evaluates to a string. The expression can be specified as the name of a variable, a numeric value, a string literal, or any valid ObjectScript expression. A string can contain control characters.
A regular expression used to match against string. A regular expression is an expression that evaluates to a string consisting of some combination of meta-characters and literals. Meta-characters specify character types and match patterns. Literals specify one or more matching single characters, ranges of characters, or substrings. An extensive regular expression syntax is supported. For details, refer to the Regular Expressions chapter of Using Caché ObjectScript .
The following example matches a string with a regular expression that specifies that the first character must be an uppercase letter (\p{LU}), followed by at least one additional character (+ quantifier), and that this second character, and all subsequent characters, must be word characters (letters, numbers, or the underscore character) (\w):
   SET strng(1)="Assembly_17"
   SET strng(2)="Part5"
   SET strng(3)="SheetMetalScrew"
   SET n=1
  WHILE $DATA(strng(n)) {
    IF $MATCH(strng(n),"\p{LU}\w+")
      { WRITE strng(n)," : successful match",! }
    ELSE { WRITE strng(n)," : invalid string",! }
    SET n=n+1 }
The following example returns 1, because the hexadecimal regular expression (hex 41) matches the letter “A”:
   WRITE $MATCH("A","\x41")
The following example returns 1, because the specified string matches the format of spaces (\s) and non-space characters (\S) specified in the regular expression:
   WRITE $MATCH("A# $ 4","\S\S\s\S\s\S")
The following example returns 1, because the specified date matches the format of digits and literals specified in the regular expression:
   WRITE $MATCH(today,"^\d\d/\d\d/\d\d\d\d$")
Note that this format requires that the day and month each be specified as two digits, so a leading zero is required for values smaller than 10.
The following example returns 1, because each letter in the string is within the corresponding letter range in the regular expression:
   WRITE $MATCH("HAL","[G-I][A-C][K-Z]")
The following example specifies an invalid regexp parameter. This results in an error, as shown:
   TRY {
   SET str="abcdef"
   WRITE "match=",$MATCH(str,"\p{}"),!
  CATCH exp {
    WRITE !!,"CATCH block exception handler:",!
    IF 1=exp.%IsA("%Exception.SystemException") {
      WRITE "System exception",!
      WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
      WRITE "Location: ",exp.Location,!
      WRITE "Code: ",exp.Code,!! 
      WRITE "%Regex.Matcher status:"
      SET err=##class(%Regex.Matcher).LastStatus()
      DO $SYSTEM.Status.DisplayError(err) }
    ELSE {WRITE "Unexpected exception type",! }
See Also