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

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

Parent Directory | Revision Log | View Patch Patch

-revision 72 by nigel,
Sat Feb 24 21:40:24 2007 UTC
+revision 73 by nigel,
Sat Feb 24 21:40:30 2007 UTC
 Line 98 
 conversion went wrong.
  <b>void (*pcre_free)(void *);</b>
  </P>
  <P>
+ <b>void *(*pcre_stack_malloc)(size_t);</b>
+ </P>
+ <P>
+ <b>void (*pcre_stack_free)(void *);</b>
+ </P>
+ <P>
  <b>int (*pcre_callout)(pcre_callout_block *);</b>
  </P>
  <br><a name="SEC2" href="#TOC1">PCRE API</a><br>
-Line 156 
 so a calling program can replace them if
+Line 162 
 so a calling program can replace them if
  should be done before calling any PCRE functions.
  </P>
  <P>
+ The global variables <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> are also
+ indirections to memory management functions. These special functions are used
+ only when PCRE is compiled to use the heap for remembering data, instead of
+ recursive function calls. This is a non-standard way of building PCRE, for use
+ in environments that have limited stacks. Because of the greater use of memory
+ management, it runs more slowly. Separate functions are provided so that
+ special-purpose external code can be used for this case. When used, these
+ functions are always called in a stack-like manner (last obtained, first
+ freed), and always for memory blocks of the same size.
+ </P>
+ <P>
  The global variable <b>pcre_callout</b> initially contains NULL. It can be set
  by the caller to a "callout" function, which PCRE will then call at specified
  points during a matching operation. Details are given in the <b>pcrecallout</b>
-Line 164 
 documentation.
+Line 181 
 documentation.
  <br><a name="SEC3" href="#TOC1">MULTITHREADING</a><br>
  <P>
  The PCRE functions can be used in multi-threading applications, with the
- proviso that the memory management functions pointed to by <b>pcre_malloc</b>
+ proviso that the memory management functions pointed to by <b>pcre_malloc</b>,
- and <b>pcre_free</b>, and the callout function pointed to by <b>pcre_callout</b>,
+ <b>pcre_free</b>, <b>pcre_stack_malloc</b>, and <b>pcre_stack_free</b>, and the
- are shared by all threads.
+ callout function pointed to by <b>pcre_callout</b>, are shared by all threads.
  </P>
  <P>
  The compiled form of a regular expression is not altered during matching, so
-Line 238 
 The output is an integer that gives the
+Line 255 
 The output is an integer that gives the
  internal matching function calls in a <b>pcre_exec()</b> execution. Further
  details are given with <b>pcre_exec()</b> below.
  </P>
+ <P>
+ <pre>
+   PCRE_CONFIG_STACKRECURSE
+ </PRE>
+ </P>
+ <P>
+ The output is an integer that is set to one if internal recursion is
+ implemented by recursive function calls that use the stack to remember their
+ state. This is the usual way that PCRE is compiled. The output is zero if PCRE
+ was compiled to use blocks of data on the heap instead of recursive function
+ calls. In this case, <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> are
+ called to manage memory blocks on the heap, thus avoiding the use of the stack.
+ </P>
  <br><a name="SEC5" href="#TOC1">COMPILING A PATTERN</a><br>
  <P>
  <b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b>
-Line 878 
 unachored at matching time.
+Line 908 
 unachored at matching time.
  </P>
  <P>
  When PCRE_UTF8 was set at compile time, the validity of the subject as a UTF-8
- string is automatically checked. If an invalid UTF-8 sequence of bytes is
+ string is automatically checked, and the value of <i>startoffset</i> is also
- found, <b>pcre_exec()</b> returns the error PCRE_ERROR_BADUTF8. If you already
+ checked to ensure that it points to the start of a UTF-8 character. If an
- know that your subject is valid, and you want to skip this check for
+ invalid UTF-8 sequence of bytes is found, <b>pcre_exec()</b> returns the error
- performance reasons, you can set the PCRE_NO_UTF8_CHECK option when calling
+ PCRE_ERROR_BADUTF8. If <i>startoffset</i> contains an invalid value,
- <b>pcre_exec()</b>. When this option is set, the effect of passing an invalid
+ PCRE_ERROR_BADUTF8_OFFSET is returned.
- UTF-8 string as a subject is undefined. It may cause your program to crash.
+ </P>
+ <P>
+ If you already know that your subject is valid, and you want to skip these
+ checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when
+ calling <b>pcre_exec()</b>. You might want to do this for the second and
+ subsequent calls to <b>pcre_exec()</b> if you are making repeated calls to find
+ all the matches in a single subject string. However, you should be sure that
+ the value of <i>startoffset</i> points to the start of a UTF-8 character. When
+ PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid UTF-8 string as a
+ 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.
  </P>
  <P>
  There are also three further options that can be set only at matching time:
-Line 939 
 below) and trying an ordinary match agai
+Line 979 
 below) and trying an ordinary match agai
  </P>
  <P>
  The subject string is passed to <b>pcre_exec()</b> as a pointer in
- <i>subject</i>, a length in <i>length</i>, and a starting offset in
+ <i>subject</i>, a length in <i>length</i>, and a starting byte offset in
  <i>startoffset</i>. Unlike the pattern string, the subject may contain binary
  zero bytes. When the starting offset is zero, the search for a match starts at
  the beginning of the subject, and this is by far the most common case.
  </P>
  <P>
  If the pattern was compiled with the PCRE_UTF8 option, the subject must be a
- sequence of bytes that is a valid UTF-8 string. If an invalid UTF-8 string is
+ sequence of bytes that is a valid UTF-8 string, and the starting offset must
- passed, PCRE's behaviour is not defined.
+ point to the beginning of a UTF-8 character. If an invalid UTF-8 string or
+ offset is passed, an error (either PCRE_ERROR_BADUTF8 or
+ PCRE_ERROR_BADUTF8_OFFSET) is returned, unless the option PCRE_NO_UTF8_CHECK is
+ set, in which case PCRE's behaviour is not defined.
  </P>
  <P>
  A non-zero starting offset is useful when searching for another match in the
-Line 1132 
 use by callout functions that want to yi
+Line 1175 
 use by callout functions that want to yi
  </P>
  <P>
  <pre>
-   PCRE_ERROR_BADUTF8       (-10)
+   PCRE_ERROR_BADUTF8        (-10)
  </PRE>
  </P>
  <P>
  A string that contains an invalid UTF-8 byte sequence was passed as a subject.
  </P>
+ <P>
+ <pre>
+   PCRE_ERROR_BADUTF8_OFFSET (-11)
+ </PRE>
+ </P>
+ <P>
+ The UTF-8 byte sequence that was passed as a subject was valid, but the value
+ of <i>startoffset</i> did not point to the beginning of a UTF-8 character.
+ </P>
  <br><a name="SEC11" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br>
  <P>
  <b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b>
-Line 1289 
 then call pcre_copy_substring() o
+Line 1341 
 then call pcre_copy_substring() o
  appropriate.
  </P>
  <P>
- Last updated: 20 August 2003
+ Last updated: 09 December 2003
  <br>
  Copyright &copy; 1997-2003 University of Cambridge.

 Legend:



Removed from v.72
 


changed lines


 
Added in v.73
 Legend:



Removed from v.72
 


changed lines


 
Added in v.73
-Removed from v.72
+Added in v.73

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12