/[pcre]/code/trunk/doc/html/pcrecallout.html
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1297 by ph10, Wed Oct 31 17:42:29 2012 UTC revision 1298 by ph10, Fri Mar 22 16:13:13 2013 UTC
# Line 64  it is processed as if it were Line 64  it is processed as if it were
64  <br>  <br>
65  <br>  <br>
66  Notice that there is a callout before and after each parenthesis and  Notice that there is a callout before and after each parenthesis and
67  alternation bar. Automatic callouts can be used for tracking the progress of  alternation bar. If the pattern contains a conditional group whose condition is
68  pattern matching. The  an assertion, an automatic callout is inserted immediately before the
69    condition. Such a callout may also be inserted explicitly, for example:
70    <pre>
71      (?(?C9)(?=a)ab|de)
72    </pre>
73    This applies only to assertion conditions (because they are themselves
74    independent groups).
75    </P>
76    <P>
77    Automatic callouts can be used for tracking the progress of pattern matching.
78    The
79  <a href="pcretest.html"><b>pcretest</b></a>  <a href="pcretest.html"><b>pcretest</b></a>
80  command has an option that sets automatic callouts; when it is used, the output  command has an option that sets automatic callouts; when it is used, the output
81  indicates how the pattern is matched. This is useful information when you are  indicates how the pattern is matched. This is useful information when you are
82  trying to optimize the performance of a particular pattern.  trying to optimize the performance of a particular pattern.
83  </P>  </P>
 <P>  
 The use of callouts in a pattern makes it ineligible for optimization by the  
 just-in-time compiler. Studying such a pattern with the PCRE_STUDY_JIT_COMPILE  
 option always fails.  
 </P>  
84  <br><a name="SEC3" href="#TOC1">MISSING CALLOUTS</a><br>  <br><a name="SEC3" href="#TOC1">MISSING CALLOUTS</a><br>
85  <P>  <P>
86  You should be aware that, because of optimizations in the way PCRE matches  You should be aware that, because of optimizations in the way PCRE matches
# Line 141  automatically generated callouts). Line 146  automatically generated callouts).
146  <P>  <P>
147  The <i>offset_vector</i> field is a pointer to the vector of offsets that was  The <i>offset_vector</i> field is a pointer to the vector of offsets that was
148  passed by the caller to the matching function. When <b>pcre_exec()</b> or  passed by the caller to the matching function. When <b>pcre_exec()</b> or
149  <b>pcre[16|32]_exec()</b> is used, the contents can be inspected, in order to extract  <b>pcre[16|32]_exec()</b> is used, the contents can be inspected, in order to
150  substrings that have been matched so far, in the same way as for extracting  extract substrings that have been matched so far, in the same way as for
151  substrings after a match has completed. For the DFA matching functions, this  extracting substrings after a match has completed. For the DFA matching
152  field is not useful.  functions, this field is not useful.
153  </P>  </P>
154  <P>  <P>
155  The <i>subject</i> and <i>subject_length</i> fields contain copies of the values  The <i>subject</i> and <i>subject_length</i> fields contain copies of the values
# Line 171  functions are used, because they do not Line 176  functions are used, because they do not
176  </P>  </P>
177  <P>  <P>
178  The <i>capture_last</i> field contains the number of the most recently captured  The <i>capture_last</i> field contains the number of the most recently captured
179  substring. If no substrings have been captured, its value is -1. This is always  substring. However, when a recursion exits, the value reverts to what it was
180  the case for the DFA matching functions.  outside the recursion, as do the values of all captured substrings. If no
181    substrings have been captured, the value of <i>capture_last</i> is -1. This is
182    always the case for the DFA matching functions.
183  </P>  </P>
184  <P>  <P>
185  The <i>callout_data</i> field contains a value that is passed to a matching  The <i>callout_data</i> field contains a value that is passed to a matching
# Line 203  same callout number. However, they are s Line 210  same callout number. However, they are s
210  </P>  </P>
211  <P>  <P>
212  The <i>mark</i> field is present from version 2 of the callout structure. In  The <i>mark</i> field is present from version 2 of the callout structure. In
213  callouts from <b>pcre_exec()</b> or <b>pcre[16|32]_exec()</b> it contains a pointer to  callouts from <b>pcre_exec()</b> or <b>pcre[16|32]_exec()</b> it contains a
214  the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or  pointer to the zero-terminated name of the most recently passed (*MARK),
215  (*THEN) item in the match, or NULL if no such items have been passed. Instances  (*PRUNE), or (*THEN) item in the match, or NULL if no such items have been
216  of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In  passed. Instances of (*PRUNE) or (*THEN) without a name do not obliterate a
217  callouts from the DFA matching functions this field always contains NULL.  previous (*MARK). In callouts from the DFA matching functions this field always
218    contains NULL.
219  </P>  </P>
220  <br><a name="SEC5" href="#TOC1">RETURN VALUES</a><br>  <br><a name="SEC5" href="#TOC1">RETURN VALUES</a><br>
221  <P>  <P>
# Line 234  Cambridge CB2 3QH, England. Line 242  Cambridge CB2 3QH, England.
242  </P>  </P>
243  <br><a name="SEC7" href="#TOC1">REVISION</a><br>  <br><a name="SEC7" href="#TOC1">REVISION</a><br>
244  <P>  <P>
245  Last updated: 24 June 2012  Last updated: 03 March 2013
246  <br>  <br>
247  Copyright &copy; 1997-2012 University of Cambridge.  Copyright &copy; 1997-2013 University of Cambridge.
248  <br>  <br>
249  <p>  <p>
250  Return to the <a href="index.html">PCRE index page</a>.  Return to the <a href="index.html">PCRE index page</a>.

Legend:
Removed from v.1297  
changed lines
  Added in v.1298

  ViewVC Help
Powered by ViewVC 1.1.5