/[pcre]/code/trunk/doc/html/pcrepartial.html

Diff of /code/trunk/doc/html/pcrepartial.html

Parent Directory | Revision Log | View Patch Patch

-revision 75 by nigel,
Sat Feb 24 21:40:37 2007 UTC
+revision 148 by ph10,
Mon Apr 16 13:25:10 2007 UTC
 Line 16 
 man page, in case the conversion went wr
  <li><a name="TOC1" href="#SEC1">PARTIAL MATCHING IN PCRE</a>
  <li><a name="TOC2" href="#SEC2">RESTRICTED PATTERNS FOR PCRE_PARTIAL</a>
  <li><a name="TOC3" href="#SEC3">EXAMPLE OF PARTIAL MATCHING USING PCRETEST</a>
+ <li><a name="TOC4" href="#SEC4">MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()</a>
+ <li><a name="TOC5" href="#SEC5">AUTHOR</a>
+ <li><a name="TOC6" href="#SEC6">REVISION</a>
  </ul>
  <br><a name="SEC1" href="#TOC1">PARTIAL MATCHING IN PCRE</a><br>
  <P>
  In normal use of PCRE, if the subject string that is passed to
- <b>pcre_exec()</b> matches as far as it goes, but is too short to match the
+ <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b> matches as far as it goes, but is
- entire pattern, PCRE_ERROR_NOMATCH is returned. There are circumstances where
+ too short to match the entire pattern, PCRE_ERROR_NOMATCH is returned. There
- it might be helpful to distinguish this case from other cases in which there is
+ are circumstances where it might be helpful to distinguish this case from other
- no match.
+ cases in which there is no match.
  </P>
  <P>
  Consider, for example, an application where a human is required to type in data
-Line 41 
 entered.
+Line 44 
 entered.
  </P>
  <P>
  PCRE supports the concept of partial matching by means of the PCRE_PARTIAL
- option, which can be set when calling <b>pcre_exec()</b>. When this is done, the
+ option, which can be set when calling <b>pcre_exec()</b> or
- return code PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if at any
+ <b>pcre_dfa_exec()</b>. When this flag is set for <b>pcre_exec()</b>, the return
- time during the matching process the entire subject string matched part of the
+ code PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if at any time
- pattern. No captured data is set when this occurs.
+ during the matching process the last part of the subject string matched part of
+ the pattern. Unfortunately, for non-anchored matching, it is not possible to
+ obtain the position of the start of the partial match. No captured data is set
+ when PCRE_ERROR_PARTIAL is returned.
+ </P>
+ <P>
+ When PCRE_PARTIAL is set for <b>pcre_dfa_exec()</b>, the return code
+ PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if the end of the
+ subject is reached, there have been no complete matches, but there is still at
+ least one matching possibility. The portion of the string that provided the
+ partial match is set as the first matching string.
  </P>
  <P>
  Using PCRE_PARTIAL disables one of PCRE's optimizations. PCRE remembers the
-Line 54 
 for a subject string that might match on
+Line 67 
 for a subject string that might match on
  </P>
  <br><a name="SEC2" href="#TOC1">RESTRICTED PATTERNS FOR PCRE_PARTIAL</a><br>
  <P>
- Because of the way certain internal optimizations are implemented in PCRE, the
+ Because of the way certain internal optimizations are implemented in the
- PCRE_PARTIAL option cannot be used with all patterns. Repeated single
+ <b>pcre_exec()</b> function, the PCRE_PARTIAL option cannot be used with all
- characters such as
+ patterns. These restrictions do not apply when <b>pcre_dfa_exec()</b> is used.
+ For <b>pcre_exec()</b>, repeated single characters such as
  <pre>
    a{2,4}
  </pre>
-Line 100 
 uses the date example quoted above:
+Line 114 
 uses the date example quoted above:
  </pre>
  The first data string is matched completely, so <b>pcretest</b> shows the
  matched substrings. The remaining four strings do not match the complete
- pattern, but the first two are partial matches.
+ pattern, but the first two are partial matches. The same test, using
+ <b>pcre_dfa_exec()</b> matching (by means of the \D escape sequence), produces
+ the following output:
+ <pre>
+     re&#62; /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
+   data&#62; 25jun04\P\D
+: 25jun04
+   data&#62; 23dec3\P\D
+   Partial match: 23dec3
+   data&#62; 3ju\P\D
+   Partial match: 3ju
+   data&#62; 3juj\P\D
+   No match
+   data&#62; j\P\D
+   No match
+ </pre>
+ Notice that in this case the portion of the string that was matched is made
+ available.
+ </P>
+ <br><a name="SEC4" href="#TOC1">MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()</a><br>
+ <P>
+ When a partial match has been found using <b>pcre_dfa_exec()</b>, it is possible
+ to continue the match by providing additional subject data and calling
+ <b>pcre_dfa_exec()</b> again with the same compiled regular expression, this
+ time setting the PCRE_DFA_RESTART option. You must also pass the same working
+ space as before, because this is where details of the previous partial match
+ are stored. Here is an example using <b>pcretest</b>, using the \R escape
+ sequence to set the PCRE_DFA_RESTART option (\P and \D are as above):
+ <pre>
+     re&#62; /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
+   data&#62; 23ja\P\D
+   Partial match: 23ja
+   data&#62; n05\R\D
+: n05
+ </pre>
+ The first call has "23ja" as the subject, and requests partial matching; the
+ second call has "n05" as the subject for the continued (restarted) match.
+ Notice that when the match is complete, only the last part is shown; PCRE does
+ not retain the previously partially-matched string. It is up to the calling
+ program to do that if it needs to.
+ </P>
+ <P>
+ You can set PCRE_PARTIAL with PCRE_DFA_RESTART to continue partial matching
+ over multiple segments. This facility can be used to pass very long subject
+ strings to <b>pcre_dfa_exec()</b>. However, some care is needed for certain
+ types of pattern.
+ </P>
+ <P>
+. If the pattern contains tests for the beginning or end of a line, you need
+ to pass the PCRE_NOTBOL or PCRE_NOTEOL options, as appropriate, when the
+ subject string for any call does not contain the beginning or end of a line.
+ </P>
+ <P>
+. If the pattern contains backward assertions (including \b or \B), you need
+ to arrange for some overlap in the subject strings to allow for this. For
+ example, you could pass the subject in chunks that are 500 bytes long, but in
+ a buffer of 700 bytes, with the starting offset set to 200 and the previous 200
+ bytes at the start of the buffer.
+ </P>
+ <P>
+. Matching a subject string that is split into multiple segments does not
+ always produce exactly the same result as matching over one single long string.
+ The difference arises when there are multiple matching possibilities, because a
+ partial match result is given only when there are no completed matches in a
+ call to <b>pcre_dfa_exec()</b>. This means that as soon as the shortest match has
+ been found, continuation to a new subject segment is no longer possible.
+ Consider this <b>pcretest</b> example:
+ <pre>
+     re&#62; /dog(sbody)?/
+   data&#62; do\P\D
+   Partial match: do
+   data&#62; gsb\R\P\D
+: g
+   data&#62; dogsbody\D
+: dogsbody
+: dog
+ </pre>
+ The pattern matches the words "dog" or "dogsbody". When the subject is
+ presented in several parts ("do" and "gsb" being the first two) the match stops
+ when "dog" has been found, and it is not possible to continue. On the other
+ hand, if "dogsbody" is presented as a single string, both matches are found.
  </P>
  <P>
- Last updated: 08 September 2004
+ Because of this phenomenon, it does not usually make sense to end a pattern
+ that is going to be matched in this way with a variable repeat.
+ </P>
+ <P>
+. Patterns that contain alternatives at the top level which do not all
+ start with the same pattern item may not work as expected. For example,
+ consider this pattern:
+ <pre>
+|3789
+ </pre>
+ If the first part of the subject is "ABC123", a partial match of the first
+ alternative is found at offset 3. There is no partial match for the second
+ alternative, because such a match does not start at the same point in the
+ subject string. Attempting to continue with the string "789" does not yield a
+ match because only those alternatives that match at one point in the subject
+ are remembered. The problem arises because the start of the second alternative
+ matches within the first alternative. There is no problem with anchored
+ patterns or patterns such as:
+ <pre>
+|ABCD
+ </pre>
+ where no string can be a partial match for both alternatives.
+ </P>
+ <br><a name="SEC5" href="#TOC1">AUTHOR</a><br>
+ <P>
+ Philip Hazel
+ <br>
+ University Computing Service
+ <br>
+ Cambridge CB2 3QH, England.
+ <br>
+ </P>
+ <br><a name="SEC6" href="#TOC1">REVISION</a><br>
+ <P>
+ Last updated: 06 March 2007
+ <br>
+ Copyright &copy; 1997-2007 University of Cambridge.
  <br>
- Copyright &copy; 1997-2004 University of Cambridge.
  <p>
  Return to the <a href="index.html">PCRE index page</a>.
  </p>

 Legend:



Removed from v.75
 


changed lines


 
Added in v.148
 Legend:



Removed from v.75
 


changed lines


 
Added in v.148
-Removed from v.75
+Added in v.148

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12