RegexLocate and RegexLocateUp (Stringlist functions)

Find next/previous item in Stringlist that matches a regex (Stringlist class)

These callable methods use a regular expression (regex) to locate an item in the method Stringlist. They return the item number of the first item that the regex matches. Both methods proceed item-by-item through the Stringlist. RegexLocate starts, by default, from item 1, the first item in the Stringlist; or it starts from the item you specify. RegexLocateUp starts from the item n you specify and proceeds "upward" to item n-1, then n-2, and so on.

Information about the regular expression matching rules observed is provided in "Regex processing rules".

Syntax

[%itemNum =] sl:RegexLocate( regex, [startItem], [Options= string], - [Status= %output], [StartCol= number], - [EndCol= number]) Throws InvalidRegex

[%itemNum =] sl:RegexLocateUp( regex, [startItem], [Options= string], - [Status= %output], [StartCol= number], - [EndCol= number]) Throws InvalidRegex

Syntax terms

%itemNum	If specified, a numeric variable that is set to the number of the sl item matched by regex, or it is 0 if no items are matched.
sl	A Stringlist object.
regex	A string that is interpreted as a regular expression and is applied to the sl method Stringlist items to determine whether the regex finds a match.
startItem	The item number from which the regex matching is to begin. If this item is not matched, the method attempts to match the item with the next higher (if RegexLocate) or lower (if RegexLocateUp) item number, and so on. This numeric value is an optional argument that defaults to 1 (if RegexLocate) or to the number of items in sl (if RegexLocateUp). This value must not be negative and must not be greater than the number of sl items. Setting this argument to 0 is the same as setting it to 1.
Options	This is an optional, 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.
Status	The Status argument (name required) is optional; if specified, it is set to an integer code. These values are possible: n The number of the sl item that is first matched. 0 No match: no items in sl were matched by regex. -2 The startItem value is invalid (either a negative value or a value greater than the number of list items), or the method Stringlist is empty. -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 request is cancelled.
StartCol	The StartCol argument (name required) is an optional number that specifies the starting column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1 and less than or equal to the EndCol argument value. If the argument is omitted, its default value is 1. If you specify a value that is greater than the length of a particular sl item, the regex is matched against the empty string for that item.
EndCol	The EndCol argument (name required) is an optional number that specifies the ending column of the range of columns in which the matched string must be located. If the argument is specified, its value must be greater than or equal to 1, greater than or equal to the StartCol argument value, and less than or equal to 6124. If the EndCol argument is omitted, its default value is 6124. Note: If the EndCol argument is omitted and a sl item exceeds 6124 bytes, the request is cancelled.

Usage notes

• All errors in RegexLocate or RegexLocateUp, including invalid argument(s), will result in request cancellation.
• 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 SOUL programming considerations.
• The regex matching is limited to the first 6124 bytes of each item.
• The request is cancelled in any of these cases:
  • You specify an invalid argument option.
  • You omit the Status argument and a situation occurs that would cause a negative Status value.
  • You omit the EndCol argument and the length of an sl item exceeds 6124 bytes.
• For information about additional methods and $functions that support regular expressions, see Regex processing.

Examples

In the following code fragment, RegexLocate is applied to the method Stringlist %sl to find the first occurrence of the string 'CUST'. If this is successful, the containing item is copied to a new Stringlist. The matching is done case-insensitively, and the starting item is the beginning of the list, by default. Substituting RegexLocateUp for RegexLocate in the example would find the last occurrence of 'CUST'.

... %sl = new text to %sl %n = %list:findImageItem(%cust:ssn) if %n then %list:replaceImage(%n, 'CUST') else %list:addimage('CUST') end if end text %opt='i' %regex = '''cust''' %itemnum = %sl:RegexLocate(%regex, Options=%opt, Status=%st) If (%itemnum EQ 0) then Print 'Status from RegexLocate[Up] is ' %st Else Print %regex ' matches item ' %itemnum Print 'Now for %sl2 . . . ' %sl2 = new %i = %sl2:CopyItems(%sl, %itemnum, '1') %i = %sl2:Print End If ...

See also

Stringlist class	List of Stringlist methods	Stringlist methods syntax
Notation conventions for methods