$RegexMatch

Whether string matches regex

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $RegexMatch function is the RegexMatch String function.

This function determines whether a given pattern (regular expression, or "regex") matches within a given string according to the "rules" of regular expression matching. (Information about the rules observed is provided in Regex rules).

$RegexMatch accepts two required and two optional arguments, and it returns a numeric value. It is also callable. Specifying an invalid argument results in request cancellation.

Syntax

[%rc =] $RegexMatch(inStr, regex, [options], [%status])

Syntax terms

%rc	a number that is either 0 (if the regular expression was invalid or no match was found) or the position of the character after the last character matched.
instr	The input string, to which the regular expression regex is applied. This is a required argument.
regex	A string that is interpreted as a regular expression and is applied to the inStr argument to determine whether the regex matches inStr. This is a required argument.
options	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 instr 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. For more information, see XML Schema mode.
%status	The fourth argument is optional; if specified, it is set to an integer status value. These values are possible: ' 1 A successful match was obtained. 0 No match: inStr was not matched by regex. -1nnn The pattern in regex is invalid. nnn, the absolute value of the return minus 1000, gives the 1-based position of the character being scanned when the error was discovered. The value for an error occurring at end-of-string is the length of the string + 1. Note: If you omit this argument and a negative %status value is to be returned, the run is cancelled.

Usage notes

• It is strongly recommended that you protect your environment from regex processing demands on PDL and STBL space by setting, say, UTABLE LPDLST 3000 and UTABLE LSTBL 9000. For further discussion of this, see SOUL programming considerations.
• $RegexMatch is considered Longstring-capable. Its string inputs and outputs are considered Longstrings for expression-compilation purposes, and they have standard Longstring truncation behavior: truncation by assignment results in request cancellation. For more information, see Longstrings and $functions.
• If %rc is zero, either regex did not match inStr, or there was an error in the regex. The %status argument returns additional information. If it is negative, it indicates an error. If it is zero, it indicates there was no error, but the regex did not match.
• For information about additional methods and $functions that support regular expressions, see Regex processing.

Examples

The following example tests whether the regex \*bc?[5-8] matches the string a*b6. If the return code is 0 (no match), the status variable is checked for more information.

Begin %rc float %regex Longstring %String Longstring %Options string len 10 %status float %Options = %regex = '\*bc?[5-8]' %String = 'a\*b6' %rc = $RegexMatch (%String, %regex, %Options, %status) If (%rc EQ 0) then Print 'Status from $RegexMatch is ' %status Else Print %regex ' matches ' %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.

Products authorizing $RegexMatch

• Sirius Functions