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

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

Parent Directory | Revision Log | View Patch Patch

-revision 42 by nigel,
Sat Feb 24 21:39:17 2007 UTC
+revision 43 by nigel,
Sat Feb 24 21:39:21 2007 UTC
 Line 25 
 conversion went wrong.
  <LI><A NAME="TOC15" HREF="#SEC15">CIRCUMFLEX AND DOLLAR</A>
  <LI><A NAME="TOC16" HREF="#SEC16">FULL STOP (PERIOD, DOT)</A>
  <LI><A NAME="TOC17" HREF="#SEC17">SQUARE BRACKETS</A>
- <LI><A NAME="TOC18" HREF="#SEC18">VERTICAL BAR</A>
+ <LI><A NAME="TOC18" HREF="#SEC18">POSIX CHARACTER CLASSES</A>
- <LI><A NAME="TOC19" HREF="#SEC19">INTERNAL OPTION SETTING</A>
+ <LI><A NAME="TOC19" HREF="#SEC19">VERTICAL BAR</A>
- <LI><A NAME="TOC20" HREF="#SEC20">SUBPATTERNS</A>
+ <LI><A NAME="TOC20" HREF="#SEC20">INTERNAL OPTION SETTING</A>
- <LI><A NAME="TOC21" HREF="#SEC21">REPETITION</A>
+ <LI><A NAME="TOC21" HREF="#SEC21">SUBPATTERNS</A>
- <LI><A NAME="TOC22" HREF="#SEC22">BACK REFERENCES</A>
+ <LI><A NAME="TOC22" HREF="#SEC22">REPETITION</A>
- <LI><A NAME="TOC23" HREF="#SEC23">ASSERTIONS</A>
+ <LI><A NAME="TOC23" HREF="#SEC23">BACK REFERENCES</A>
- <LI><A NAME="TOC24" HREF="#SEC24">ONCE-ONLY SUBPATTERNS</A>
+ <LI><A NAME="TOC24" HREF="#SEC24">ASSERTIONS</A>
- <LI><A NAME="TOC25" HREF="#SEC25">CONDITIONAL SUBPATTERNS</A>
+ <LI><A NAME="TOC25" HREF="#SEC25">ONCE-ONLY SUBPATTERNS</A>
- <LI><A NAME="TOC26" HREF="#SEC26">COMMENTS</A>
+ <LI><A NAME="TOC26" HREF="#SEC26">CONDITIONAL SUBPATTERNS</A>
- <LI><A NAME="TOC27" HREF="#SEC27">PERFORMANCE</A>
+ <LI><A NAME="TOC27" HREF="#SEC27">COMMENTS</A>
- <LI><A NAME="TOC28" HREF="#SEC28">AUTHOR</A>
+ <LI><A NAME="TOC28" HREF="#SEC28">RECURSIVE PATTERNS</A>
+ <LI><A NAME="TOC29" HREF="#SEC29">PERFORMANCE</A>
+ <LI><A NAME="TOC30" HREF="#SEC30">AUTHOR</A>
  </UL>
  <LI><A NAME="SEC1" HREF="#TOC1">NAME</A>
  <P>
-Line 77 
 pcre - Perl-compatible regular expressio
+Line 79 
 pcre - Perl-compatible regular expressio
  <B>const unsigned char *pcre_maketables(void);</B>
  </P>
  <P>
+ <B>int pcre_fullinfo(const pcre *<I>code</I>, const pcre_extra *<I>extra</I>,</B>
+ <B>int <I>what</I>, void *<I>where</I>);</B>
+ </P>
+ <P>
  <B>int pcre_info(const pcre *<I>code</I>, int *<I>optptr</I>, int</B>
  <B>*<I>firstcharptr</I>);</B>
  </P>
-Line 93 
 pcre - Perl-compatible regular expressio
+Line 99 
 pcre - Perl-compatible regular expressio
  <P>
  The PCRE library is a set of functions that implement regular expression
  pattern matching using the same syntax and semantics as Perl 5, with just a few
- differences (see below). The current implementation corresponds to Perl 5.005.
+ differences (see below). The current implementation corresponds to Perl 5.005,
+ with some additional features from the Perl development release.
  </P>
  <P>
  PCRE has its own native API, which is described in this document. There is also
- a set of wrapper functions that correspond to the POSIX API. These are
+ a set of wrapper functions that correspond to the POSIX regular expression API.
- described in the <B>pcreposix</B> documentation.
+ These are described in the <B>pcreposix</B> documentation.
  </P>
  <P>
  The native API function prototypes are defined in the header file <B>pcre.h</B>,
  and on Unix systems the library itself is called <B>libpcre.a</B>, so can be
  accessed by adding <B>-lpcre</B> to the command for linking an application which
- calls it.
+ calls it. The header file defines the macros PCRE_MAJOR and PCRE_MINOR to
+ contain the major and minor release numbers for the library. Applications can
+ use these to include support for different releases.
  </P>
  <P>
  The functions <B>pcre_compile()</B>, <B>pcre_study()</B>, and <B>pcre_exec()</B>
-Line 116 
 captured substrings from a matched subje
+Line 125 
 captured substrings from a matched subje
  in the current locale for passing to <B>pcre_compile()</B>.
  </P>
  <P>
- The function <B>pcre_info()</B> is used to find out information about a compiled
+ The function <B>pcre_fullinfo()</B> is used to find out information about a
- pattern, while the function <B>pcre_version()</B> returns a pointer to a string
+ compiled pattern; <B>pcre_info()</B> is an obsolete version which returns only
- containing the version of PCRE and its date of release.
+ some of the available information, but is retained for backwards compatibility.
+ The function <B>pcre_version()</B> returns a pointer to a string containing the
+ version of PCRE and its date of release.
  </P>
  <P>
  The global variables <B>pcre_malloc</B> and <B>pcre_free</B> initially contain
-Line 246 
 sequence (?( which introduces a conditio
+Line 257 
 sequence (?( which introduces a conditio
  </PRE>
  </P>
  <P>
- This option turns on additional functionality of PCRE that is incompatible with
+ This option was invented in order to turn on additional functionality of PCRE
- Perl. Any backslash in a pattern that is followed by a letter that has no
+ that is incompatible with Perl, but it is currently of very little use. When
+ set, any backslash in a pattern that is followed by a letter that has no
  special meaning causes an error, thus reserving these combinations for future
  expansion. By default, as in Perl, a backslash followed by a letter with no
  special meaning is treated as a literal. There are at present no other features
- controlled by this option.
+ controlled by this option. It can also be set by a (?X) option setting within a
+ pattern.
  </P>
  <P>
  <PRE>
-Line 342 
 memory containing the tables remains ava
+Line 355 
 memory containing the tables remains ava
  </P>
  <LI><A NAME="SEC8" HREF="#TOC1">INFORMATION ABOUT A PATTERN</A>
  <P>
- The <B>pcre_info()</B> function returns information about a compiled pattern.
+ The <B>pcre_fullinfo()</B> function returns information about a compiled
- Its yield is the number of capturing subpatterns, or one of the following
+ pattern. It replaces the obsolete <B>pcre_info()</B> function, which is
- negative numbers:
+ nevertheless retained for backwards compability (and is documented below).
+ </P>
+ <P>
+ The first argument for <B>pcre_fullinfo()</B> is a pointer to the compiled
+ pattern. The second argument is the result of <B>pcre_study()</B>, or NULL if
+ the pattern was not studied. The third argument specifies which piece of
+ information is required, while the fourth argument is a pointer to a variable
+ to receive the data. The yield of the function is zero for success, or one of
+ the following negative numbers:
  </P>
  <P>
  <PRE>
    PCRE_ERROR_NULL       the argument <I>code</I> was NULL
+                         the argument <I>where</I> was NULL
    PCRE_ERROR_BADMAGIC   the "magic number" was not found
+   PCRE_ERROR_BADOPTION  the value of <I>what</I> was invalid
  </PRE>
  </P>
  <P>
- If the <I>optptr</I> argument is not NULL, a copy of the options with which the
+ The possible values for the third argument are defined in <B>pcre.h</B>, and are
- pattern was compiled is placed in the integer it points to. These option bits
+ as follows:
+ </P>
+ <P>
+ <PRE>
+   PCRE_INFO_OPTIONS
+ </PRE>
+ </P>
+ <P>
+ Return a copy of the options with which the pattern was compiled. The fourth
+ argument should point to au <B>unsigned long int</B> variable. These option bits
  are those specified in the call to <B>pcre_compile()</B>, modified by any
  top-level option settings within the pattern itself, and with the PCRE_ANCHORED
- bit set if the form of the pattern implies that it can match only at the start
+ bit forcibly set if the form of the pattern implies that it can match only at
- of a subject string.
+ the start of a subject string.
  </P>
  <P>
- If the pattern is not anchored and the <I>firstcharptr</I> argument is not NULL,
+ <PRE>
- it is used to pass back information about the first character of any matched
+   PCRE_INFO_SIZE
- string. If there is a fixed first character, e.g. from a pattern such as
+ </PRE>
- (cat|cow|coyote), then it is returned in the integer pointed to by
+ </P>
- <I>firstcharptr</I>. Otherwise, if either
+ <P>
+ Return the size of the compiled pattern, that is, the value that was passed as
+ the argument to <B>pcre_malloc()</B> when PCRE was getting memory in which to
+ place the compiled data. The fourth argument should point to a <B>size_t</B>
+ variable.
+ </P>
+ <P>
+ <PRE>
+   PCRE_INFO_CAPTURECOUNT
+ </PRE>
+ </P>
+ <P>
+ Return the number of capturing subpatterns in the pattern. The fourth argument
+ should point to an \fbint\fR variable.
+ </P>
+ <P>
+ <PRE>
+   PCRE_INFO_BACKREFMAX
+ </PRE>
+ </P>
+ <P>
+ Return the number of the highest back reference in the pattern. The fourth
+ argument should point to an <B>int</B> variable. Zero is returned if there are
+ no back references.
+ </P>
+ <P>
+ <PRE>
+   PCRE_INFO_FIRSTCHAR
+ </PRE>
+ </P>
+ <P>
+ Return information about the first character of any matched string, for a
+ non-anchored pattern. If there is a fixed first character, e.g. from a pattern
+ such as (cat|cow|coyote), then it is returned in the integer pointed to by
+ <I>where</I>. Otherwise, if either
  </P>
  <P>
  (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
-Line 378 
 starts with "^", or
+Line 444 
 starts with "^", or
  <P>
  then -1 is returned, indicating that the pattern matches only at the
  start of a subject string or after any "\n" within the string. Otherwise -2 is
- returned.
+ returned. For anchored patterns, -2 is returned.
+ </P>
+ <P>
+ <PRE>
+   PCRE_INFO_FIRSTTABLE
+ </PRE>
+ </P>
+ <P>
+ If the pattern was studied, and this resulted in the construction of a 256-bit
+ table indicating a fixed set of characters for the first character in any
+ matching string, a pointer to the table is returned. Otherwise NULL is
+ returned. The fourth argument should point to an <B>unsigned char *</B>
+ variable.
+ </P>
+ <P>
+ <PRE>
+   PCRE_INFO_LASTLITERAL
+ </PRE>
+ </P>
+ <P>
+ For a non-anchored pattern, return the value of the rightmost literal character
+ which must exist in any matched string, other than at its start. The fourth
+ argument should point to an <B>int</B> variable. If there is no such character,
+ or if the pattern is anchored, -1 is returned. For example, for the pattern
+ /a\d+z\d+/ the returned value is 'z'.
+ </P>
+ <P>
+ The <B>pcre_info()</B> function is now obsolete because its interface is too
+ restrictive to return all the available data about a compiled pattern. New
+ programs should use <B>pcre_fullinfo()</B> instead. The yield of
+ <B>pcre_info()</B> is the number of capturing subpatterns, or one of the
+ following negative numbers:
+ </P>
+ <P>
+ <PRE>
+   PCRE_ERROR_NULL       the argument <I>code</I> was NULL
+   PCRE_ERROR_BADMAGIC   the "magic number" was not found
+ </PRE>
+ </P>
+ <P>
+ If the <I>optptr</I> argument is not NULL, a copy of the options with which the
+ pattern was compiled is placed in the integer it points to (see
+ PCRE_INFO_OPTIONS above).
+ </P>
+ <P>
+ If the pattern is not anchored and the <I>firstcharptr</I> argument is not NULL,
+ it is used to pass back information about the first character of any matched
+ string (see PCRE_INFO_FIRSTCHAR above).
  </P>
  <LI><A NAME="SEC9" HREF="#TOC1">MATCHING A PATTERN</A>
  <P>
-Line 735 
 are not part of its pattern matching eng
+Line 848 
 are not part of its pattern matching eng
  pattern matches.
  </P>
  <P>
-. Fairly obviously, PCRE does not support the (?{code}) construction.
+. Fairly obviously, PCRE does not support the (?{code}) and (?p{code})
+ constructions. However, there is some experimental support for recursive
+ patterns using the non-Perl item (?R).
  </P>
  <P>
 . There are at the time of writing some oddities in Perl 5.005_02 concerned
-Line 783 
 of the subject.
+Line 898 
 of the subject.
  (f) The PCRE_NOTBOL, PCRE_NOTEOL, and PCRE_NOTEMPTY options for
  <B>pcre_exec()</B> have no Perl equivalents.
  </P>
+ <P>
+ (g) The (?R) construct allows for recursive pattern matching (Perl 5.6 can do
+ this using the (?p{code}) construct, which PCRE cannot of course support.)
+ </P>
  <LI><A NAME="SEC13" HREF="#TOC1">REGULAR EXPRESSION DETAILS</A>
  <P>
  The syntax and semantics of the regular expressions supported by PCRE are
  described below. Regular expressions are also described in the Perl
  documentation and in a number of other books, some of which have copious
  examples. Jeffrey Friedl's "Mastering Regular Expressions", published by
- O'Reilly (ISBN 1-56592-257-3), covers them in great detail. The description
+ O'Reilly (ISBN 1-56592-257), covers them in great detail. The description
  here is intended as reference documentation.
  </P>
  <P>
-Line 1144 
 All non-alphameric characters other than
+Line 1263 
 All non-alphameric characters other than
  terminating ] are non-special in character classes, but it does no harm if they
  are escaped.
  </P>
- <LI><A NAME="SEC18" HREF="#TOC1">VERTICAL BAR</A>
+ <LI><A NAME="SEC18" HREF="#TOC1">POSIX CHARACTER CLASSES</A>
+ <P>
+ Perl 5.6 (not yet released at the time of writing) is going to support the
+ POSIX notation for character classes, which uses names enclosed by [: and :]
+ within the enclosing square brackets. PCRE supports this notation. For example,
+ </P>
+ <P>
+ <PRE>
+   [01[:alpha:]%]
+ </PRE>
+ </P>
+ <P>
+ matches "0", "1", any alphabetic character, or "%". The supported class names
+ are
+ </P>
+ <P>
+ <PRE>
+   alnum    letters and digits
+   alpha    letters
+   ascii    character codes 0 - 127
+   cntrl    control characters
+   digit    decimal digits (same as \d)
+   graph    printing characters, excluding space
+   lower    lower case letters
+   print    printing characters, including space
+   punct    printing characters, excluding letters and digits
+   space    white space (same as \s)
+   upper    upper case letters
+   word     "word" characters (same as \w)
+   xdigit   hexadecimal digits
+ </PRE>
+ </P>
+ <P>
+ The names "ascii" and "word" are Perl extensions. Another Perl extension is
+ negation, which is indicated by a ^ character after the colon. For example,
+ </P>
+ <P>
+ <PRE>
+   [12[:^digit:]]
+ </PRE>
+ </P>
+ <P>
+ matches "1", "2", or any non-digit. PCRE (and Perl) also recogize the POSIX
+ syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not
+ supported, and an error is given if they are encountered.
+ </P>
+ <LI><A NAME="SEC19" HREF="#TOC1">VERTICAL BAR</A>
  <P>
  Vertical bar characters are used to separate alternative patterns. For example,
  the pattern
-Line 1162 
 and the first one that succeeds is used.
+Line 1327 
 and the first one that succeeds is used.
  subpattern (defined below), "succeeds" means matching the rest of the main
  pattern as well as the alternative in the subpattern.
  </P>
- <LI><A NAME="SEC19" HREF="#TOC1">INTERNAL OPTION SETTING</A>
+ <LI><A NAME="SEC20" HREF="#TOC1">INTERNAL OPTION SETTING</A>
  <P>
  The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED
  can be changed from within the pattern by a sequence of Perl option letters
-Line 1238 
 respectively. The (?X) flag setting is s
+Line 1403 
 respectively. The (?X) flag setting is s
  earlier in the pattern than any of the additional features it turns on, even
  when it is at top level. It is best put at the start.
  </P>
- <LI><A NAME="SEC20" HREF="#TOC1">SUBPATTERNS</A>
+ <LI><A NAME="SEC21" HREF="#TOC1">SUBPATTERNS</A>
  <P>
  Subpatterns are delimited by parentheses (round brackets), which can be nested.
  Marking part of a pattern as a subpattern does two things:
-Line 1309 
 from left to right, and options are not
+Line 1474 
 from left to right, and options are not
  is reached, an option setting in one branch does affect subsequent branches, so
  the above patterns match "SUNDAY" as well as "Saturday".
  </P>
- <LI><A NAME="SEC21" HREF="#TOC1">REPETITION</A>
+ <LI><A NAME="SEC22" HREF="#TOC1">REPETITION</A>
  <P>
  Repetition is specified by quantifiers, which can follow any of the following
  items:
-Line 1484 
 example, after
+Line 1649 
 example, after
  <P>
  matches "aba" the value of the second captured substring is "b".
  </P>
- <LI><A NAME="SEC22" HREF="#TOC1">BACK REFERENCES</A>
+ <LI><A NAME="SEC23" HREF="#TOC1">BACK REFERENCES</A>
  <P>
  Outside a character class, a backslash followed by a digit greater than 0 (and
  possibly further digits) is a back reference to a capturing subpattern earlier
-Line 1560 
 that the first iteration does not need t
+Line 1725 
 that the first iteration does not need t
  done using alternation, as in the example above, or by a quantifier with a
  minimum of zero.
  </P>
- <LI><A NAME="SEC23" HREF="#TOC1">ASSERTIONS</A>
+ <LI><A NAME="SEC24" HREF="#TOC1">ASSERTIONS</A>
  <P>
  An assertion is a test on the characters following or preceding the current
  matching point that does not actually consume any characters. The simple
-Line 1718 
 because it does not make sense for negat
+Line 1883 
 because it does not make sense for negat
  <P>
  Assertions count towards the maximum of 200 parenthesized subpatterns.
  </P>
- <LI><A NAME="SEC24" HREF="#TOC1">ONCE-ONLY SUBPATTERNS</A>
+ <LI><A NAME="SEC25" HREF="#TOC1">ONCE-ONLY SUBPATTERNS</A>
  <P>
  With both maximizing and minimizing repetition, failure of what follows
  normally causes the repeated item to be re-evaluated to see if a different
-Line 1782 
 pattern such as
+Line 1947 
 pattern such as
  </PRE>
  </P>
  <P>
- when applied to a long string which does not match it. Because matching
+ when applied to a long string which does not match. Because matching proceeds
- proceeds from left to right, PCRE will look for each "a" in the subject and
+ from left to right, PCRE will look for each "a" in the subject and then see if
- then see if what follows matches the rest of the pattern. If the pattern is
+ what follows matches the rest of the pattern. If the pattern is specified as
- specified as
  </P>
  <P>
  <PRE>
-Line 1793 
 specified as
+Line 1957 
 specified as
  </PRE>
  </P>
  <P>
- then the initial .* matches the entire string at first, but when this fails, it
+ then the initial .* matches the entire string at first, but when this fails
- backtracks to match all but the last character, then all but the last two
+ (because there is no following "a"), it backtracks to match all but the last
- characters, and so on. Once again the search for "a" covers the entire string,
+ character, then all but the last two characters, and so on. Once again the
- from right to left, so we are no better off. However, if the pattern is written
+ search for "a" covers the entire string, from right to left, so we are no
- as
+ better off. However, if the pattern is written as
  </P>
  <P>
  <PRE>
-Line 1810 
 string. The subsequent lookbehind assert
+Line 1974 
 string. The subsequent lookbehind assert
  characters. If it fails, the match fails immediately. For long strings, this
  approach makes a significant difference to the processing time.
  </P>
- <LI><A NAME="SEC25" HREF="#TOC1">CONDITIONAL SUBPATTERNS</A>
+ <P>
+ When a pattern contains an unlimited repeat inside a subpattern that can itself
+ be repeated an unlimited number of times, the use of a once-only subpattern is
+ the only way to avoid some failing matches taking a very long time indeed.
+ The pattern
+ </P>
+ <P>
+ <PRE>
+   (\D+|&#60;\d+&#62;)*[!?]
+ </PRE>
+ </P>
+ <P>
+ matches an unlimited number of substrings that either consist of non-digits, or
+ digits enclosed in &#60;&#62;, followed by either ! or ?. When it matches, it runs
+ quickly. However, if it is applied to
+ </P>
+ <P>
+ <PRE>
+   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ </PRE>
+ </P>
+ <P>
+ it takes a long time before reporting failure. This is because the string can
+ be divided between the two repeats in a large number of ways, and all have to
+ be tried. (The example used [!?] rather than a single character at the end,
+ because both PCRE and Perl have an optimization that allows for fast failure
+ when a single character is used. They remember the last single character that
+ is required for a match, and fail early if it is not present in the string.)
+ If the pattern is changed to
+ </P>
+ <P>
+ <PRE>
+   ((?&#62;\D+)|&#60;\d+&#62;)*[!?]
+ </PRE>
+ </P>
+ <P>
+ sequences of non-digits cannot be broken, and failure happens quickly.
+ </P>
+ <LI><A NAME="SEC26" HREF="#TOC1">CONDITIONAL SUBPATTERNS</A>
  <P>
  It is possible to cause the matching process to obey a subpattern
  conditionally or to choose between two alternative subpatterns, depending on
-Line 1872 
 subject is matched against the first alt
+Line 2074 
 subject is matched against the first alt
  against the second. This pattern matches strings in one of the two forms
  dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.
  </P>
- <LI><A NAME="SEC26" HREF="#TOC1">COMMENTS</A>
+ <LI><A NAME="SEC27" HREF="#TOC1">COMMENTS</A>
  <P>
  The sequence (?# marks the start of a comment which continues up to the next
  closing parenthesis. Nested parentheses are not permitted. The characters
-Line 1883 
 If the PCRE_EXTENDED option is set, an u
+Line 2085 
 If the PCRE_EXTENDED option is set, an u
  character class introduces a comment that continues up to the next newline
  character in the pattern.
  </P>
- <LI><A NAME="SEC27" HREF="#TOC1">PERFORMANCE</A>
+ <LI><A NAME="SEC28" HREF="#TOC1">RECURSIVE PATTERNS</A>
+ <P>
+ Consider the problem of matching a string in parentheses, allowing for
+ unlimited nested parentheses. Without the use of recursion, the best that can
+ be done is to use a pattern that matches up to some fixed depth of nesting. It
+ is not possible to handle an arbitrary nesting depth. Perl 5.6 has provided an
+ experimental facility that allows regular expressions to recurse (amongst other
+ things). It does this by interpolating Perl code in the expression at run time,
+ and the code can refer to the expression itself. A Perl pattern to solve the
+ parentheses problem can be created like this:
+ </P>
+ <P>
+ <PRE>
+   $re = qr{\( (?: (?&#62;[^()]+) | (?p{$re}) )* \)}x;
+ </PRE>
+ </P>
+ <P>
+ The (?p{...}) item interpolates Perl code at run time, and in this case refers
+ recursively to the pattern in which it appears. Obviously, PCRE cannot support
+ the interpolation of Perl code. Instead, the special item (?R) is provided for
+ the specific case of recursion. This PCRE pattern solves the parentheses
+ problem (assume the PCRE_EXTENDED option is set so that white space is
+ ignored):
+ </P>
+ <P>
+ <PRE>
+   \( ( (?&#62;[^()]+) | (?R) )* \)
+ </PRE>
+ </P>
+ <P>
+ First it matches an opening parenthesis. Then it matches any number of
+ substrings which can either be a sequence of non-parentheses, or a recursive
+ match of the pattern itself (i.e. a correctly parenthesized substring). Finally
+ there is a closing parenthesis.
+ </P>
+ <P>
+ This particular example pattern contains nested unlimited repeats, and so the
+ use of a once-only subpattern for matching strings of non-parentheses is
+ important when applying the pattern to strings that do not match. For example,
+ when it is applied to
+ </P>
+ <P>
+ <PRE>
+   (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
+ </PRE>
+ </P>
+ <P>
+ it yields "no match" quickly. However, if a once-only subpattern is not used,
+ the match runs for a very long time indeed because there are so many different
+ ways the + and * repeats can carve up the subject, and all have to be tested
+ before failure can be reported.
+ </P>
+ <P>
+ The values set for any capturing subpatterns are those from the outermost level
+ of the recursion at which the subpattern value is set. If the pattern above is
+ matched against
+ </P>
+ <P>
+ <PRE>
+   (ab(cd)ef)
+ </PRE>
+ </P>
+ <P>
+ the value for the capturing parentheses is "ef", which is the last value taken
+ on at the top level. If additional parentheses are added, giving
+ </P>
+ <P>
+ <PRE>
+   \( ( ( (?&#62;[^()]+) | (?R) )* ) \)
+      ^                        ^
+      ^                        ^
+ </PRE>
+ then the string they capture is "ab(cd)ef", the contents of the top level
+ parentheses. If there are more than 15 capturing parentheses in a pattern, PCRE
+ has to obtain extra memory to store data during a recursion, which it does by
+ using <B>pcre_malloc</B>, freeing it via <B>pcre_free</B> afterwards. If no
+ memory can be obtained, it saves data for the first 15 capturing parentheses
+ only, as there is no way to give an out-of-memory error from within a
+ recursion.
+ </P>
+ <LI><A NAME="SEC29" HREF="#TOC1">PERFORMANCE</A>
  <P>
  Certain items that may appear in patterns are more efficient than others. It is
  more efficient to use a character class like [aeiou] than a set of alternatives
-Line 1959 
 with the pattern above. The former gives
+Line 2241 
 with the pattern above. The former gives
  applied to a whole line of "a" characters, whereas the latter takes an
  appreciable time with strings longer than about 20 characters.
  </P>
- <LI><A NAME="SEC28" HREF="#TOC1">AUTHOR</A>
+ <LI><A NAME="SEC30" HREF="#TOC1">AUTHOR</A>
  <P>
  Philip Hazel &#60;ph10@cam.ac.uk&#62;
  <BR>
-Line 1972 
 Cambridge CB2 3QG, England.
+Line 2254 
 Cambridge CB2 3QG, England.
  Phone: +44 1223 334714
  </P>
  <P>
- Last updated: 29 July 1999
+ Last updated: 27 January 2000
  <BR>
- Copyright (c) 1997-1999 University of Cambridge.
+ Copyright (c) 1997-2000 University of Cambridge.

 Legend:



Removed from v.42
 


changed lines


 
Added in v.43
 Legend:



Removed from v.42
 


changed lines


 
Added in v.43
-Removed from v.42
+Added in v.43

	ViewVC Help
Powered by ViewVC 1.1.5