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

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

Parent Directory | Revision Log | View Patch Patch

-revision 142 by ph10,
Fri Mar 30 15:55:18 2007 UTC
+revision 426 by ph10,
Wed Aug 26 15:38:32 2009 UTC
 Line 140 
 distribution. The
  .\" HREF
  \fBpcresample\fP
  .\"
- documentation describes how to run it.
+ documentation describes how to compile and run it.
  .P
  A second matching function, \fBpcre_dfa_exec()\fP, which is not
  Perl-compatible, is also provided. This uses a different algorithm for the
 Line 218 
 points during a matching operation. Deta
  documentation.
  .
  .
+ .\" HTML <a name="newlines"></a>
  .SH NEWLINES
  .rs
  .sp
- PCRE supports four different conventions for indicating line breaks in
+ PCRE supports five different conventions for indicating line breaks in
  strings: a single CR (carriage return) character, a single LF (linefeed)
- character, the two-character sequence CRLF, or any Unicode newline sequence.
+ character, the two-character sequence CRLF, any of the three preceding, or any
- The Unicode newline sequences are the three just mentioned, plus the single
+ Unicode newline sequence. The Unicode newline sequences are the three just
- characters VT (vertical tab, U+000B), FF (formfeed, U+000C), NEL (next line,
+ mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed,
- U+0085), LS (line separator, U+2028), and PS (paragraph separator, U+2029).
+ U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
+ (paragraph separator, U+2029).
  .P
  Each of the first three conventions is used by at least one operating system as
  its standard newline sequence. When PCRE is built, a default can be specified.
-Line 234 
 The default default is LF, which is the
+Line 236 
 The default default is LF, which is the
  default can be overridden, either when a pattern is compiled, or when it is
  matched.
  .P
+ At compile time, the newline convention can be specified by the \fIoptions\fP
+ argument of \fBpcre_compile()\fP, or it can be specified by special text at the
+ start of the pattern itself; this overrides any other settings. See the
+ .\" HREF
+ \fBpcrepattern\fP
+ .\"
+ page for details of the special character sequences.
+ .P
  In the PCRE documentation the word "newline" is used to mean "the character or
  pair of characters that indicate a line break". The choice of newline
  convention affects the handling of the dot, circumflex, and dollar
  metacharacters, the handling of #-comments in /x mode, and, when CRLF is a
  recognized line ending sequence, the match position advancement for a
- non-anchored pattern. The choice of newline convention does not affect the
+ non-anchored pattern. There is more detail about this in the
- interpretation of the \en or \er escape sequences.
+ .\" HTML <a href="#execoptions">
+ .\" </a>
+ section on \fBpcre_exec()\fP options
+ .\"
+ below.
+ .P
+ The choice of newline convention does not affect the interpretation of
+ the \en or \er escape sequences, nor does it affect what \eR matches, which is
+ controlled in a similar way, but by separate options.
  .
  .
  .SH MULTITHREADING
-Line 264 
 which it was compiled. Details are given
+Line 282 
 which it was compiled. Details are given
  .\" HREF
  \fBpcreprecompile\fP
  .\"
- documentation.
+ documentation. However, compiling a regular expression with one version of PCRE
+ for use with a different version is not guaranteed to work and may cause
+ crashes.
  .
  .
  .SH "CHECKING BUILD-TIME OPTIONS"
-Line 297 
 properties is available; otherwise it is
+Line 317 
 properties is available; otherwise it is
  .sp
  The output is an integer whose value specifies the default character sequence
  that is recognized as meaning "newline". The four values that are supported
- are: 10 for LF, 13 for CR, 3338 for CRLF, and -1 for ANY. The default should
+ are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY.
- normally be the standard sequence for your operating system.
+ Though they are derived from ASCII, the same values are returned in EBCDIC
+ environments. The default should normally correspond to the standard sequence
+ for your operating system.
+ .sp
+   PCRE_CONFIG_BSR
+ .sp
+ The output is an integer whose value indicates what character sequences the \eR
+ escape sequence matches by default. A value of 0 means that \eR matches any
+ Unicode line ending sequence; a value of 1 means that \eR matches only CR, LF,
+ or CRLF. The default can be overridden when a pattern is compiled or matched.
  .sp
    PCRE_CONFIG_LINK_SIZE
  .sp
-Line 320 
 documentation.
+Line 349 
 documentation.
  .sp
    PCRE_CONFIG_MATCH_LIMIT
  .sp
- The output is an integer that gives the default limit for the number of
+ The output is a long integer that gives the default limit for the number of
  internal matching function calls in a \fBpcre_exec()\fP execution. Further
  details are given with \fBpcre_exec()\fP below.
  .sp
    PCRE_CONFIG_MATCH_LIMIT_RECURSION
  .sp
- The output is an integer that gives the default limit for the depth of
+ The output is a long integer that gives the default limit for the depth of
  recursion when calling the internal matching function in a \fBpcre_exec()\fP
  execution. Further details are given with \fBpcre_exec()\fP below.
  .sp
-Line 377 
 argument, which is an address (see below
+Line 406 
 argument, which is an address (see below
  .P
  The \fIoptions\fP 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
+ options are described below. Some of them (in particular, those that are
- compatible with Perl, can also be set and unset from within the pattern (see
+ compatible with Perl, but also some others) can also be set and unset from
- the detailed description in the
+ within the pattern (see the detailed description in the
  .\" HREF
  \fBpcrepattern\fP
  .\"
- documentation). For these options, the contents of the \fIoptions\fP argument
+ documentation). For those options that can be different in different parts of
- specifies their initial settings at the start of compilation and execution. The
+ the pattern, the contents of the \fIoptions\fP argument specifies their initial
- PCRE_ANCHORED and PCRE_NEWLINE_\fIxxx\fP options can be set at the time of
+ settings at the start of compilation and execution. The PCRE_ANCHORED and
- matching as well as at compile time.
+ PCRE_NEWLINE_\fIxxx\fP options can be set at the time of matching as well as at
+ compile time.
  .P
  If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately.
  Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns
-Line 441 
 facility, see the
+Line 471 
 facility, see the
  .\"
  documentation.
  .sp
+   PCRE_BSR_ANYCRLF
+   PCRE_BSR_UNICODE
+ .sp
+ These options (which are mutually exclusive) control what the \eR escape
+ sequence matches. The choice is either to match only CR, LF, or CRLF, or to
+ match any Unicode newline sequence. The default is specified when PCRE is
+ built. It can be overridden from within the pattern, or by setting an option
+ when a compiled pattern is matched.
+ .sp
    PCRE_CASELESS
  .sp
  If this bit is set, letters in the pattern match both upper and lower case
-Line 513 
 If this option is set, an unanchored pat
+Line 552 
 If this option is set, an unanchored pat
  the first newline in the subject string, though the matched text may continue
  over the newline.
  .sp
+   PCRE_JAVASCRIPT_COMPAT
+ .sp
+ If this option is set, PCRE's behaviour is changed in some ways so that it is
+ compatible with JavaScript rather than Perl. The changes are as follows:
+ .P
+ (1) A lone closing square bracket in a pattern causes a compile-time error,
+ because this is illegal in JavaScript (by default it is treated as a data
+ character). Thus, the pattern AB]CD becomes illegal when this option is set.
+ .P
+ (2) At run time, a back reference to an unset subpattern group matches an empty
+ string (by default this causes the current matching alternative to fail). A
+ pattern such as (\e1)(a) succeeds when this option is set (assuming it can find
+ an "a" in the subject), whereas it fails by default, for Perl compatibility.
+ .sp
    PCRE_MULTILINE
  .sp
  By default, PCRE treats the subject string as consisting of a single line of
-Line 532 
 occurrences of ^ or $ in a pattern, sett
+Line 585 
 occurrences of ^ or $ in a pattern, sett
    PCRE_NEWLINE_CR
    PCRE_NEWLINE_LF
    PCRE_NEWLINE_CRLF
+   PCRE_NEWLINE_ANYCRLF
    PCRE_NEWLINE_ANY
  .sp
  These options override the default newline definition that was chosen when PCRE
  was built. Setting the first or the second specifies that a newline is
  indicated by a single character (CR or LF, respectively). Setting
  PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character
- CRLF sequence. Setting PCRE_NEWLINE_ANY specifies that any Unicode newline
+ CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three
- sequence should be recognized. The Unicode newline sequences are the three just
+ preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies
- mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed,
+ that any Unicode newline sequence should be recognized. The Unicode newline
- U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
+ sequences are the three just mentioned, plus the single characters VT (vertical
- (paragraph separator, U+2029). The last two are recognized only in UTF-8 mode.
+ tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line
+ separator, U+2028), and PS (paragraph separator, U+2029). The last two are
+ recognized only in UTF-8 mode.
  .P
  The newline setting in the options word uses three bits that are treated
- as a number, giving eight possibilities. Currently only five are used (default
+ as a number, giving eight possibilities. Currently only six are used (default
- plus the four values above). This means that if you set more than one newline
+ plus the five values above). This means that if you set more than one newline
  option, the combination may or may not be sensible. For example,
  PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but
- other combinations yield unused numbers and cause an error.
+ other combinations may yield unused numbers and cause an error.
  .P
  The only time that a line break is specially recognized when compiling a
  pattern is if PCRE_EXTENDED is set, and an unescaped # outside a character
-Line 595 
 page.
+Line 651 
 page.
    PCRE_NO_UTF8_CHECK
  .sp
  When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
- automatically checked. If an invalid UTF-8 sequence of bytes is found,
+ automatically checked. There is a discussion about the
- \fBpcre_compile()\fP returns an error. If you already know that your pattern is
+ .\" HTML <a href="pcre.html#utf8strings">
- valid, and you want to skip this check for performance reasons, you can set the
+ .\" </a>
- PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid
+ validity of UTF-8 strings
- UTF-8 string as a pattern is undefined. It may cause your program to crash.
+ .\"
- Note that this option can also be passed to \fBpcre_exec()\fP and
+ in the main
- \fBpcre_dfa_exec()\fP, to suppress the UTF-8 validity checking of subject
+ .\" HREF
- strings.
+ \fBpcre\fP
+ .\"
+ page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_compile()\fP
+ returns an error. If you already know that your pattern is valid, and you want
+ to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK
+ option. When it is set, the effect of passing an invalid UTF-8 string as a
+ pattern is undefined. It may cause your program to crash. Note that this option
+ can also be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress
+ the UTF-8 validity checking of subject strings.
  .
  .
  .SH "COMPILATION ERROR CODES"
-Line 625 
 out of use. To avoid confusion, they hav
+Line 689 
 out of use. To avoid confusion, they hav
  nothing to repeat
  [this code is not in use]
  internal error: unexpected repeat
- unrecognized character after (?
+ unrecognized character after (? or (?-
  POSIX named classes are supported only within a class
  missing )
  reference to non-existent subpattern
-Line 633 
 out of use. To avoid confusion, they hav
+Line 697 
 out of use. To avoid confusion, they hav
  unknown option bit(s) set
  missing ) after comment
  [this code is not in use]
- regular expression too large
+ regular expression is too large
  failed to get memory
  unmatched parentheses
  internal error: code overflow
-Line 642 
 out of use. To avoid confusion, they hav
+Line 706 
 out of use. To avoid confusion, they hav
  malformed number or name after (?(
  conditional group contains more than two branches
  assertion expected after (?(
- (?R or (?digits must be followed by )
+ (?R or (?[+-]digits must be followed by )
  unknown POSIX class name
  POSIX collating elements are not supported
  this version of PCRE is not compiled with PCRE_UTF8 support
-Line 662 
 out of use. To avoid confusion, they hav
+Line 726 
 out of use. To avoid confusion, they hav
  malformed \eP or \ep sequence
  unknown property name after \eP or \ep
  subpattern name is too long (maximum 32 characters)
- too many named subpatterns (maximum 10,000)
+ too many named subpatterns (maximum 10000)
- repeated subpattern is too long
+ [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
  DEFINE group contains more than one branch
  repeating a DEFINE group is not allowed
- inconsistent NEWLINE options"
+ inconsistent NEWLINE options
+ \eg is not followed by a braced, angle-bracketed, or quoted
+         name/number or by a plain number
+ a numbered reference must not be zero
+ (*VERB) with an argument is not supported
+ (*VERB) not recognized
+ number is too big
+ subpattern name expected
+ digit expected after (?+
+ ] is an invalid data character in JavaScript compatibility mode
+ .sp
+ The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may
+ be used if the limits were changed when PCRE was built.
  .
  .
  .SH "STUDYING A PATTERN"
-Line 865 
 table indicating a fixed set of bytes fo
+Line 941 
 table indicating a fixed set of bytes fo
  string, a pointer to the table is returned. Otherwise NULL is returned. The
  fourth argument should point to an \fBunsigned char *\fP variable.
  .sp
+   PCRE_INFO_HASCRORLF
+ .sp
+ Return 1 if the pattern contains any explicit matches for CR or LF characters,
+ otherwise 0. The fourth argument should point to an \fBint\fP variable. An
+ explicit match is either a literal CR or LF character, or \er or \en.
+ .sp
+   PCRE_INFO_JCHANGED
+ .sp
+ Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise
+. The fourth argument should point to an \fBint\fP variable. (?J) and
+ (?-J) set and unset the local PCRE_DUPNAMES option, respectively.
+ .sp
    PCRE_INFO_LASTLITERAL
  .sp
  Return the value of the rightmost literal byte that must exist in any matched
-Line 917 
 When writing code to extract data from n
+Line 1005 
 When writing code to extract data from n
  name-to-number map, remember that the length of the entries is likely to be
  different for each compiled pattern.
  .sp
+   PCRE_INFO_OKPARTIAL
+ .sp
+ Return 1 if the pattern can be used for partial matching, otherwise 0. The
+ fourth argument should point to an \fBint\fP variable. From release 8.00, this
+ always returns 1, because the restrictions that previously applied to partial
+ matching have been lifted. The
+ .\" HREF
+ \fBpcrepartial\fP
+ .\"
+ documentation gives details of partial matching.
+ .sp
    PCRE_INFO_OPTIONS
  .sp
  Return a copy of the options with which the pattern was compiled. The fourth
  argument should point to an \fBunsigned long int\fP variable. These option bits
  are those specified in the call to \fBpcre_compile()\fP, modified by any
- top-level option settings within the pattern itself.
+ top-level option settings at the start of the pattern itself. In other words,
+ they are the options that will be in force when matching starts. For example,
+ if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the
+ result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED.
  .P
  A pattern is automatically anchored by PCRE if all of its top-level
  alternatives begin with one of the following:
-Line 1133 
 called. See the
+Line 1235 
 called. See the
  .\"
  documentation for a discussion of saving compiled patterns for later use.
  .
+ .\" HTML <a name="execoptions"></a>
  .SS "Option bits for \fBpcre_exec()\fP"
  .rs
  .sp
  The unused bits of the \fIoptions\fP argument for \fBpcre_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_NO_UTF8_CHECK and PCRE_PARTIAL.
+ PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_START_OPTIMIZE,
+ PCRE_NO_UTF8_CHECK and PCRE_PARTIAL.
  .sp
    PCRE_ANCHORED
  .sp
-Line 1147 
 matching position. If a pattern was comp
+Line 1251 
 matching position. If a pattern was comp
  to be anchored by virtue of its contents, it cannot be made unachored at
  matching time.
  .sp
+   PCRE_BSR_ANYCRLF
+   PCRE_BSR_UNICODE
+ .sp
+ These options (which are mutually exclusive) control what the \eR escape
+ sequence matches. The choice is either to match only CR, LF, or CRLF, or to
+ match any Unicode newline sequence. These options override the choice that was
+ made or defaulted when the pattern was compiled.
+ .sp
    PCRE_NEWLINE_CR
    PCRE_NEWLINE_LF
    PCRE_NEWLINE_CRLF
+   PCRE_NEWLINE_ANYCRLF
    PCRE_NEWLINE_ANY
  .sp
  These options override the newline definition that was chosen or defaulted when
-Line 1157 
 the pattern was compiled. For details, s
+Line 1270 
 the pattern was compiled. For details, s
  \fBpcre_compile()\fP above. During matching, the newline choice affects the
  behaviour of the dot, circumflex, and dollar metacharacters. It may also alter
  the way the match position is advanced after a match failure for an unanchored
- pattern. When PCRE_NEWLINE_CRLF or PCRE_NEWLINE_ANY is set, and a match attempt
+ pattern.
- fails when the current position is at a CRLF sequence, the match position is
+ .P
- advanced by two characters instead of one, in other words, to after the CRLF.
+ When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a
+ match attempt for an unanchored pattern fails when the current position is at a
+ CRLF sequence, and the pattern contains no explicit matches for CR or LF
+ characters, the match position is advanced by two characters instead of one, in
+ other words, to after the CRLF.
+ .P
+ The above rule is a compromise that makes the most common cases work as
+ expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not
+ set), it does not match the string "\er\enA" because, after failing at the
+ start, it skips both the CR and the LF before retrying. However, the pattern
+ [\er\en]A does match that string, because it contains an explicit CR or LF
+ reference, and so advances only by one character after the first failure.
+ .P
+ An explicit match for CR of LF is either a literal appearance of one of those
+ characters, or one of the \er or \en escape sequences. Implicit matches such as
+ [^X] do not count, nor does \es (which includes CR and LF in the characters
+ that it matches).
+ .P
+ Notwithstanding the above, anomalous effects may still occur when CRLF is a
+ valid newline sequence and explicit \er or \en escapes appear in the pattern.
  .sp
    PCRE_NOTBOL
  .sp
-Line 1197 
 PCRE_NOTEMPTY and PCRE_ANCHORED, and the
+Line 1329 
 PCRE_NOTEMPTY and PCRE_ANCHORED, and the
  starting offset (see below) and trying an ordinary match again. There is some
  code that demonstrates how to do this in the \fIpcredemo.c\fP sample program.
  .sp
+   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
+ match must start with a specific character, it searches the subject for that
+ character, and fails immediately if it cannot find it, without actually running
+ the main matching function. When callouts are in use, these optimizations can
+ cause them to be skipped. This option disables the "start-up" optimizations,
+ causing performance to suffer, but ensuring that the callouts do occur.
+ .sp
    PCRE_NO_UTF8_CHECK
  .sp
  When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8
  string is automatically checked when \fBpcre_exec()\fP is subsequently called.
  The value of \fIstartoffset\fP is also checked to ensure that it points to the
- start of a UTF-8 character. If an invalid UTF-8 sequence of bytes is found,
+ start of a UTF-8 character. There is a discussion about the validity of UTF-8
- \fBpcre_exec()\fP returns the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP
+ strings in the
- contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
+ .\" HTML <a href="pcre.html#utf8strings">
+ .\" </a>
+ section on UTF-8 support
+ .\"
+ in the main
+ .\" HREF
+ \fBpcre\fP
+ .\"
+ page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fP returns
+ the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP contains an invalid value,
+ PCRE_ERROR_BADUTF8_OFFSET is returned.
  .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
-Line 1223 
 to match the pattern, but at some point
+Line 1375 
 to match the pattern, but at some point
  the subject was reached (that is, the subject partially matches the pattern and
  the failure to match occurred only because there were not enough subject
  characters), \fBpcre_exec()\fP returns PCRE_ERROR_PARTIAL instead of
- PCRE_ERROR_NOMATCH. When PCRE_PARTIAL is used, there are restrictions on what
+ PCRE_ERROR_NOMATCH. The portion of the string that provided the longest partial
- may appear in the pattern. These are discussed in the
+ match is set as the first matching string. There is further discussion in the
  .\" HREF
  \fBpcrepartial\fP
  .\"
-Line 1234 
 documentation.
+Line 1386 
 documentation.
  .rs
  .sp
  The subject string is passed to \fBpcre_exec()\fP as a pointer in
- \fIsubject\fP, a length in \fIlength\fP, and a starting byte offset in
+ \fIsubject\fP, a length (in bytes) in \fIlength\fP, and a starting byte offset
- \fIstartoffset\fP. In UTF-8 mode, the byte offset must point to the start of a
+ in \fIstartoffset\fP. In UTF-8 mode, the byte offset must point to the start of
- UTF-8 character. Unlike the pattern string, the subject may contain binary zero
+ a UTF-8 character. Unlike the pattern string, the subject may contain binary
- bytes. When the starting offset is zero, the search for a match starts at the
+ zero bytes. When the starting offset is zero, the search for a match starts at
- beginning of the subject, and this is by far the most common case.
+ the beginning of the subject, and this is by far the most common case.
  .P
  A non-zero starting offset is useful when searching for another match in the
  same subject by calling \fBpcre_exec()\fP again after a previous success.
-Line 1272 
 pattern. Following the usage in Jeffrey
+Line 1424 
 pattern. Following the usage in Jeffrey
  a fragment of a pattern that picks out a substring. PCRE supports several other
  kinds of parenthesized subpattern that do not cause substrings to be captured.
  .P
- Captured substrings are returned to the caller via a vector of integer offsets
+ Captured substrings are returned to the caller via a vector of integers whose
- whose address is passed in \fIovector\fP. The number of elements in the vector
+ address is passed in \fIovector\fP. The number of elements in the vector is
- is passed in \fIovecsize\fP, which must be a non-negative number. \fBNote\fP:
+ passed in \fIovecsize\fP, which must be a non-negative number. \fBNote\fP: this
- this argument is NOT the size of \fIovector\fP in bytes.
+ argument is NOT the size of \fIovector\fP in bytes.
  .P
  The first two-thirds of the vector is used to pass back captured substrings,
  each substring using a pair of integers. The remaining third of the vector is
  used as workspace by \fBpcre_exec()\fP while matching capturing subpatterns,
- and is not available for passing back information. The length passed in
+ and is not available for passing back information. The number passed in
  \fIovecsize\fP should always be a multiple of three. If it is not, it is
  rounded down.
  .P
  When a match is successful, information about captured substrings is returned
  in pairs of integers, starting at the beginning of \fIovector\fP, and
- continuing up to two-thirds of its length at the most. The first element of a
+ continuing up to two-thirds of its length at the most. The first element of
- pair is set to the offset of the first character in a substring, and the second
+ each pair is set to the byte offset of the first character in a substring, and
- is set to the offset of the first character after the end of a substring. The
+ the second is set to the byte offset of the first character after the end of a
- first pair, \fIovector[0]\fP and \fIovector[1]\fP, identify the portion of the
+ substring. \fBNote\fP: these values are always byte offsets, even in UTF-8
- subject string matched by the entire pattern. The next pair is used for the
+ mode. They are not character counts.
- first capturing subpattern, and so on. The value returned by \fBpcre_exec()\fP
+ .P
- is one more than the highest numbered pair that has been set. For example, if
+ The first pair of integers, \fIovector[0]\fP and \fIovector[1]\fP, identify the
- two substrings have been captured, the returned value is 3. If there are no
+ portion of the subject string matched by the entire pattern. The next pair is
- capturing subpatterns, the return value from a successful match is 1,
+ used for the first capturing subpattern, and so on. The value returned by
- indicating that just the first pair of offsets has been set.
+ \fBpcre_exec()\fP is one more than the highest numbered pair that has been set.
+ For example, if two substrings have been captured, the returned value is 3. If
+ there are no capturing subpatterns, the return value from a successful match is
+, indicating that just the first pair of offsets has been set.
  .P
  If a capturing subpattern is matched repeatedly, it is the last portion of the
  string that it matched that is returned.
  .P
  If the vector is too small to hold all the captured substring offsets, it is
  used as far as possible (up to two-thirds of its length), and the function
- returns a value of zero. In particular, if the substring offsets are not of
+ returns a value of zero. If the substring offsets are not of interest,
- interest, \fBpcre_exec()\fP may be called with \fIovector\fP passed as NULL and
+ \fBpcre_exec()\fP may be called with \fIovector\fP passed as NULL and
  \fIovecsize\fP as zero. However, if the pattern contains back references and
  the \fIovector\fP is not big enough to remember the related substrings, PCRE
  has to get additional memory for use during matching. Thus it is usually
-Line 1414 
 documentation for details of partial mat
+Line 1569 
 documentation for details of partial mat
  .sp
    PCRE_ERROR_BADPARTIAL     (-13)
  .sp
- The PCRE_PARTIAL option was used with a compiled pattern containing items that
+ This code is no longer in use. It was formerly returned when the PCRE_PARTIAL
- are not supported for partial matching. See the
+ option was used with a compiled pattern containing items that were not
- .\" HREF
+ supported for partial matching. From release 8.00 onwards, there are no
- \fBpcrepartial\fP
+ restrictions on partial matching.
- .\"
- documentation for details of partial matching.
  .sp
    PCRE_ERROR_INTERNAL       (-14)
  .sp
-Line 1436 
 The internal recursion limit, as specifi
+Line 1589 
 The internal recursion limit, as specifi
  field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the
  description above.
  .sp
-   PCRE_ERROR_NULLWSLIMIT    (-22)
- .sp
- When a group that can match an empty substring is repeated with an unbounded
- upper limit, the subject position at the start of the group must be remembered,
- so that a test for an empty string can be made when the end of the group is
- reached. Some workspace is required for this; if it runs out, this error is
- given.
- .sp
    PCRE_ERROR_BADNEWLINE     (-23)
  .sp
  An invalid combination of PCRE_NEWLINE_\fIxxx\fP options was given.
  .P
- Error numbers -16 to -20 are not used by \fBpcre_exec()\fP.
+ Error numbers -16 to -20 and -22 are not used by \fBpcre_exec()\fP.
  .
  .
  .SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
-Line 1597 
 These functions call \fBpcre_get_stringn
+Line 1742 
 These functions call \fBpcre_get_stringn
  then call \fBpcre_copy_substring()\fP or \fBpcre_get_substring()\fP, as
  appropriate. \fBNOTE:\fP If PCRE_DUPNAMES is set and there are duplicate names,
  the behaviour may not be what you want (see the next section).
- .
+ .P
+ \fBWarning:\fP If the pattern uses the "(?|" feature to set up multiple
+ subpatterns with the same number, you cannot use names to distinguish them,
+ because names are not included in the compiled code. The matching process uses
+ only numbers.
  .
  .SH "DUPLICATE SUBPATTERN NAMES"
  .rs
-Line 1613 
 example is shown in the
+Line 1762 
 example is shown in the
  .\" HREF
  \fBpcrepattern\fP
  .\"
- documentation. When duplicates are present, \fBpcre_copy_named_substring()\fP
+ documentation.
- and \fBpcre_get_named_substring()\fP return the first substring corresponding
+ .P
- to the given name that is set. If none are set, an empty string is returned.
+ When duplicates are present, \fBpcre_copy_named_substring()\fP and
- The \fBpcre_get_stringnumber()\fP function returns one of the numbers that are
+ \fBpcre_get_named_substring()\fP return the first substring corresponding to
- associated with the name, but it is not defined which it is.
+ the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is
- .sp
+ returned; no data is returned. The \fBpcre_get_stringnumber()\fP function
+ returns one of the numbers that are associated with the name, but it is not
+ defined which it is.
+ .P
  If you want to get full details of all captured substrings for a given name,
  you must use the \fBpcre_get_stringtable_entries()\fP function. The first
  argument is the compiled pattern, and the second is the name. The third and
-Line 1712 
 The unused bits of the \fIoptions\fP arg
+Line 1864 
 The unused bits of the \fIoptions\fP arg
  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,
  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL,
  PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All but the last three of these are
- the same as for \fBpcre_exec()\fP, so their description is not repeated here.
+ exactly the same as for \fBpcre_exec()\fP, so their description is not repeated
+ here.
  .sp
    PCRE_PARTIAL
  .sp
-Line 1721 
 details are slightly different. When PCR
+Line 1874 
 details are slightly different. When PCR
  \fBpcre_dfa_exec()\fP, the return code PCRE_ERROR_NOMATCH is converted into
  PCRE_ERROR_PARTIAL if the end of the subject is reached, there have been no
  complete matches, but there is still at least one matching possibility. The
- portion of the string that provided the partial match is set as the first
+ portion of the string that provided the longest partial match is set as the
- matching string.
+ first matching string.
  .sp
    PCRE_DFA_SHORTEST
  .sp
-Line 1843 
 Cambridge CB2 3QH, England.
+Line 1996 
 Cambridge CB2 3QH, England.
  .rs
  .sp
  .nf
- Last updated: 06 March 2007
+ Last updated: 26 August 2009
- Copyright (c) 1997-2007 University of Cambridge.
+ Copyright (c) 1997-2009 University of Cambridge.
  .fi

 Legend:



Removed from v.142
 


changed lines


 
Added in v.426
 Legend:



Removed from v.142
 


changed lines


 
Added in v.426
-Removed from v.142
+Added in v.426

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12