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

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

Parent Directory | Revision Log | View Patch Patch

-revision 460 by ph10,
Tue Sep 22 09:42:11 2009 UTC
+revision 461 by ph10,
Mon Oct  5 10:59:35 2009 UTC
 Line 400 
 avoiding the use of the stack.
  Either of the functions <b>pcre_compile()</b> or <b>pcre_compile2()</b> can be
  called to compile a pattern into an internal form. The only difference between
  the two interfaces is that <b>pcre_compile2()</b> has an additional argument,
- <i>errorcodeptr</i>, via which a numerical error code can be returned.
+ <i>errorcodeptr</i>, via which a numerical error code can be returned. To avoid
+ too much repetition, we refer just to <b>pcre_compile()</b> below, but the
+ information applies equally to <b>pcre_compile2()</b>.
  </P>
  <P>
  The pattern is a C string terminated by a binary zero, and is passed in the
-Line 420 
 argument, which is an address (see below
+Line 422 
 argument, which is an address (see below
  The <i>options</i> argument contains various bit settings that affect the
  compilation. It should be zero if no options are required. The available
  options are described below. Some of them (in particular, those that are
- compatible with Perl, but also some others) can also be set and unset from
+ compatible with Perl, but some others as well) can also be set and unset from
  within the pattern (see the detailed description in the
  <a href="pcrepattern.html"><b>pcrepattern</b></a>
  documentation). For those options that can be different in different parts of
- the pattern, the contents of the <i>options</i> argument specifies their initial
+ the pattern, the contents of the <i>options</i> argument specifies their
- settings at the start of compilation and execution. The PCRE_ANCHORED and
+ settings at the start of compilation and execution. The PCRE_ANCHORED,
- PCRE_NEWLINE_<i>xxx</i> options can be set at the time of matching as well as at
+ PCRE_BSR_<i>xxx</i>, and PCRE_NEWLINE_<i>xxx</i> options can be set at the time
- compile time.
+ of matching as well as at compile time.
  </P>
  <P>
  If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately.
-Line 435 
 Otherwise, if compilation of a pattern f
+Line 437 
 Otherwise, if compilation of a pattern f
  NULL, and sets the variable pointed to by <i>errptr</i> to point to a textual
  error message. This is a static string that is part of the library. You must
  not try to free it. The byte offset from the start of the pattern to the
- character that was being processes when the error was discovered is placed in
+ character that was being processed when the error was discovered is placed in
  the variable pointed to by <i>erroffset</i>, which must not be NULL. If it is,
  an immediate error is given. Some errors are not detected until checks are
  carried out when the whole pattern has been scanned; in this case the offset is
-Line 772 
 results of the study.
+Line 774 
 results of the study.
  </P>
  <P>
  The returned value from <b>pcre_study()</b> can be passed directly to
- <b>pcre_exec()</b>. However, a <b>pcre_extra</b> block also contains other
+ <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. However, a <b>pcre_extra</b> block
- fields that can be set by the caller before the block is passed; these are
+ also contains other fields that can be set by the caller before the block is
- described
+ passed; these are described
  <a href="#extradata">below</a>
  in the section on matching a pattern.
  </P>
  <P>
- If studying the pattern does not produce any additional information
+ If studying the pattern does not produce any useful information,
  <b>pcre_study()</b> returns NULL. In that circumstance, if the calling program
- wants to pass any of the other fields to <b>pcre_exec()</b>, it must set up its
+ wants to pass any of the other fields to <b>pcre_exec()</b> or
- own <b>pcre_extra</b> block.
+ <b>pcre_dfa_exec()</b>, it must set up its own <b>pcre_extra</b> block.
  </P>
  <P>
  The second argument of <b>pcre_study()</b> contains option bits. At present, no
-Line 805 
 This is a typical call to pcre_study<
+Line 807 
 This is a typical call to pcre_study<
 ,              /* no options exist */
      &error);        /* set to NULL or points to a message */
  </pre>
- At present, studying a pattern is useful only for non-anchored patterns that do
+ Studying a pattern does two things: first, a lower bound for the length of
- not have a single fixed starting character. A bitmap of possible starting
+ subject string that is needed to match the pattern is computed. This does not
- bytes is created.
+ mean that there are any strings of that length that match, but it does
+ guarantee that no shorter strings match. The value is used by
+ <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b> to avoid wasting time by trying to
+ match strings that are shorter than the lower bound. You can find out the value
+ in a calling program via the <b>pcre_fullinfo()</b> function.
+ </P>
+ <P>
+ Studying a pattern is also useful for non-anchored patterns that do not have a
+ single fixed starting character. A bitmap of possible starting bytes is
+ created. This speeds up finding a position in the subject at which to start
+ matching.
  <a name="localesupport"></a></P>
  <br><a name="SEC10" href="#TOC1">LOCALE SUPPORT</a><br>
  <P>
-Line 978 
 follows something of variable length. Fo
+Line 990 
 follows something of variable length. Fo
  /^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value
  is -1.
  <pre>
+   PCRE_INFO_MINLENGTH
+ </pre>
+ If the pattern was studied and a minimum length for matching subject strings
+ was computed, its value is returned. Otherwise the returned value is -1. The
+ value is a number of characters, not bytes (this may be relevant in UTF-8
+ mode). The fourth argument should point to an <b>int</b> variable. A
+ non-negative value is a lower bound to the length of any matching string. There
+ may not be any strings of that length that do actually match, but every string
+ that does match is at least that long.
+ <pre>
    PCRE_INFO_NAMECOUNT
    PCRE_INFO_NAMEENTRYSIZE
    PCRE_INFO_NAMETABLE
-Line 999 
 entry; both of these return an int
+Line 1021 
 entry; both of these return an int
  length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first
  entry of the table (a pointer to <b>char</b>). The first two bytes of each entry
  are the number of the capturing parenthesis, most significant byte first. The
- rest of the entry is the corresponding name, zero terminated. The names are in
+ rest of the entry is the corresponding name, zero terminated.
- alphabetical order. When PCRE_DUPNAMES is set, duplicate names are in order of
+ </P>
- their parentheses numbers. For example, consider the following pattern (assume
+ <P>
- PCRE_EXTENDED is set, so white space - including newlines - is ignored):
+ The names are in alphabetical order. Duplicate names may appear if (?| is used
+ to create multiple groups with the same number, as described in the
+ <a href="pcrepattern.html#dupsubpatternnumber">section on duplicate subpattern numbers</a>
+ in the
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
+ page. Duplicate names for subpatterns with different numbers are permitted only
+ if PCRE_DUPNAMES is set. In all cases of duplicate names, they appear in the
+ table in the order in which they were found in the pattern. In the absence of
+ (?| this is the order of increasing number; when (?| is used this is not
+ necessarily the case because later subpatterns may have lower numbers.
+ </P>
+ <P>
+ As a simple example of the name/number table, consider the following pattern
+ (assume PCRE_EXTENDED is set, so white space - including newlines - is
+ ignored):
  <pre>
    (?&#60;date&#62; (?&#60;year&#62;(\d\d)?\d\d) - (?&#60;month&#62;\d\d) - (?&#60;day&#62;\d\d) )
  </pre>
-Line 1062 
 variable.
+Line 1098 
 variable.
  Return the size of the data block pointed to by the <i>study_data</i> field in
  a <b>pcre_extra</b> block. That is, it is the value that was passed to
  <b>pcre_malloc()</b> when PCRE was getting memory into which to place the data
- created by <b>pcre_study()</b>. The fourth argument should point to a
+ created by <b>pcre_study()</b>. If <b>pcre_extra</b> is NULL, or there is no
+ study data, zero is returned. The fourth argument should point to a
  <b>size_t</b> variable.
  </P>
  <br><a name="SEC12" href="#TOC1">OBSOLETE INFO FUNCTION</a><br>
-Line 1122 
 is different. (This seems a highly unlik
+Line 1159 
 is different. (This seems a highly unlik
  <P>
  The function <b>pcre_exec()</b> is called to match a subject string against a
  compiled pattern, which is passed in the <i>code</i> argument. If the
- pattern has been studied, the result of the study should be passed in the
+ pattern was studied, the result of the study should be passed in the
  <i>extra</i> argument. This function is the main matching facility of the
  library, and it operates in a Perl-like manner. For specialist use there is
  also an alternative matching function, which is described
-Line 1189 
 the block by setting the other fields an
+Line 1226 
 the block by setting the other fields an
  The <i>match_limit</i> field provides a means of preventing PCRE from using up a
  vast amount of resources when running patterns that are not going to match,
  but which have a very large number of possibilities in their search trees. The
- classic example is the use of nested unlimited repeats.
+ classic example is a pattern that uses nested unlimited repeats.
  </P>
  <P>
  Internally, PCRE uses a function called <b>match()</b> which it calls repeatedly
-Line 1339 
 valid, so PCRE searches further into the
+Line 1376 
 valid, so PCRE searches further into the
  <pre>
    PCRE_NOTEMPTY_ATSTART
  </pre>
  This is like PCRE_NOTEMPTY, except that an empty string match that is not at
  the start of the subject is permitted. If the pattern is anchored, such a match
  can occur only if the pattern contains \K.
  </P>
-Line 1390 
 PCRE_NO_UTF8_CHECK is set, the effect of
+Line 1427 
 PCRE_NO_UTF8_CHECK is set, the effect of
  subject, or a value of <i>startoffset</i> that does not point to the start of a
  UTF-8 character, is undefined. Your program may crash.
  <pre>
    PCRE_PARTIAL_HARD
    PCRE_PARTIAL_SOFT
  </pre>
  These options turn on the partial matching feature. For backwards
-Line 1499 
 has to get additional memory for use dur
+Line 1536 
 has to get additional memory for use dur
  advisable to supply an <i>ovector</i>.
  </P>
  <P>
- The <b>pcre_info()</b> function can be used to find out how many capturing
+ The <b>pcre_fullinfo()</b> function can be used to find out how many capturing
  subpatterns there are in a compiled pattern. The smallest size for
  <i>ovector</i> that will allow for <i>n</i> captured substrings, in addition to
  the offsets of the substring matched by the whole pattern, is (<i>n</i>+1)*3.
-Line 1605 
 documentation for details of partial mat
+Line 1642 
 documentation for details of partial mat
  </pre>
  This code is no longer in use. It was formerly returned when the PCRE_PARTIAL
  option was used with a compiled pattern containing items that were not
  supported for partial matching. From release 8.00 onwards, there are no
  restrictions on partial matching.
  <pre>
    PCRE_ERROR_INTERNAL       (-14)
-Line 1779 
 appropriate. NOTE: If PCRE_DUPNAM
+Line 1816 
 appropriate. NOTE: If PCRE_DUPNAM
  the behaviour may not be what you want (see the next section).
  </P>
  <P>
- <b>Warning:</b> If the pattern uses the "(?|" feature to set up multiple
+ <b>Warning:</b> If the pattern uses the (?| feature to set up multiple
- subpatterns with the same number, you cannot use names to distinguish them,
+ subpatterns with the same number, as described in the
- because names are not included in the compiled code. The matching process uses
+ <a href="pcrepattern.html#dupsubpatternnumber">section on duplicate subpattern numbers</a>
- only numbers.
+ in the
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
+ page, you cannot use names to distinguish the different subpatterns, because
+ names are not included in the compiled code. The matching process uses only
+ numbers. For this reason, the use of different names for subpatterns of the
+ same number causes an error at compile time.
  </P>
  <br><a name="SEC17" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br>
  <P>
-Line 1791 
 only numbers.
+Line 1833 
 only numbers.
  </P>
  <P>
  When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns
- are not required to be unique. Normally, patterns with duplicate names are such
+ are not required to be unique. (Duplicate names are always allowed for
- that in any one match, only one of the named subpatterns participates. An
+ subpatterns with the same number, created by using the (?| feature. Indeed, if
- example is shown in the
+ such subpatterns are named, they are required to use the same names.)
+ </P>
+ <P>
+ Normally, patterns with duplicate names are such that in any one match, only
+ one of the named subpatterns participates. An example is shown in the
  <a href="pcrepattern.html"><b>pcrepattern</b></a>
  documentation.
  </P>
-Line 1849 
 a compiled pattern, using a matching alg
+Line 1895 
 a compiled pattern, using a matching alg
  just once, and does not backtrack. This has different characteristics to the
  normal algorithm, and is not compatible with Perl. Some of the features of PCRE
  patterns are not supported. Nevertheless, there are times when this kind of
  matching can be useful. For a discussion of the two matching algorithms, and a
  list of features that <b>pcre_dfa_exec()</b> does not support, see the
  <a href="pcrematching.html"><b>pcrematching</b></a>
  documentation.
-Line 1898 
 and PCRE_DFA_RESTART. All but the last f
+Line 1944 
 and PCRE_DFA_RESTART. All but the last f
  for <b>pcre_exec()</b>, so their description is not repeated here.
  <pre>
    PCRE_PARTIAL_HARD
    PCRE_PARTIAL_SOFT
  </pre>
  These have the same general effect as they do for <b>pcre_exec()</b>, but the
  details are slightly different. When PCRE_PARTIAL_HARD is set for
-Line 2021 
 Cambridge CB2 3QH, England.
+Line 2067 
 Cambridge CB2 3QH, England.
  </P>
  <br><a name="SEC22" href="#TOC1">REVISION</a><br>
  <P>
- Last updated: 22 September 2009
+ Last updated: 03 October 2009
  <br>
  Copyright &copy; 1997-2009 University of Cambridge.
  <br>

 Legend:



Removed from v.460
 


changed lines


 
Added in v.461
 Legend:



Removed from v.460
 


changed lines


 
Added in v.461
-Removed from v.460
+Added in v.461

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12