Updated PCRE source to version 8.32 (bug 5593).

tools/pcre/doc/html/pcrematching.html

@@ -26,13 +26,17 @@ man page, in case the conversion went wrong.
 <P>
 This document describes the two different algorithms that are available in PCRE
 for matching a compiled regular expression against a given subject string. The
-"standard" algorithm is the one provided by the <b>pcre_exec()</b> function.
-This works in the same was as Perl's matching function, and provides a
-Perl-compatible matching operation.
+"standard" algorithm is the one provided by the <b>pcre_exec()</b>,
+<b>pcre16_exec()</b> and <b>pcre32_exec()</b> functions. These work in the same
+as as Perl's matching function, and provide a Perl-compatible matching operation.
+The just-in-time (JIT) optimization that is described in the
+<a href="pcrejit.html"><b>pcrejit</b></a>
+documentation is compatible with these functions.
 </P>
 <P>
-An alternative algorithm is provided by the <b>pcre_dfa_exec()</b> function;
-this operates in a different way, and is not Perl-compatible. It has advantages
+An alternative algorithm is provided by the <b>pcre_dfa_exec()</b>,
+<b>pcre16_dfa_exec()</b> and <b>pcre32_dfa_exec()</b> functions; they operate in
+a different way, and are not Perl-compatible. This alternative has advantages
 and disadvantages compared with the standard algorithm, and these are described
 below.
 </P>
@@ -96,22 +100,28 @@ traditional finite state machine (it keeps multiple states active
 simultaneously).
 </P>
 <P>
+Although the general principle of this matching algorithm is that it scans the
+subject string only once, without backtracking, there is one exception: when a
+lookaround assertion is encountered, the characters following or preceding the
+current point have to be independently inspected.
+</P>
+<P>
 The scan continues until either the end of the subject is reached, or there are
 no more unterminated paths. At this point, terminated paths represent the
 different matching possibilities (if there are none, the match has failed).
 Thus, if there is more than one possible match, this algorithm finds all of
-them, and in particular, it finds the longest. In PCRE, there is an option to
-stop the algorithm after the first match (which is necessarily the shortest)
-has been found.
+them, and in particular, it finds the longest. The matches are returned in
+decreasing order of length. There is an option to stop the algorithm after the
+first match (which is necessarily the shortest) is found.
 </P>
 <P>
 Note that all the matches that are found start at the same point in the
 subject. If the pattern
 <pre>
-  cat(er(pillar)?)
+  cat(er(pillar)?)?
 </pre>
 is matched against the string "the caterpillar catchment", the result will be
-the three strings "cat", "cater", and "caterpillar" that start at the fourth
+the three strings "caterpillar", "cater", and "cat" that start at the fifth
 character of the subject. The algorithm does not automatically move on to find
 matches that start at later positions.
 </P>
@@ -157,10 +167,10 @@ and not on others), is not supported. It causes an error if encountered.
 always 1, and the value of the <i>capture_last</i> field is always -1.
 </P>
 <P>
-7. The \C escape sequence, which (in the standard algorithm) matches a single
-byte, even in UTF-8 mode, is not supported because the alternative algorithm
-moves through the subject string one character at a time, for all active paths
-through the tree.
+7. The \C escape sequence, which (in the standard algorithm) always matches a
+single data unit, even in UTF-8, UTF-16 or UTF-32 modes, is not supported in
+these modes, because the alternative algorithm moves through the subject string
+one character (not data unit) at a time, for all active paths through the tree.
 </P>
 <P>
 8. Except for (*FAIL), the backtracking control verbs such as (*PRUNE) are not
@@ -177,16 +187,15 @@ match using the standard algorithm, you have to do kludgy things with
 callouts.
 </P>
 <P>
-2. There is much better support for partial matching. The restrictions on the
-content of the pattern that apply when using the standard algorithm for partial
-matching do not apply to the alternative algorithm. For non-anchored patterns,
-the starting position of a partial match is available.
-</P>
-<P>
-3. Because the alternative algorithm scans the subject string just once, and
-never needs to backtrack, it is possible to pass very long subject strings to
-the matching function in several pieces, checking for partial matching each
-time.
+2. Because the alternative algorithm scans the subject string just once, and
+never needs to backtrack (except for lookbehinds), it is possible to pass very
+long subject strings to the matching function in several pieces, checking for
+partial matching each time. Although it is possible to do multi-segment
+matching using the standard algorithm by retaining partially matched
+substrings, it is more complicated. The
+<a href="pcrepartial.html"><b>pcrepartial</b></a>
+documentation gives details of partial matching and discusses multi-segment
+matching.
 </P>
 <br><a name="SEC6" href="#TOC1">DISADVANTAGES OF THE ALTERNATIVE ALGORITHM</a><br>
 <P>
@@ -215,9 +224,9 @@ Cambridge CB2 3QH, England.
 </P>
 <br><a name="SEC8" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 19 April 2008
+Last updated: 08 January 2012
 <br>
-Copyright &copy; 1997-2008 University of Cambridge.
+Copyright &copy; 1997-2012 University of Cambridge.
 <br>
 <p>
 Return to the <a href="index.html">PCRE index page</a>.