| .TH PCREPARTIAL 3 |
| .SH NAME |
| PCRE - Perl-compatible regular expressions |
| .SH "PARTIAL MATCHING IN PCRE" |
| .rs |
| .sp |
| In normal use of PCRE, if the subject string that is passed to |
| \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP matches as far as it goes, but is |
| too short to match the entire pattern, PCRE_ERROR_NOMATCH is returned. There |
| are circumstances where it might be helpful to distinguish this case from other |
| cases in which there is no match. |
| .P |
| Consider, for example, an application where a human is required to type in data |
| for a field with specific formatting requirements. An example might be a date |
| in the form \fIddmmmyy\fP, defined by this pattern: |
| .sp |
| ^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$ |
| .sp |
| If the application sees the user's keystrokes one by one, and can check that |
| what has been typed so far is potentially valid, it is able to raise an error |
| as soon as a mistake is made, by beeping and not reflecting the character that |
| has been typed, for example. This immediate feedback is likely to be a better |
| user interface than a check that is delayed until the entire string has been |
| entered. Partial matching can also be useful when the subject string is very |
| long and is not all available at once. |
| .P |
| PCRE supports partial matching by means of the PCRE_PARTIAL_SOFT and |
| PCRE_PARTIAL_HARD options, which can be set when calling \fBpcre_exec()\fP or |
| \fBpcre_dfa_exec()\fP. For backwards compatibility, PCRE_PARTIAL is a synonym |
| for PCRE_PARTIAL_SOFT. The essential difference between the two options is |
| whether or not a partial match is preferred to an alternative complete match, |
| though the details differ between the two matching functions. If both options |
| are set, PCRE_PARTIAL_HARD takes precedence. |
| .P |
| Setting a partial matching option for \fBpcre_exec()\fP disables the use of any |
| just-in-time code that was set up by calling \fBpcre_study()\fP with the |
| PCRE_STUDY_JIT_COMPILE option. It also disables two of PCRE's standard |
| optimizations. PCRE remembers the last literal byte in a pattern, and abandons |
| matching immediately if such a byte is not present in the subject string. This |
| optimization cannot be used for a subject string that might match only |
| partially. If the pattern was studied, PCRE knows the minimum length of a |
| matching string, and does not bother to run the matching function on shorter |
| strings. This optimization is also disabled for partial matching. |
| . |
| . |
| .SH "PARTIAL MATCHING USING pcre_exec()" |
| .rs |
| .sp |
| A partial match occurs during a call to \fBpcre_exec()\fP when the end of the |
| subject string is reached successfully, but matching cannot continue because |
| more characters are needed. However, at least one character in the subject must |
| have been inspected. This character need not form part of the final matched |
| string; lookbehind assertions and the \eK escape sequence provide ways of |
| inspecting characters before the start of a matched substring. The requirement |
| for inspecting at least one character exists because an empty string can always |
| be matched; without such a restriction there would always be a partial match of |
| an empty string at the end of the subject. |
| .P |
| If there are at least two slots in the offsets vector when \fBpcre_exec()\fP |
| returns with a partial match, the first slot is set to the offset of the |
| earliest character that was inspected when the partial match was found. For |
| convenience, the second offset points to the end of the subject so that a |
| substring can easily be identified. |
| .P |
| For the majority of patterns, the first offset identifies the start of the |
| partially matched string. However, for patterns that contain lookbehind |
| assertions, or \eK, or begin with \eb or \eB, earlier characters have been |
| inspected while carrying out the match. For example: |
| .sp |
| /(?<=abc)123/ |
| .sp |
| This pattern matches "123", but only if it is preceded by "abc". If the subject |
| string is "xyzabc12", the offsets after a partial match are for the substring |
| "abc12", because all these characters are needed if another match is tried |
| with extra characters added to the subject. |
| .P |
| What happens when a partial match is identified depends on which of the two |
| partial matching options are set. |
| . |
| . |
| .SS "PCRE_PARTIAL_SOFT with pcre_exec()" |
| .rs |
| .sp |
| If PCRE_PARTIAL_SOFT is set when \fBpcre_exec()\fP identifies a partial match, |
| the partial match is remembered, but matching continues as normal, and other |
| alternatives in the pattern are tried. If no complete match can be found, |
| \fBpcre_exec()\fP returns PCRE_ERROR_PARTIAL instead of PCRE_ERROR_NOMATCH. |
| .P |
| This option is "soft" because it prefers a complete match over a partial match. |
| All the various matching items in a pattern behave as if the subject string is |
| potentially complete. For example, \ez, \eZ, and $ match at the end of the |
| subject, as normal, and for \eb and \eB the end of the subject is treated as a |
| non-alphanumeric. |
| .P |
| If there is more than one partial match, the first one that was found provides |
| the data that is returned. Consider this pattern: |
| .sp |
| /123\ew+X|dogY/ |
| .sp |
| If this is matched against the subject string "abc123dog", both |
| alternatives fail to match, but the end of the subject is reached during |
| matching, so PCRE_ERROR_PARTIAL is returned. The offsets are set to 3 and 9, |
| identifying "123dog" as the first partial match that was found. (In this |
| example, there are two partial matches, because "dog" on its own partially |
| matches the second alternative.) |
| . |
| . |
| .SS "PCRE_PARTIAL_HARD with pcre_exec()" |
| .rs |
| .sp |
| If PCRE_PARTIAL_HARD is set for \fBpcre_exec()\fP, it returns |
| PCRE_ERROR_PARTIAL as soon as a partial match is found, without continuing to |
| search for possible complete matches. This option is "hard" because it prefers |
| an earlier partial match over a later complete match. For this reason, the |
| assumption is made that the end of the supplied subject string may not be the |
| true end of the available data, and so, if \ez, \eZ, \eb, \eB, or $ are |
| encountered at the end of the subject, the result is PCRE_ERROR_PARTIAL. |
| .P |
| Setting PCRE_PARTIAL_HARD also affects the way \fBpcre_exec()\fP checks UTF-8 |
| subject strings for validity. Normally, an invalid UTF-8 sequence causes the |
| error PCRE_ERROR_BADUTF8. However, in the special case of a truncated UTF-8 |
| character at the end of the subject, PCRE_ERROR_SHORTUTF8 is returned when |
| PCRE_PARTIAL_HARD is set. |
| . |
| . |
| .SS "Comparing hard and soft partial matching" |
| .rs |
| .sp |
| The difference between the two partial matching options can be illustrated by a |
| pattern such as: |
| .sp |
| /dog(sbody)?/ |
| .sp |
| This matches either "dog" or "dogsbody", greedily (that is, it prefers the |
| longer string if possible). If it is matched against the string "dog" with |
| PCRE_PARTIAL_SOFT, it yields a complete match for "dog". However, if |
| PCRE_PARTIAL_HARD is set, the result is PCRE_ERROR_PARTIAL. On the other hand, |
| if the pattern is made ungreedy the result is different: |
| .sp |
| /dog(sbody)??/ |
| .sp |
| In this case the result is always a complete match because \fBpcre_exec()\fP |
| finds that first, and it never continues after finding a match. It might be |
| easier to follow this explanation by thinking of the two patterns like this: |
| .sp |
| /dog(sbody)?/ is the same as /dogsbody|dog/ |
| /dog(sbody)??/ is the same as /dog|dogsbody/ |
| .sp |
| The second pattern will never match "dogsbody" when \fBpcre_exec()\fP is |
| used, because it will always find the shorter match first. |
| . |
| . |
| .SH "PARTIAL MATCHING USING pcre_dfa_exec()" |
| .rs |
| .sp |
| The \fBpcre_dfa_exec()\fP function moves along the subject string character by |
| character, without backtracking, searching for all possible matches |
| simultaneously. If the end of the subject is reached before the end of the |
| pattern, there is the possibility of a partial match, again provided that at |
| least one character has been inspected. |
| .P |
| When PCRE_PARTIAL_SOFT is set, PCRE_ERROR_PARTIAL is returned only if there |
| have been no complete matches. Otherwise, the complete matches are returned. |
| However, if PCRE_PARTIAL_HARD is set, a partial match takes precedence over any |
| complete matches. The portion of the string that was inspected when the longest |
| partial match was found is set as the first matching string, provided there are |
| at least two slots in the offsets vector. |
| .P |
| Because \fBpcre_dfa_exec()\fP always searches for all possible matches, and |
| there is no difference between greedy and ungreedy repetition, its behaviour is |
| different from \fBpcre_exec\fP when PCRE_PARTIAL_HARD is set. Consider the |
| string "dog" matched against the ungreedy pattern shown above: |
| .sp |
| /dog(sbody)??/ |
| .sp |
| Whereas \fBpcre_exec()\fP stops as soon as it finds the complete match for |
| "dog", \fBpcre_dfa_exec()\fP also finds the partial match for "dogsbody", and |
| so returns that when PCRE_PARTIAL_HARD is set. |
| . |
| . |
| .SH "PARTIAL MATCHING AND WORD BOUNDARIES" |
| .rs |
| .sp |
| If a pattern ends with one of sequences \eb or \eB, which test for word |
| boundaries, partial matching with PCRE_PARTIAL_SOFT can give counter-intuitive |
| results. Consider this pattern: |
| .sp |
| /\ebcat\eb/ |
| .sp |
| This matches "cat", provided there is a word boundary at either end. If the |
| subject string is "the cat", the comparison of the final "t" with a following |
| character cannot take place, so a partial match is found. However, |
| \fBpcre_exec()\fP carries on with normal matching, which matches \eb at the end |
| of the subject when the last character is a letter, thus finding a complete |
| match. The result, therefore, is \fInot\fP PCRE_ERROR_PARTIAL. The same thing |
| happens with \fBpcre_dfa_exec()\fP, because it also finds the complete match. |
| .P |
| Using PCRE_PARTIAL_HARD in this case does yield PCRE_ERROR_PARTIAL, because |
| then the partial match takes precedence. |
| . |
| . |
| .SH "FORMERLY RESTRICTED PATTERNS" |
| .rs |
| .sp |
| For releases of PCRE prior to 8.00, because of the way certain internal |
| optimizations were implemented in the \fBpcre_exec()\fP function, the |
| PCRE_PARTIAL option (predecessor of PCRE_PARTIAL_SOFT) could not be used with |
| all patterns. From release 8.00 onwards, the restrictions no longer apply, and |
| partial matching with \fBpcre_exec()\fP can be requested for any pattern. |
| .P |
| Items that were formerly restricted were repeated single characters and |
| repeated metasequences. If PCRE_PARTIAL was set for a pattern that did not |
| conform to the restrictions, \fBpcre_exec()\fP returned the error code |
| PCRE_ERROR_BADPARTIAL (-13). This error code is no longer in use. The |
| PCRE_INFO_OKPARTIAL call to \fBpcre_fullinfo()\fP to find out if a compiled |
| pattern can be used for partial matching now always returns 1. |
| . |
| . |
| .SH "EXAMPLE OF PARTIAL MATCHING USING PCRETEST" |
| .rs |
| .sp |
| If the escape sequence \eP is present in a \fBpcretest\fP data line, the |
| PCRE_PARTIAL_SOFT option is used for the match. Here is a run of \fBpcretest\fP |
| that uses the date example quoted above: |
| .sp |
| re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ |
| data> 25jun04\eP |
| 0: 25jun04 |
| 1: jun |
| data> 25dec3\eP |
| Partial match: 23dec3 |
| data> 3ju\eP |
| Partial match: 3ju |
| data> 3juj\eP |
| No match |
| data> j\eP |
| No match |
| .sp |
| The first data string is matched completely, so \fBpcretest\fP shows the |
| matched substrings. The remaining four strings do not match the complete |
| pattern, but the first two are partial matches. Similar output is obtained |
| when \fBpcre_dfa_exec()\fP is used. |
| .P |
| If the escape sequence \eP is present more than once in a \fBpcretest\fP data |
| line, the PCRE_PARTIAL_HARD option is set for the match. |
| . |
| . |
| .SH "MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()" |
| .rs |
| .sp |
| When a partial match has been found using \fBpcre_dfa_exec()\fP, it is possible |
| to continue the match by providing additional subject data and calling |
| \fBpcre_dfa_exec()\fP again with the same compiled regular expression, this |
| time setting the PCRE_DFA_RESTART option. You must pass the same working |
| space as before, because this is where details of the previous partial match |
| are stored. Here is an example using \fBpcretest\fP, using the \eR escape |
| sequence to set the PCRE_DFA_RESTART option (\eD specifies the use of |
| \fBpcre_dfa_exec()\fP): |
| .sp |
| re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ |
| data> 23ja\eP\eD |
| Partial match: 23ja |
| data> n05\eR\eD |
| 0: n05 |
| .sp |
| 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 |
| You can set the PCRE_PARTIAL_SOFT or PCRE_PARTIAL_HARD options with |
| PCRE_DFA_RESTART to continue partial matching over multiple segments. This |
| facility can be used to pass very long subject strings to |
| \fBpcre_dfa_exec()\fP. |
| . |
| . |
| .SH "MULTI-SEGMENT MATCHING WITH pcre_exec()" |
| .rs |
| .sp |
| From release 8.00, \fBpcre_exec()\fP can also be used to do multi-segment |
| matching. Unlike \fBpcre_dfa_exec()\fP, it is not possible to restart the |
| previous match with a new segment of data. Instead, new data must be added to |
| the previous subject string, and the entire match re-run, starting from the |
| point where the partial match occurred. Earlier data can be discarded. It is |
| best to use PCRE_PARTIAL_HARD in this situation, because it does not treat the |
| end of a segment as the end of the subject when matching \ez, \eZ, \eb, \eB, |
| and $. Consider an unanchored pattern that matches dates: |
| .sp |
| re> /\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed/ |
| data> The date is 23ja\eP\eP |
| Partial match: 23ja |
| .sp |
| At this stage, an application could discard the text preceding "23ja", add on |
| text from the next segment, and call \fBpcre_exec()\fP again. Unlike |
| \fBpcre_dfa_exec()\fP, the entire matching string must always be available, and |
| the complete matching process occurs for each call, so more memory and more |
| processing time is needed. |
| .P |
| \fBNote:\fP If the pattern contains lookbehind assertions, or \eK, or starts |
| with \eb or \eB, the string that is returned for a partial match will include |
| characters that precede the partially matched string itself, because these must |
| be retained when adding on more characters for a subsequent matching attempt. |
| . |
| . |
| .SH "ISSUES WITH MULTI-SEGMENT MATCHING" |
| .rs |
| .sp |
| Certain types of pattern may give problems with multi-segment matching, |
| whichever matching function is used. |
| .P |
| 1. If the pattern contains a test for the beginning of a line, you need to pass |
| the PCRE_NOTBOL option when the subject string for any call does start at the |
| beginning of a line. There is also a PCRE_NOTEOL option, but in practice when |
| doing multi-segment matching you should be using PCRE_PARTIAL_HARD, which |
| includes the effect of PCRE_NOTEOL. |
| .P |
| 2. Lookbehind assertions at the start of a pattern are catered for in the |
| offsets that are returned for a partial match. However, in theory, a lookbehind |
| assertion later in the pattern could require even earlier characters to be |
| inspected, and it might not have been reached when a partial match occurs. This |
| is probably an extremely unlikely case; you could guard against it to a certain |
| extent by always including extra characters at the start. |
| .P |
| 3. Matching a subject string that is split into multiple segments may not |
| always produce exactly the same result as matching over one single long string, |
| especially when PCRE_PARTIAL_SOFT is used. The section "Partial Matching and |
| Word Boundaries" above describes an issue that arises if the pattern ends with |
| \eb or \eB. Another kind of difference may occur when there are multiple |
| matching possibilities, because (for PCRE_PARTIAL_SOFT) a partial match result |
| is given only when there are no completed matches. This means that as soon as |
| the shortest match has been found, continuation to a new subject segment is no |
| longer possible. Consider again this \fBpcretest\fP example: |
| .sp |
| re> /dog(sbody)?/ |
| data> dogsb\eP |
| 0: dog |
| data> do\eP\eD |
| Partial match: do |
| data> gsb\eR\eP\eD |
| 0: g |
| data> dogsbody\eD |
| 0: dogsbody |
| 1: dog |
| .sp |
| The first data line passes the string "dogsb" to \fBpcre_exec()\fP, setting the |
| PCRE_PARTIAL_SOFT option. Although the string is a partial match for |
| "dogsbody", the result is not PCRE_ERROR_PARTIAL, because the shorter string |
| "dog" is a complete match. Similarly, when the subject is presented to |
| \fBpcre_dfa_exec()\fP 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, |
| \fBpcre_dfa_exec()\fP finds both matches. |
| .P |
| Because of these problems, it is best to use PCRE_PARTIAL_HARD when matching |
| multi-segment data. The example above then behaves differently: |
| .sp |
| re> /dog(sbody)?/ |
| data> dogsb\eP\eP |
| Partial match: dogsb |
| data> do\eP\eD |
| Partial match: do |
| data> gsb\eR\eP\eP\eD |
| Partial match: gsb |
| .sp |
| 4. Patterns that contain alternatives at the top level which do not all |
| start with the same pattern item may not work as expected when |
| PCRE_DFA_RESTART is used with \fBpcre_dfa_exec()\fP. For example, consider this |
| pattern: |
| .sp |
| 1234|3789 |
| .sp |
| 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 "7890" 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: |
| .sp |
| 1234|ABCD |
| .sp |
| where no string can be a partial match for both alternatives. This is not a |
| problem if \fBpcre_exec()\fP is used, because the entire match has to be rerun |
| each time: |
| .sp |
| re> /1234|3789/ |
| data> ABC123\eP\eP |
| Partial match: 123 |
| data> 1237890 |
| 0: 3789 |
| .sp |
| Of course, instead of using PCRE_DFA_RESTART, the same technique of re-running |
| the entire match can also be used with \fBpcre_dfa_exec()\fP. Another |
| possibility is to work with two buffers. If a partial match at offset \fIn\fP |
| in the first buffer is followed by "no match" when PCRE_DFA_RESTART is used on |
| the second buffer, you can then try a new match starting at offset \fIn+1\fP in |
| the first buffer. |
| . |
| . |
| .SH AUTHOR |
| .rs |
| .sp |
| .nf |
| Philip Hazel |
| University Computing Service |
| Cambridge CB2 3QH, England. |
| .fi |
| . |
| . |
| .SH REVISION |
| .rs |
| .sp |
| .nf |
| Last updated: 26 August 2011 |
| Copyright (c) 1997-2011 University of Cambridge. |
| .fi |