Match (Regex function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
 
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Template:Regex:Match subtitle}}
{{Template:Regex:Match subtitle}}


This page is [[under construction]].
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 capturing groups to a [[Stringlist_class|Stringlist]]. It provides similar functionality to [[RegexMatch (String function)|RegexMatch]], [[UnicodeRegexMatch (Unicode function)|UnicodeRegexMatch]], and [[RegexCapture (Stringlist function)|RegexCapture]].
 
==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>number</td></tr>
<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 this argument is [[??]].</td></tr>
<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<br/>The default value of this argument is [[??]].</td></tr>
<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 &ndash; 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]]

Latest revision as of 15:07, 24 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 capturing groups to a Stringlist. It provides similar functionality to RegexMatch, UnicodeRegexMatch, and RegexCapture.

Syntax

%number = regex:Match( string, [Start= number], [Capture= stringlist])

Syntax terms

%numberThe 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.

See also