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

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

Parent Directory | Revision Log | View Patch Patch

-revision 525 by ph10,
Wed May 26 10:50:24 2010 UTC
+revision 547 by ph10,
Mon Jun 21 14:06:54 2010 UTC
 Line 134 
 Applications can use these to include su
  .P
  In a Windows environment, if you want to statically link an application program
  against a non-dll \fBpcre.a\fP file, you must define PCRE_STATIC before
- including \fBpcre.h\fP, because otherwise the \fBpcre_malloc()\fP and
+ including \fBpcre.h\fP or \fBpcrecpp.h\fP, because otherwise the
- \fBpcre_free()\fP exported functions will be declared
+ \fBpcre_malloc()\fP and \fBpcre_free()\fP exported functions will be declared
  \fB__declspec(dllimport)\fP, with unwanted results.
  .P
  The functions \fBpcre_compile()\fP, \fBpcre_compile2()\fP, \fBpcre_study()\fP,
 Line 765 
 out of use. To avoid confusion, they hav
  [this code is not in use]
  octal value is greater than \e377 (not in UTF-8 mode)
  internal error: overran compiling workspace
- internal error: previously-checked referenced subpattern not found
+ internal error: previously-checked referenced subpattern
+         not found
  DEFINE group contains more than one branch
  repeating a DEFINE group is not allowed
  inconsistent NEWLINE options
-Line 778 
 out of use. To avoid confusion, they hav
+Line 779 
 out of use. To avoid confusion, they hav
  subpattern name expected
  digit expected after (?+
  ] is an invalid data character in JavaScript compatibility mode
- different names for subpatterns of the same number are not allowed
+ different names for subpatterns of the same number are
+         not allowed
  (*MARK) must have an argument
  this version of PCRE is not compiled with PCRE_UCP support
  .sp
-Line 846 
 Studying a pattern is also useful for no
+Line 848 
 Studying a pattern is also useful for no
  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.
+ .P
+ The two optimizations just described can be disabled by setting the
+ PCRE_NO_START_OPTIMIZE option when calling \fBpcre_exec()\fP or
+ \fBpcre_dfa_exec()\fP. You might want to do this if your pattern contains
+ callouts, or make use of (*MARK), and you make use of these in cases where
+ matching fails. See the discussion of PCRE_NO_START_OPTIMIZE
+ .\" HTML <a href="#execoptions">
+ .\" </a>
+ below.
+ .\"
  .
  .
  .\" HTML <a name="localesupport"></a>
-Line 1443 
 sample program.
+Line 1455 
 sample program.
    PCRE_NO_START_OPTIMIZE
  .sp
  There are a number of optimizations that \fBpcre_exec()\fP uses at the start of
- a match, in order to speed up the process. For example, if it is known that a
+ a match, in order to speed up the process. For example, if it is known that an
- match must start with a specific character, it searches the subject for that
+ unanchored match must start with a specific character, it searches the subject
- character, and fails immediately if it cannot find it, without actually running
+ for that character, and fails immediately if it cannot find it, without
- the main matching function. When callouts are in use, these optimizations can
+ actually running the main matching function. This means that a special item
- cause them to be skipped. This option disables the "start-up" optimizations,
+ such as (*COMMIT) at the start of a pattern is not considered until after a
- causing performance to suffer, but ensuring that the callouts do occur.
+ suitable starting point for the match has been found. When callouts or (*MARK)
+ items are in use, these "start-up" optimizations can cause them to be skipped
+ if the pattern is never actually used. The start-up optimizations are in effect
+ a pre-scan of the subject that takes place before the pattern is run.
+ .P
+ The PCRE_NO_START_OPTIMIZE option disables the start-up optimizations, possibly
+ causing performance to suffer, but ensuring that in cases where the result is
+ "no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK)
+ are considered at every possible starting position in the subject string.
+ Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation.
+ Consider the pattern
+ .sp
+   (*COMMIT)ABC
+ .sp
+ When this is compiled, PCRE records the fact that a match must start with the
+ character "A". Suppose the subject string is "DEFABC". The start-up
+ optimization scans along the subject, finds "A" and runs the first match
+ attempt from there. The (*COMMIT) item means that the pattern must match the
+ current starting position, which in this case, it does. However, if the same
+ match is run with PCRE_NO_START_OPTIMIZE set, the initial scan along the
+ subject string does not happen. The first match attempt is run starting from
+ "D" and when this fails, (*COMMIT) prevents any further matches being tried, so
+ the overall result is "no match". If the pattern is studied, more start-up
+ optimizations may be used. For example, a minimum length for the subject may be
+ recorded. Consider the pattern
+ .sp
+   (*MARK:A)(X|Y)
+ .sp
+ The minimum length for a match is one character. If the subject is "ABC", there
+ will be attempts to match "ABC", "BC", "C", and then finally an empty string.
+ If the pattern is studied, the final attempt does not take place, because PCRE
+ knows that the subject is too short, and so the (*MARK) is never encountered.
+ In this case, studying the pattern does not affect the overall match result,
+ which is still "no match", but it does affect the auxiliary information that is
+ returned.
  .sp
    PCRE_NO_UTF8_CHECK
  .sp
-Line 1643 
 If a pattern contains back references, b
+Line 1689 
 If a pattern contains back references, b
  gets a block of memory at the start of matching to use for this purpose. If the
  call via \fBpcre_malloc()\fP fails, this error is given. The memory is
  automatically freed at the end of matching.
+ .P
+ This error is also given if \fBpcre_stack_malloc()\fP fails in
+ \fBpcre_exec()\fP. This can happen only when PCRE has been compiled with
+ \fB--disable-stack-for-recursion\fP.
  .sp
    PCRE_ERROR_NOSUBSTRING    (-7)
  .sp
-Line 1991 
 Here is an example of a simple call to \
+Line 2041 
 Here is an example of a simple call to \
  The unused bits of the \fIoptions\fP argument for \fBpcre_dfa_exec()\fP must be
  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,
  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
- PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, PCRE_PARTIAL_SOFT, PCRE_DFA_SHORTEST,
+ PCRE_NO_UTF8_CHECK, PCRE_BSR_ANYCRLF, PCRE_BSR_UNICODE, PCRE_NO_START_OPTIMIZE,
- and PCRE_DFA_RESTART. All but the last four of these are exactly the same as
+ PCRE_PARTIAL_HARD, PCRE_PARTIAL_SOFT, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART.
- for \fBpcre_exec()\fP, so their description is not repeated here.
+ All but the last four of these are exactly the same as for \fBpcre_exec()\fP,
+ so their description is not repeated here.
  .sp
    PCRE_PARTIAL_HARD
    PCRE_PARTIAL_SOFT
-Line 2127 
 Cambridge CB2 3QH, England.
+Line 2178 
 Cambridge CB2 3QH, England.
  .rs
  .sp
  .nf
- Last updated: 26 May 2010
+ Last updated: 21 June 2010
  Copyright (c) 1997-2010 University of Cambridge.
  .fi

 Legend:



Removed from v.525
 


changed lines


 
Added in v.547
 Legend:



Removed from v.525
 


changed lines


 
Added in v.547
-Removed from v.525
+Added in v.547

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12