UnicodeRegexMatch (Unicode function)

Position after match of regex (Unicode class)

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

This page is under construction.

Syntax

%number = unicode:UnicodeRegexMatch( regex, [Options= string], - [CaptureList= stringlist]) Throws InvalidRegex

Syntax terms

%number	A variable to return the position of the character after the last character matched, or a zero if no characters in the method object Unicode string match the regular expression.
unicode	The input Unicode string, to which the regular expression regex is applied.
regex	A Unicode string that is interpreted as a regular expression and is applied to the method object unicode to determine whether the regular expression matches unicode.
Options	This is an optional, but name required, parameter supplying a string of single letter options, which may be specified in uppercase or lowercase, in any combination, and blank separated or not as you prefer. For more information about these options, see "Common regex options". I Do case-insensitive matching between unicode and regex. S Dot-All mode: a period (.) 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 unicode. 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.
CaptureList	This argument is available for Rocket development testing purposes only. Not an ordinary user parameter.

Exceptions

UnicodeRegexMatch 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".
• UnicodeRegexMatch may be 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. UnicodeRegexMatch behaves more like a matching method if the regular expression is "anchored" (begins with a caret (^) and ends with a dollar sign ($)), or if the C option indicates XML Schema mode.

  Examples

  Finding the first position of one of several characters

  A common programming problem is to "scan" a string, and find the first position which is one of several characters. This can be readily accomplished with UnicodeRegexMatch; here is an example:

  %regex = '[aeiou]'; * Scan for any vowel %str = 'That quick brown fox' %i = %str:unicodeRegexMatch(%regex) if %i then printText Before vowel: {%str:unicodeLeft(%i - 2)} printText The vowel: {%str:unicodeChar(%i-1)} printText After vowel: {%str:unicodeSubstring(%i)}

  The result of the above fragment is:

  Before vowel: Th The vowel: a After vowel: t quick brown fox

  Notes:

  • The position returned by UnicodeRegexMatch is the position of the character after the first successful match.

  Finding the first position that is not one of several characters

  A programming task similar to that in the preceding example is finding the position of the first character that is not one of a set of characters. This task is readily accomplished with UnicodeRegexMatch. Here is an example:

  %regex = '[^aeiou]'; * Scan for any non-vowel %str = 'albatross' %i = %str:unicodeRegexMatch(%regex) if %i then printText Before non-vowel: {%str:unicodeLeft(%i - 2)} printText The non-vowel: {%str:unicodeChar(%i-1)} printText After non-vowel: {%str:unicodeSubstring(%i)}

  The result of the above fragment is:

  Before non-vowel: a The non-vowel: l After non-vowel: batross

  Notes:

  • The regex is specified with the following statement:

    %regex = '[^aeiou]'

    Comparing this to the example using circumflex for RegexMatch illustrates one benefit of UnicodeRegexMatch: since the input is Unicode,

  • The right hand side of that statement ('[' '5F':HexToString 'aeiou]') uses the implicit concatenation feature introduced in version 7.9 of the Sirius Mods.
  • This use of UnicodeRegexMatch is like the standard SOUL $Verify function, although it indicates not just whether all characters in the given string are in the regex, but also the position (plus one) of the first character that is not in the regex.

  See also

  Float class String class Unicode class	List of Float methods List of String methods List of Unicode methods List of Intrinsic methods	Float methods syntax String methods syntax Unicode methods syntax
  Notation conventions for methods