Locate and LocateUp (Regex function): Difference between revisions
Jump to navigation
Jump to search
m (Alex moved page Locate (Regex function) to Locate and LocateUp (Regex function)) |
No edit summary |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Regex:Locate subtitle}} | {{Template:Regex:Locate subtitle}} | ||
These functions search a [[Stringlist_class|Stringlist]] for an item that matches the regular expression in the <var>Regex</var> object. <var>Locate</var> searches forward (low to high item number) in the <var>Stringlist</var> while <var>LocateUp</var> searches backward. These provide similary functionality to [[RegexLocate and RegexLocateUp (Stringlist functions)|RegexLocate and RegexLocateUp]]. | |||
==Syntax== | ==Syntax== | ||
{{Template:Regex:Locate syntax}} | {{Template:Regex:Locate syntax}} | ||
{{Template:Regex:LocateUp syntax}} | |||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%itemNum</th><td>number</td></tr> | <tr><th>%itemNum</th><td>The first matching item number. If no items match, 0 (zero) is returned.</td></tr> | ||
<tr><th>regex</th> | <tr><th>regex</th> | ||
<td><var>Regex</var> object</td></tr> | <td>The <var>Regex</var> object</td></tr> | ||
<tr><th> | <tr><th>sl</th> | ||
<td><var>Stringlist</var> | <td>The <var>Stringlist</var> to be searched</td></tr> | ||
<tr><th>startItem</th> | <tr><th>startItem</th> | ||
<td>number< | <td>The item number at which to start searching. If 0 (the default), searching begins from the first item for <var>Locate</var> and the last item for <var>LocateUp</var>. Otherwise, <var>startItem</var> must be a number from 1 to the number of items in the <var>Stringlist</var>, inclusive.</td></tr> | ||
<tr><th><var>StartCol</var></th> | <tr><th><var>StartCol</var></th> | ||
<td>number | <td>The starting column number (position in stringlist items) to which to limit the match. The default value of this argument is 1. This value must be greater than or equal to 1 and less than or equal to 6124.</td></tr> | ||
<tr><th><var>EndCol</var></th> | <tr><th><var>EndCol</var></th> | ||
<td>number | <td>The ending column number (position in stringlist items) to which to limit the match. There is no default value of this argument so essentially matching is done to the end of each item. This value must be greater than or equal to <var>StartCol</var> and less than or equal to 6124.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | |||
<li>These functions have identical functionality to the ][RegexLocate and RegexLocateUp (Stringlist functions)|Stringlist RegexLocate and RegexLocateUp]] functions.</li> | |||
<li>Invalid values for parameters (such as start column greater than end column) result in request cancellation.</li> | |||
<li>If <var>EndCol</var> was not specified and a <var>Stringlist</var> item longer than 6124 bytes is encountered, the request is canceled.</li> | |||
</ul> | |||
==Examples== | ==Examples== | ||
The following example removes all items that match regular expression <code>"(foo|fu)bar"</code> (case insensitive) from a <var>Stringlist</var>: | |||
<p class="code">%num is float | |||
%regex is object regex | |||
%sl is object stringlist | |||
... | |||
%regex = new("(fu|foo)bar", options="i") | |||
%num = 1 | |||
repeat while %num le %sl:count | |||
%num = %regex:locate(%sl, %num) | |||
if %num eq 0 then loop end; end if | |||
%sl:removeItem(%num) | |||
end repeat | |||
</p> | |||
==See also== | ==See also== | ||
{{Template:Regex:Locate footer}} | {{Template:Regex:Locate footer}} | ||
[[Category:Regular expression processing]] | |||
Latest revision as of 21:07, 24 March 2022
Find next item in Stringlist that matches a regex (Regex class)
These functions search a Stringlist for an item that matches the regular expression in the Regex object. Locate searches forward (low to high item number) in the Stringlist while LocateUp searches backward. These provide similary functionality to RegexLocate and RegexLocateUp.
Syntax
[%itemNum =] regex:Locate( sl, [startItem], [StartCol= number], - [EndCol= number])
[%itemNum =] regex:LocateUp( sl, [startItem], [StartCol= number], - [EndCol= number])
Syntax terms
| %itemNum | The first matching item number. If no items match, 0 (zero) is returned. |
|---|---|
| regex | The Regex object |
| sl | The Stringlist to be searched |
| startItem | The item number at which to start searching. If 0 (the default), searching begins from the first item for Locate and the last item for LocateUp. Otherwise, startItem must be a number from 1 to the number of items in the Stringlist, inclusive. |
| StartCol | The starting column number (position in stringlist items) to which to limit the match. The default value of this argument is 1. This value must be greater than or equal to 1 and less than or equal to 6124. |
| EndCol | The ending column number (position in stringlist items) to which to limit the match. There is no default value of this argument so essentially matching is done to the end of each item. This value must be greater than or equal to StartCol and less than or equal to 6124. |
Usage notes
- These functions have identical functionality to the ][RegexLocate and RegexLocateUp (Stringlist functions)|Stringlist RegexLocate and RegexLocateUp]] functions.
- Invalid values for parameters (such as start column greater than end column) result in request cancellation.
- If EndCol was not specified and a Stringlist item longer than 6124 bytes is encountered, the request is canceled.
Examples
The following example removes all items that match regular expression "(foo|fu)bar" (case insensitive) from a Stringlist:
%num is float %regex is object regex %sl is object stringlist ... %regex = new("(fu|foo)bar", options="i") %num = 1 repeat while %num le %sl:count %num = %regex:locate(%sl, %num) if %num eq 0 then loop end; end if %sl:removeItem(%num) end repeat