# $EPIC: regmatches.txt,v 1.3 2009/03/21 05:06:18 zwhite Exp $
======Synopsis:======
$[[regmatches]](<value returned by regcomp> <max matches> <string>)

======Technical:======
This function matches a regular expression much like [[regexec]] does, 
except it honors subexpressions in the regular expression. It will return 
at most <max matches> pairs of numbers describing the start and length of
any matches and submatches found. Each pair is suitable for passing to
[[mid]].

The first pair of numbers returned is always the entire string matched.
If you wish to match any subexpressions you must specify at least 2 for
<max matches>.

======Returns:======
Returns a list of number pairs, with each suitable for passing to $[[mid]]()
to extract the substring.

If the <string> does not match the <value returned by regcomp> then 
the false value is returned.  

======Example:======
<file>
   @ orig_string = 'abc def';
   @ pattern = regcomp(abc \(def\)));
   @ substrings = regmatches($pattern 2 $orig_string);
   fe ($substrings) x y {
      if (y != strlen($orig_string)) {
         @ rvalue = mid($x $y $orig_string);
         echo $rvalue;
      };
   };
   @regfree($pattern);
</file>

When run, this will return "def".

======More Info:======
See the [[regex]] page for more info.

======History======
This function first appeared in EPIC4-1.1.3.  Previously, [[regcomp]]
did not support subexpressions.