Revision: 1301
http://vcs.pcre.org/viewvc?view=rev&revision=1301
Author: ph10
Date: 2013-03-26 16:36:40 +0000 (Tue, 26 Mar 2013)
Log Message:
-----------
Improve and correct PCRE_NO_START_OPTIMIZE documentation.
Modified Paths:
--------------
code/trunk/doc/pcreapi.3
Modified: code/trunk/doc/pcreapi.3
===================================================================
--- code/trunk/doc/pcreapi.3 2013-03-25 12:34:26 UTC (rev 1300)
+++ code/trunk/doc/pcreapi.3 2013-03-26 16:36:40 UTC (rev 1301)
@@ -1,4 +1,4 @@
-.TH PCREAPI 3 "27 February 2013" "PCRE 8.33"
+.TH PCREAPI 3 "26 March 2013" "PCRE 8.33"
.SH NAME
PCRE - Perl-compatible regular expressions
.sp
@@ -810,12 +810,14 @@
they acquire numbers in the usual way). There is no equivalent of this option
in Perl.
.sp
- NO_START_OPTIMIZE
+ PCRE_NO_START_OPTIMIZE
.sp
This is an option that acts at matching time; that is, it is really an option
for \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. If it is set at compile time,
-it is remembered with the compiled pattern and assumed at matching time. For
-details see the discussion of PCRE_NO_START_OPTIMIZE
+it is remembered with the compiled pattern and assumed at matching time. This
+is necessary if you want to use JIT execution, because the JIT compiler needs
+to know whether or not this option is set. For details see the discussion of
+PCRE_NO_START_OPTIMIZE
.\" HTML <a href="#execoptions">
.\" </a>
below.
@@ -1081,11 +1083,17 @@
.P
These two optimizations apply to both \fBpcre_exec()\fP and
\fBpcre_dfa_exec()\fP, and the information is also used by the JIT compiler.
-The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option
-when calling \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP, but if this is done,
-JIT execution is also disabled. You might want to do this if your pattern
-contains callouts or (*MARK) and you want to make use of these facilities in
-cases where matching fails. See the discussion of PCRE_NO_START_OPTIMIZE
+The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option.
+You might want to do this if your pattern contains callouts or (*MARK) and you
+want to make use of these facilities in cases where matching fails.
+.P
+PCRE_NO_START_OPTIMIZE can be specified at either compile time or execution
+time. However, if PCRE_NO_START_OPTIMIZE is passed to \fBpcre_exec()\fP, (that
+is, after any JIT compilation has happened) JIT execution is disabled. For JIT
+execution to work with PCRE_NO_START_OPTIMIZE, the option must be set at
+compile time.
+.P
+There is a longer discussion of PCRE_NO_START_OPTIMIZE
.\" HTML <a href="#execoptions">
.\" </a>
below.
@@ -1829,18 +1837,19 @@
for that character, and fails immediately if it cannot find it, without
actually running the main matching function. This means that a special item
such as (*COMMIT) at the start of a pattern is not considered until after a
-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.
+suitable starting point for the match has been found. Also, 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. If
PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching
-time. The use of PCRE_NO_START_OPTIMIZE disables JIT execution; when it is set,
-matching is always done using interpretively.
+time. The use of PCRE_NO_START_OPTIMIZE at matching time (that is, passing it
+to \fBpcre_exec()\fP) disables JIT execution; in this situation, matching is
+always done using interpretively.
.P
Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation.
Consider the pattern
@@ -2825,6 +2834,6 @@
.rs
.sp
.nf
-Last updated: 27 February 2013
+Last updated: 26 March 2013
Copyright (c) 1997-2013 University of Cambridge.
.fi
