Match (Regex function): Difference between revisions
Jump to navigation
Jump to search
(Automatically generated page update) |
No edit summary |
||
| Line 1: | Line 1: | ||
{{Template:Regex:Match subtitle}} | {{Template:Regex:Match subtitle}} | ||
This | This function tests a Unicode or EBCDIC string against the regular expression in the <var>Regex</var> object. It can also return the contents of cpturing groups to a [[Stringlist_class|Stringlist]]. | ||
==Syntax== | ==Syntax== | ||
{{Template:Regex:Match syntax}} | {{Template:Regex:Match syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%number</th><td> | <tr><th>%number</th><td>The position in the string after the match. If the string does not match the regular expression, 0 is returned. If the regular expressions matches up to the end of the string, the lenght of the string plus one 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>string</th> | <tr><th>string</th> | ||
<td>string</td></tr> | <td>The Unicode or EBCDIC string to test against the <var>Regex</var> object.</td></tr> | ||
<tr><th><var>start</var></th> | <tr><th><var>start</var></th> | ||
<td>number<br/>The default value of | <td>number<br/>The starting position. This value must be between 1 and the length of <var>string</var> plus 1. The default value is 1, which means to start at the beginning of the string.</td></tr> | ||
<tr><th><var>capture</var></th> | <tr><th><var>capture</var></th> | ||
<td><var>Stringlist</var> object | <td>A <var>Stringlist</var> object that is to receive the capturing group contents if there is a match. Each added item represents a capturing group's value with items added in capturing group order.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | |||
<li>There is no <var>Capture</var> method for the <var>Regex</var> class since <var>Match</var> provides capture functionality.</li> | |||
<li>An advantage of this method over the [[RegexMatch (String function)|String RegexMatch method]] is that this method has a start position parameter.</li> | |||
</ul> | |||
==Examples== | ==Examples== | ||
The following illustrates how a loop can find all occurrences of a particular pattern in a string and to add those occurrences to a <var>Stringlist</var>: | |||
<p class="code">%pos is float | |||
%matches is object stringlist | |||
%regex is object regex | |||
%str is longstring | |||
... | |||
%regex = new("(<[^>]+>)") | |||
%pos = 1 | |||
%matches = new | |||
repeat while %pos | |||
%pos = %regex:match(%str, start=%pos, capture=%matches) | |||
end repeat | |||
</p> | |||
Note that no special check is required for a zero-length string – 1 is a valid start position for a zero-length string and the first <var>Match</var> call for a zero length string will always return 0 in this case. | |||
==See also== | ==See also== | ||
{{Template:Regex:Match footer}} | {{Template:Regex:Match footer}} | ||
[[Category:Regular expression processing]] | |||
Revision as of 01:11, 23 March 2022
Position after match of regex (Regex class)
This function tests a Unicode or EBCDIC string against the regular expression in the Regex object. It can also return the contents of cpturing groups to a Stringlist.
Syntax
%number = regex:Match( string, [Start= number], [Capture= stringlist])
Syntax terms
| %number | The position in the string after the match. If the string does not match the regular expression, 0 is returned. If the regular expressions matches up to the end of the string, the lenght of the string plus one is returned. |
|---|---|
| regex | The Regex object |
| string | The Unicode or EBCDIC string to test against the Regex object. |
| start | number The starting position. This value must be between 1 and the length of string plus 1. The default value is 1, which means to start at the beginning of the string. |
| capture | A Stringlist object that is to receive the capturing group contents if there is a match. Each added item represents a capturing group's value with items added in capturing group order. |
Usage notes
- There is no Capture method for the Regex class since Match provides capture functionality.
- An advantage of this method over the String RegexMatch method is that this method has a start position parameter.
Examples
The following illustrates how a loop can find all occurrences of a particular pattern in a string and to add those occurrences to a Stringlist:
%pos is float %matches is object stringlist %regex is object regex %str is longstring ... %regex = new("(<[^>]+>)") %pos = 1 %matches = new repeat while %pos %pos = %regex:match(%str, start=%pos, capture=%matches) end repeat
Note that no special check is required for a zero-length string – 1 is a valid start position for a zero-length string and the first Match call for a zero length string will always return 0 in this case.