|
version 1.1.1.1, 2012/02/21 23:05:52
|
version 1.1.1.3, 2012/10/09 09:19:17
|
|
Line 1
|
Line 1
|
| .TH PCREPARTIAL 3 | .TH PCREPARTIAL 3 "24 February 2012" "PCRE 8.31" |
| .SH NAME |
.SH NAME |
| PCRE - Perl-compatible regular expressions |
PCRE - Perl-compatible regular expressions |
| .SH "PARTIAL MATCHING IN PCRE" |
.SH "PARTIAL MATCHING IN PCRE" |
| .rs |
.rs |
| .sp |
.sp |
| In normal use of PCRE, if the subject string that is passed to | In normal use of PCRE, if the subject string that is passed to a matching |
| \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP matches as far as it goes, but is | function matches as far as it goes, but is too short to match the entire |
| too short to match the entire pattern, PCRE_ERROR_NOMATCH is returned. There | pattern, PCRE_ERROR_NOMATCH is returned. There are circumstances where it might |
| are circumstances where it might be helpful to distinguish this case from other | be helpful to distinguish this case from other cases in which there is no |
| cases in which there is no match. | match. |
| .P |
.P |
| Consider, for example, an application where a human is required to type in data |
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 |
for a field with specific formatting requirements. An example might be a date |
|
Line 25 entered. Partial matching can also be useful when the
|
Line 25 entered. Partial matching can also be useful when the
|
| long and is not all available at once. |
long and is not all available at once. |
| .P |
.P |
| PCRE supports partial matching by means of the PCRE_PARTIAL_SOFT and |
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 | PCRE_PARTIAL_HARD options, which can be set when calling any of the matching |
| \fBpcre_dfa_exec()\fP. For backwards compatibility, PCRE_PARTIAL is a synonym | functions. For backwards compatibility, PCRE_PARTIAL is a synonym for |
| for PCRE_PARTIAL_SOFT. The essential difference between the two options is | PCRE_PARTIAL_SOFT. The essential difference between the two options is whether |
| whether or not a partial match is preferred to an alternative complete match, | or not a partial match is preferred to an alternative complete match, though |
| though the details differ between the two matching functions. If both options | the details differ between the two types of matching function. If both options |
| are set, PCRE_PARTIAL_HARD takes precedence. |
are set, PCRE_PARTIAL_HARD takes precedence. |
| .P |
.P |
| Setting a partial matching option for \fBpcre_exec()\fP disables the use of any | If you want to use partial matching with just-in-time optimized code, you must |
| just-in-time code that was set up by calling \fBpcre_study()\fP with the | call \fBpcre_study()\fP or \fBpcre16_study()\fP with one or both of these |
| PCRE_STUDY_JIT_COMPILE option. It also disables two of PCRE's standard | options: |
| optimizations. PCRE remembers the last literal byte in a pattern, and abandons | .sp |
| matching immediately if such a byte is not present in the subject string. This | PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE |
| | PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE |
| | .sp |
| | PCRE_STUDY_JIT_COMPILE should also be set if you are going to run non-partial |
| | matches on the same pattern. If the appropriate JIT study mode has not been set |
| | for a match, the interpretive matching code is used. |
| | .P |
| | Setting a partial matching option disables two of PCRE's standard |
| | optimizations. PCRE remembers the last literal data unit in a pattern, and |
| | abandons matching immediately if it is not present in the subject string. This |
| optimization cannot be used for a subject string that might match only |
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 |
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 |
matching string, and does not bother to run the matching function on shorter |
| strings. This optimization is also disabled for partial matching. |
strings. This optimization is also disabled for partial matching. |
| . |
. |
| . |
. |
| .SH "PARTIAL MATCHING USING pcre_exec()" | .SH "PARTIAL MATCHING USING pcre_exec() OR pcre16_exec()" |
| .rs |
.rs |
| .sp |
.sp |
| A partial match occurs during a call to \fBpcre_exec()\fP when the end of the | A partial match occurs during a call to \fBpcre_exec()\fP or |
| subject string is reached successfully, but matching cannot continue because | \fBpcre16_exec()\fP when the end of the subject string is reached successfully, |
| more characters are needed. However, at least one character in the subject must | but matching cannot continue because more characters are needed. However, at |
| have been inspected. This character need not form part of the final matched | least one character in the subject must have been inspected. This character |
| string; lookbehind assertions and the \eK escape sequence provide ways of | need not form part of the final matched string; lookbehind assertions and the |
| inspecting characters before the start of a matched substring. The requirement | \eK escape sequence provide ways of inspecting characters before the start of a |
| for inspecting at least one character exists because an empty string can always | matched substring. The requirement for inspecting at least one character exists |
| be matched; without such a restriction there would always be a partial match of | because an empty string can always be matched; without such a restriction there |
| an empty string at the end of the subject. | would always be a partial match of an empty string at the end of the subject. |
| .P |
.P |
| If there are at least two slots in the offsets vector when \fBpcre_exec()\fP | If there are at least two slots in the offsets vector when a partial match is |
| returns with a partial match, the first slot is set to the offset of the | returned, the first slot is set to the offset of the earliest character that |
| earliest character that was inspected when the partial match was found. For | was inspected. For convenience, the second offset points to the end of the |
| convenience, the second offset points to the end of the subject so that a | subject so that a substring can easily be identified. |
| substring can easily be identified. | |
| .P |
.P |
| For the majority of patterns, the first offset identifies the start of the |
For the majority of patterns, the first offset identifies the start of the |
| partially matched string. However, for patterns that contain lookbehind |
partially matched string. However, for patterns that contain lookbehind |
|
Line 78 What happens when a partial match is identified depend
|
Line 86 What happens when a partial match is identified depend
|
| partial matching options are set. |
partial matching options are set. |
| . |
. |
| . |
. |
| .SS "PCRE_PARTIAL_SOFT with pcre_exec()" | .SS "PCRE_PARTIAL_SOFT WITH pcre_exec() OR pcre16_exec()" |
| .rs |
.rs |
| .sp |
.sp |
| If PCRE_PARTIAL_SOFT is set when \fBpcre_exec()\fP identifies a partial match, | If PCRE_PARTIAL_SOFT is set when \fBpcre_exec()\fP or \fBpcre16_exec()\fP |
| the partial match is remembered, but matching continues as normal, and other | identifies a partial match, the partial match is remembered, but matching |
| alternatives in the pattern are tried. If no complete match can be found, | continues as normal, and other alternatives in the pattern are tried. If no |
| \fBpcre_exec()\fP returns PCRE_ERROR_PARTIAL instead of PCRE_ERROR_NOMATCH. | complete match can be found, PCRE_ERROR_PARTIAL is returned instead of |
| | PCRE_ERROR_NOMATCH. |
| .P |
.P |
| This option is "soft" because it prefers a complete match over a partial match. |
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 |
All the various matching items in a pattern behave as if the subject string is |
|
Line 105 example, there are two partial matches, because "dog"
|
Line 114 example, there are two partial matches, because "dog"
|
| matches the second alternative.) |
matches the second alternative.) |
| . |
. |
| . |
. |
| .SS "PCRE_PARTIAL_HARD with pcre_exec()" | .SS "PCRE_PARTIAL_HARD WITH pcre_exec() OR pcre16_exec()" |
| .rs |
.rs |
| .sp |
.sp |
| If PCRE_PARTIAL_HARD is set for \fBpcre_exec()\fP, it returns | If PCRE_PARTIAL_HARD is set for \fBpcre_exec()\fP or \fBpcre16_exec()\fP, |
| PCRE_ERROR_PARTIAL as soon as a partial match is found, without continuing to | PCRE_ERROR_PARTIAL is returned as soon as a partial match is found, without |
| search for possible complete matches. This option is "hard" because it prefers | continuing to search for possible complete matches. This option is "hard" |
| an earlier partial match over a later complete match. For this reason, the | because it prefers an earlier partial match over a later complete match. For |
| assumption is made that the end of the supplied subject string may not be the | this reason, the assumption is made that the end of the supplied subject string |
| true end of the available data, and so, if \ez, \eZ, \eb, \eB, or $ are | may not be the true end of the available data, and so, if \ez, \eZ, \eb, \eB, |
| encountered at the end of the subject, the result is PCRE_ERROR_PARTIAL. | or $ are encountered at the end of the subject, the result is |
| | PCRE_ERROR_PARTIAL, provided that at least one character in the subject has |
| | been inspected. |
| .P |
.P |
| Setting PCRE_PARTIAL_HARD also affects the way \fBpcre_exec()\fP checks UTF-8 | Setting PCRE_PARTIAL_HARD also affects the way UTF-8 and UTF-16 |
| subject strings for validity. Normally, an invalid UTF-8 sequence causes the | subject strings are checked for validity. Normally, an invalid sequence |
| error PCRE_ERROR_BADUTF8. However, in the special case of a truncated UTF-8 | causes the error PCRE_ERROR_BADUTF8 or PCRE_ERROR_BADUTF16. However, in the |
| character at the end of the subject, PCRE_ERROR_SHORTUTF8 is returned when | special case of a truncated character at the end of the subject, |
| | PCRE_ERROR_SHORTUTF8 or PCRE_ERROR_SHORTUTF16 is returned when |
| PCRE_PARTIAL_HARD is set. |
PCRE_PARTIAL_HARD is set. |
| . |
. |
| . |
. |
|
Line 139 if the pattern is made ungreedy the result is differen
|
Line 151 if the pattern is made ungreedy the result is differen
|
| .sp |
.sp |
| /dog(sbody)??/ |
/dog(sbody)??/ |
| .sp |
.sp |
| In this case the result is always a complete match because \fBpcre_exec()\fP | In this case the result is always a complete match because that is found first, |
| finds that first, and it never continues after finding a match. It might be | and matching never continues after finding a complete match. It might be easier |
| easier to follow this explanation by thinking of the two patterns like this: | to follow this explanation by thinking of the two patterns like this: |
| .sp |
.sp |
| /dog(sbody)?/ is the same as /dogsbody|dog/ |
/dog(sbody)?/ is the same as /dogsbody|dog/ |
| /dog(sbody)??/ is the same as /dog|dogsbody/ |
/dog(sbody)??/ is the same as /dog|dogsbody/ |
| .sp |
.sp |
| The second pattern will never match "dogsbody" when \fBpcre_exec()\fP is | The second pattern will never match "dogsbody", because it will always find the |
| used, because it will always find the shorter match first. | shorter match first. |
| . |
. |
| . |
. |
| .SH "PARTIAL MATCHING USING pcre_dfa_exec()" | .SH "PARTIAL MATCHING USING pcre_dfa_exec() OR pcre16_dfa_exec()" |
| .rs |
.rs |
| .sp |
.sp |
| The \fBpcre_dfa_exec()\fP function moves along the subject string character by | The DFA functions move along the subject string character by character, without |
| character, without backtracking, searching for all possible matches | backtracking, searching for all possible matches simultaneously. If the end of |
| simultaneously. If the end of the subject is reached before the end of the | the subject is reached before the end of the pattern, there is the possibility |
| pattern, there is the possibility of a partial match, again provided that at | of a partial match, again provided that at least one character has been |
| least one character has been inspected. | inspected. |
| .P |
.P |
| When PCRE_PARTIAL_SOFT is set, PCRE_ERROR_PARTIAL is returned only if there |
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. |
have been no complete matches. Otherwise, the complete matches are returned. |
|
Line 166 complete matches. The portion of the string that was i
|
Line 178 complete matches. The portion of the string that was i
|
| partial match was found is set as the first matching string, provided there are |
partial match was found is set as the first matching string, provided there are |
| at least two slots in the offsets vector. |
at least two slots in the offsets vector. |
| .P |
.P |
| Because \fBpcre_dfa_exec()\fP always searches for all possible matches, and | Because the DFA functions always search for all possible matches, and there is |
| there is no difference between greedy and ungreedy repetition, its behaviour is | no difference between greedy and ungreedy repetition, their behaviour is |
| different from \fBpcre_exec\fP when PCRE_PARTIAL_HARD is set. Consider the | different from the standard functions when PCRE_PARTIAL_HARD is set. Consider |
| string "dog" matched against the ungreedy pattern shown above: | the string "dog" matched against the ungreedy pattern shown above: |
| .sp |
.sp |
| /dog(sbody)??/ |
/dog(sbody)??/ |
| .sp |
.sp |
| Whereas \fBpcre_exec()\fP stops as soon as it finds the complete match for | Whereas the standard functions stop as soon as they find the complete match for |
| "dog", \fBpcre_dfa_exec()\fP also finds the partial match for "dogsbody", and | "dog", the DFA functions also find the partial match for "dogsbody", and so |
| so returns that when PCRE_PARTIAL_HARD is set. | return that when PCRE_PARTIAL_HARD is set. |
| . |
. |
| . |
. |
| .SH "PARTIAL MATCHING AND WORD BOUNDARIES" |
.SH "PARTIAL MATCHING AND WORD BOUNDARIES" |
|
Line 189 results. Consider this pattern:
|
Line 201 results. Consider this pattern:
|
| .sp |
.sp |
| This matches "cat", provided there is a word boundary at either end. If the |
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 |
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, | character cannot take place, so a partial match is found. However, normal |
| \fBpcre_exec()\fP carries on with normal matching, which matches \eb at the end | matching carries on, and \eb matches at the end of the subject when the last |
| of the subject when the last character is a letter, thus finding a complete | character is a letter, so a complete match is found. The result, therefore, is |
| match. The result, therefore, is \fInot\fP PCRE_ERROR_PARTIAL. The same thing | \fInot\fP PCRE_ERROR_PARTIAL. Using PCRE_PARTIAL_HARD in this case does yield |
| happens with \fBpcre_dfa_exec()\fP, because it also finds the complete match. | PCRE_ERROR_PARTIAL, because then the partial match takes precedence. |
| .P | |
| Using PCRE_PARTIAL_HARD in this case does yield PCRE_ERROR_PARTIAL, because | |
| then the partial match takes precedence. | |
| . |
. |
| . |
. |
| .SH "FORMERLY RESTRICTED PATTERNS" |
.SH "FORMERLY RESTRICTED PATTERNS" |
|
Line 206 For releases of PCRE prior to 8.00, because of the way
|
Line 215 For releases of PCRE prior to 8.00, because of the way
|
| optimizations were implemented in the \fBpcre_exec()\fP function, the |
optimizations were implemented in the \fBpcre_exec()\fP function, the |
| PCRE_PARTIAL option (predecessor of PCRE_PARTIAL_SOFT) could not be used with |
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 |
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. | partial matching with can be requested for any pattern. |
| .P |
.P |
| Items that were formerly restricted were repeated single characters and |
Items that were formerly restricted were repeated single characters and |
| repeated metasequences. If PCRE_PARTIAL was set for a pattern that did not |
repeated metasequences. If PCRE_PARTIAL was set for a pattern that did not |
|
Line 239 that uses the date example quoted above:
|
Line 248 that uses the date example quoted above:
|
| The first data string is matched completely, so \fBpcretest\fP shows the |
The first data string is matched completely, so \fBpcretest\fP shows the |
| matched substrings. The remaining four strings do not match the complete |
matched substrings. The remaining four strings do not match the complete |
| pattern, but the first two are partial matches. Similar output is obtained |
pattern, but the first two are partial matches. Similar output is obtained |
| when \fBpcre_dfa_exec()\fP is used. | if DFA matching is used. |
| .P |
.P |
| If the escape sequence \eP is present more than once in a \fBpcretest\fP data |
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. |
line, the PCRE_PARTIAL_HARD option is set for the match. |
| . |
. |
| . |
. |
| .SH "MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()" | .SH "MULTI-SEGMENT MATCHING WITH pcre_dfa_exec() OR pcre16_dfa_exec()" |
| .rs |
.rs |
| .sp |
.sp |
| When a partial match has been found using \fBpcre_dfa_exec()\fP, it is possible | When a partial match has been found using a DFA matching function, it is |
| to continue the match by providing additional subject data and calling | possible to continue the match by providing additional subject data and calling |
| \fBpcre_dfa_exec()\fP again with the same compiled regular expression, this | the function again with the same compiled regular expression, this time setting |
| time setting the PCRE_DFA_RESTART option. You must pass the same working | the PCRE_DFA_RESTART option. You must pass the same working space as before, |
| space as before, because this is where details of the previous partial match | because this is where details of the previous partial match are stored. Here is |
| are stored. Here is an example using \fBpcretest\fP, using the \eR escape | an example using \fBpcretest\fP, using the \eR escape sequence to set the |
| sequence to set the PCRE_DFA_RESTART option (\eD specifies the use of | PCRE_DFA_RESTART option (\eD specifies the use of the DFA matching function): |
| \fBpcre_dfa_exec()\fP): | |
| .sp |
.sp |
| re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ |
re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ |
| data> 23ja\eP\eD |
data> 23ja\eP\eD |
|
Line 271 program to do that if it needs to.
|
Line 279 program to do that if it needs to.
|
| .P |
.P |
| You can set the PCRE_PARTIAL_SOFT or PCRE_PARTIAL_HARD options with |
You can set the PCRE_PARTIAL_SOFT or PCRE_PARTIAL_HARD options with |
| PCRE_DFA_RESTART to continue partial matching over multiple segments. This |
PCRE_DFA_RESTART to continue partial matching over multiple segments. This |
| facility can be used to pass very long subject strings to | facility can be used to pass very long subject strings to the DFA matching |
| \fBpcre_dfa_exec()\fP. | functions. |
| . |
. |
| . |
. |
| .SH "MULTI-SEGMENT MATCHING WITH pcre_exec()" | .SH "MULTI-SEGMENT MATCHING WITH pcre_exec() OR pcre16_exec()" |
| .rs |
.rs |
| .sp |
.sp |
| From release 8.00, \fBpcre_exec()\fP can also be used to do multi-segment | From release 8.00, the standard matching functions can also be used to do |
| matching. Unlike \fBpcre_dfa_exec()\fP, it is not possible to restart the | multi-segment matching. Unlike the DFA functions, it is not possible to |
| previous match with a new segment of data. Instead, new data must be added to | restart the previous match with a new segment of data. Instead, new data must |
| the previous subject string, and the entire match re-run, starting from the | be added to the previous subject string, and the entire match re-run, starting |
| point where the partial match occurred. Earlier data can be discarded. It is | from the point where the partial match occurred. Earlier data can be discarded. |
| best to use PCRE_PARTIAL_HARD in this situation, because it does not treat the | .P |
| end of a segment as the end of the subject when matching \ez, \eZ, \eb, \eB, | It is best to use PCRE_PARTIAL_HARD in this situation, because it does not |
| and $. Consider an unanchored pattern that matches dates: | 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 |
.sp |
| re> /\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed/ |
re> /\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed/ |
| data> The date is 23ja\eP\eP |
data> The date is 23ja\eP\eP |
| Partial match: 23ja |
Partial match: 23ja |
| .sp |
.sp |
| At this stage, an application could discard the text preceding "23ja", add on |
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 | text from the next segment, and call the matching function again. Unlike the |
| \fBpcre_dfa_exec()\fP, the entire matching string must always be available, and | DFA matching functions, the entire matching string must always be available, |
| the complete matching process occurs for each call, so more memory and more | and the complete matching process occurs for each call, so more memory and more |
| processing time is needed. |
processing time is needed. |
| .P |
.P |
| \fBNote:\fP If the pattern contains lookbehind assertions, or \eK, or starts |
\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 | with \eb or \eB, the string that is returned for a partial match includes |
| characters that precede the partially matched string itself, because these must |
characters that precede the partially matched string itself, because these must |
| be retained when adding on more characters for a subsequent matching attempt. |
be retained when adding on more characters for a subsequent matching attempt. |
| |
However, in some cases you may need to retain even earlier characters, as |
| |
discussed in the next section. |
| . |
. |
| . |
. |
| .SH "ISSUES WITH MULTI-SEGMENT MATCHING" |
.SH "ISSUES WITH MULTI-SEGMENT MATCHING" |
|
Line 315 beginning of a line. There is also a PCRE_NOTEOL optio
|
Line 326 beginning of a line. There is also a PCRE_NOTEOL optio
|
| doing multi-segment matching you should be using PCRE_PARTIAL_HARD, which |
doing multi-segment matching you should be using PCRE_PARTIAL_HARD, which |
| includes the effect of PCRE_NOTEOL. |
includes the effect of PCRE_NOTEOL. |
| .P |
.P |
| 2. Lookbehind assertions at the start of a pattern are catered for in the | 2. Lookbehind assertions that have already been obeyed are catered for in the |
| offsets that are returned for a partial match. However, in theory, a lookbehind | offsets that are returned for a partial match. However a lookbehind assertion |
| assertion later in the pattern could require even earlier characters to be | later in the pattern could require even earlier characters to be inspected. You |
| inspected, and it might not have been reached when a partial match occurs. This | can handle this case by using the PCRE_INFO_MAXLOOKBEHIND option of the |
| is probably an extremely unlikely case; you could guard against it to a certain | \fBpcre_fullinfo()\fP or \fBpcre16_fullinfo()\fP functions to obtain the length |
| extent by always including extra characters at the start. | of the largest lookbehind in the pattern. This length is given in characters, |
| | not bytes. If you always retain at least that many characters before the |
| | partially matched string, all should be well. (Of course, near the start of the |
| | subject, fewer characters may be present; in that case all characters should be |
| | retained.) |
| .P |
.P |
| 3. Matching a subject string that is split into multiple segments may not | 3. Because a partial match must always contain at least one character, what |
| | might be considered a partial match of an empty string actually gives a "no |
| | match" result. For example: |
| | .sp |
| | re> /c(?<=abc)x/ |
| | data> ab\eP |
| | No match |
| | .sp |
| | If the next segment begins "cx", a match should be found, but this will only |
| | happen if characters from the previous segment are retained. For this reason, a |
| | "no match" result should be interpreted as "partial match of an empty string" |
| | when the pattern contains lookbehinds. |
| | .P |
| | 4. 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, |
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 |
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 |
Word Boundaries" above describes an issue that arises if the pattern ends with |
|
Line 343 longer possible. Consider again this \fBpcretest\fP ex
|
Line 371 longer possible. Consider again this \fBpcretest\fP ex
|
| 0: dogsbody |
0: dogsbody |
| 1: dog |
1: dog |
| .sp |
.sp |
| The first data line passes the string "dogsb" to \fBpcre_exec()\fP, setting the | The first data line passes the string "dogsb" to a standard matching function, |
| PCRE_PARTIAL_SOFT option. Although the string is a partial match for | setting the PCRE_PARTIAL_SOFT option. Although the string is a partial match |
| "dogsbody", the result is not PCRE_ERROR_PARTIAL, because the shorter string | for "dogsbody", the result is not PCRE_ERROR_PARTIAL, because the shorter |
| "dog" is a complete match. Similarly, when the subject is presented to | 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 | a DFA matching function in several parts ("do" and "gsb" being the first two) |
| match stops when "dog" has been found, and it is not possible to continue. On | the match stops when "dog" has been found, and it is not possible to continue. |
| the other hand, if "dogsbody" is presented as a single string, | On the other hand, if "dogsbody" is presented as a single string, a DFA |
| \fBpcre_dfa_exec()\fP finds both matches. | matching function finds both matches. |
| .P |
.P |
| Because of these problems, it is best to use PCRE_PARTIAL_HARD when matching |
Because of these problems, it is best to use PCRE_PARTIAL_HARD when matching |
| multi-segment data. The example above then behaves differently: |
multi-segment data. The example above then behaves differently: |
|
Line 363 multi-segment data. The example above then behaves dif
|
Line 391 multi-segment data. The example above then behaves dif
|
| data> gsb\eR\eP\eP\eD |
data> gsb\eR\eP\eP\eD |
| Partial match: gsb |
Partial match: gsb |
| .sp |
.sp |
| 4. Patterns that contain alternatives at the top level which do not all | 5. Patterns that contain alternatives at the top level which do not all start |
| start with the same pattern item may not work as expected when | with the same pattern item may not work as expected when PCRE_DFA_RESTART is |
| PCRE_DFA_RESTART is used with \fBpcre_dfa_exec()\fP. For example, consider this | used. For example, consider this pattern: |
| pattern: | |
| .sp |
.sp |
| 1234|3789 |
1234|3789 |
| .sp |
.sp |
|
Line 382 patterns or patterns such as:
|
Line 409 patterns or patterns such as:
|
| 1234|ABCD |
1234|ABCD |
| .sp |
.sp |
| where no string can be a partial match for both alternatives. This is not a |
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 | problem if a standard matching function is used, because the entire match has |
| each time: | to be rerun each time: |
| .sp |
.sp |
| re> /1234|3789/ |
re> /1234|3789/ |
| data> ABC123\eP\eP |
data> ABC123\eP\eP |
|
Line 392 each time:
|
Line 419 each time:
|
| 0: 3789 |
0: 3789 |
| .sp |
.sp |
| Of course, instead of using PCRE_DFA_RESTART, the same technique of re-running |
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 | the entire match can also be used with the DFA matching functions. Another |
| possibility is to work with two buffers. If a partial match at offset \fIn\fP |
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 |
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 second buffer, you can then try a new match starting at offset \fIn+1\fP in |
|
Line 413 Cambridge CB2 3QH, England.
|
Line 440 Cambridge CB2 3QH, England.
|
| .rs |
.rs |
| .sp |
.sp |
| .nf |
.nf |
| Last updated: 26 August 2011 | Last updated: 24 February 2012 |
| Copyright (c) 1997-2011 University of Cambridge. | Copyright (c) 1997-2012 University of Cambridge. |
| .fi |
.fi |
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pcrepartial.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc