$RegexMatch

Whether string matches regex

Most Sirius $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 ). The function is available as of Version 6.9 of the Sirius Mods.

Syntax

<section begin="syntax" /> [%rc =] $RegexMatch(inStr, regex, [options], [%status]) <section end="syntax" />

$RegexMatch Function

%rc, if specified, is 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.

$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.

• The first argument is the input string, to which the regular expression regex is applied. This is a required argument.
• The second argument is 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.
• The third argument 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

  
  

  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. For more information,

• The fourth argument is optional; if specified, it is set to an integer status value. These values are possible:

  &thinsp.1	A successful match was obtained.
  &thinsp.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. Prior to Version 7.0 of the Sirius Mods, an invalid regex results in a status value of -1. Note: If you omit this argument and a negative status value is to be returned, the run is cancelled.

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,
• $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,
• 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,

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.

$RegexMatch is available as of Version 6.9.

• Sirius functions

Products authorizing $RegexMatch