RegexMatch (String function)

This intrinsic function determines whether a given pattern (regular expression, or "regex") matches within a given string according to the "rules" of regular expression matching.

RegexMatch is available as of version 7.2 of the Sirius Mods.

RegexMatch syntax

  %pos = string:regexMatch(regex, [Options=opts])                                                     

Syntax Terms

%pos

A variable to receive the position of the character after the last character matched, or a zero if no characters in the method object string match the regular expression.

string

The input string, to which the regular expression regex is applied.

regex

A string that is interpreted as a regular expression and is applied to the method object string to determine whether the regex matches string.

Options=opts

The Options argument (name required) is an optional string of options. The options are single letters, which may be specified in uppercase or lowercase, in any combination, and separated by blanks or not separated. For more information about these options, see Common regex options.

I

Do case-insensitive matching between string and regex.

S

Dot-All mode: a dot ('.') can match any character, including carriage return and linefeed.

M

Multi-line mode: let anchor characters match end-of-line indicators wherever the indicator appears in the input string. M mode is ignored if C (XML Schema) mode is specified.

C

Do the match according to XML Schema regex rules. Each regex is implicitly anchored at the beginning and end, and no characters serve as anchors.

Exceptions

This intrinsic function can throw the following exceptions:

InvalidRegex

If the regex parameter does not contain a valid regular expression. The exception object indicates the position of the character in the regex parameter where it was determined that the regular expression is invalid, and a description of the nature of the error.

Usage Notes

• It is strongly recommended that you protect your environment from regular expression processing demands on PDL and STBL space by setting, say, 'UTABLE LPDLST 3000' and 'UTABLE LSTBL 9000'. See User Language programming considerations.
• For information about additional methods that support regular expressions, see Regex Processing.
• RegexMatch is something of a misnomer. It does not determine if a string matches a regular expression, it determines if a string contains a substring that matches a regular expression. RegexMatch behaves more like a matching method if the regular expression is "anchored" (begins with a caret ('&circ.') and ends with a dollar sign ('$'), or if the C option indicates XML Schema mode.

Examples

The following example tests whether the regex '\*bc?[5-8]' contains a substring that matches 'a*b6'.

   begin                                                                              
     %rc float                                                                        
     %regex Longstring                                                                
     %string Longstring                                                               
                                                                                      
     %regex = '\*bc?[5-8]'                                                            
     %string = 'a\*b6'                                                                
                                                                                      
     %rc = %string:regexmatch(%regex)                                                 
     if %rc then                                                                      
        printText '{%regex}' matches '{%string}'              
     else                                                                             
        printText '{%regex}' does not match '{%string}'                               
     end if                                                                           
   end                                                                                
                                                                                      

The regex matches the input string; the example result is:

   '\*bc?[5-8]' matches 'a\*b6'                                                       
                                                                                      

This regex demonstrates the following:

• To match a string, a regex pattern must merely "fit" a substring of the string.
• Metacharacters, in this case star ('*'), must be escaped.
• An optional character ('c?') may fail to find a match, but this does not prevent the success of the overall match.
• The character class range ('[5-8]') matches the '6' in the input string.

See also

List of Intrinsic String Methods