140 |
.\" HREF |
.\" HREF |
141 |
\fBpcresample\fP |
\fBpcresample\fP |
142 |
.\" |
.\" |
143 |
documentation describes how to run it. |
documentation describes how to compile and run it. |
144 |
.P |
.P |
145 |
A second matching function, \fBpcre_dfa_exec()\fP, which is not |
A second matching function, \fBpcre_dfa_exec()\fP, which is not |
146 |
Perl-compatible, is also provided. This uses a different algorithm for the |
Perl-compatible, is also provided. This uses a different algorithm for the |
218 |
documentation. |
documentation. |
219 |
. |
. |
220 |
. |
. |
221 |
|
.\" HTML <a name="newlines"></a> |
222 |
.SH NEWLINES |
.SH NEWLINES |
223 |
.rs |
.rs |
224 |
.sp |
.sp |
236 |
default can be overridden, either when a pattern is compiled, or when it is |
default can be overridden, either when a pattern is compiled, or when it is |
237 |
matched. |
matched. |
238 |
.P |
.P |
239 |
|
At compile time, the newline convention can be specified by the \fIoptions\fP |
240 |
|
argument of \fBpcre_compile()\fP, or it can be specified by special text at the |
241 |
|
start of the pattern itself; this overrides any other settings. See the |
242 |
|
.\" HREF |
243 |
|
\fBpcrepattern\fP |
244 |
|
.\" |
245 |
|
page for details of the special character sequences. |
246 |
|
.P |
247 |
In the PCRE documentation the word "newline" is used to mean "the character or |
In the PCRE documentation the word "newline" is used to mean "the character or |
248 |
pair of characters that indicate a line break". The choice of newline |
pair of characters that indicate a line break". The choice of newline |
249 |
convention affects the handling of the dot, circumflex, and dollar |
convention affects the handling of the dot, circumflex, and dollar |
250 |
metacharacters, the handling of #-comments in /x mode, and, when CRLF is a |
metacharacters, the handling of #-comments in /x mode, and, when CRLF is a |
251 |
recognized line ending sequence, the match position advancement for a |
recognized line ending sequence, the match position advancement for a |
252 |
non-anchored pattern. The choice of newline convention does not affect the |
non-anchored pattern. There is more detail about this in the |
253 |
interpretation of the \en or \er escape sequences. |
.\" HTML <a href="#execoptions"> |
254 |
|
.\" </a> |
255 |
|
section on \fBpcre_exec()\fP options |
256 |
|
.\" |
257 |
|
below. |
258 |
|
.P |
259 |
|
The choice of newline convention does not affect the interpretation of |
260 |
|
the \en or \er escape sequences, nor does it affect what \eR matches, which is |
261 |
|
controlled in a similar way, but by separate options. |
262 |
. |
. |
263 |
. |
. |
264 |
.SH MULTITHREADING |
.SH MULTITHREADING |
320 |
are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. The |
are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. The |
321 |
default should normally be the standard sequence for your operating system. |
default should normally be the standard sequence for your operating system. |
322 |
.sp |
.sp |
323 |
|
PCRE_CONFIG_BSR |
324 |
|
.sp |
325 |
|
The output is an integer whose value indicates what character sequences the \eR |
326 |
|
escape sequence matches by default. A value of 0 means that \eR matches any |
327 |
|
Unicode line ending sequence; a value of 1 means that \eR matches only CR, LF, |
328 |
|
or CRLF. The default can be overridden when a pattern is compiled or matched. |
329 |
|
.sp |
330 |
PCRE_CONFIG_LINK_SIZE |
PCRE_CONFIG_LINK_SIZE |
331 |
.sp |
.sp |
332 |
The output is an integer that contains the number of bytes used for internal |
The output is an integer that contains the number of bytes used for internal |
347 |
.sp |
.sp |
348 |
PCRE_CONFIG_MATCH_LIMIT |
PCRE_CONFIG_MATCH_LIMIT |
349 |
.sp |
.sp |
350 |
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 |
351 |
internal matching function calls in a \fBpcre_exec()\fP execution. Further |
internal matching function calls in a \fBpcre_exec()\fP execution. Further |
352 |
details are given with \fBpcre_exec()\fP below. |
details are given with \fBpcre_exec()\fP below. |
353 |
.sp |
.sp |
354 |
PCRE_CONFIG_MATCH_LIMIT_RECURSION |
PCRE_CONFIG_MATCH_LIMIT_RECURSION |
355 |
.sp |
.sp |
356 |
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 |
357 |
recursion when calling the internal matching function in a \fBpcre_exec()\fP |
recursion when calling the internal matching function in a \fBpcre_exec()\fP |
358 |
execution. Further details are given with \fBpcre_exec()\fP below. |
execution. Further details are given with \fBpcre_exec()\fP below. |
359 |
.sp |
.sp |
468 |
.\" |
.\" |
469 |
documentation. |
documentation. |
470 |
.sp |
.sp |
471 |
|
PCRE_BSR_ANYCRLF |
472 |
|
PCRE_BSR_UNICODE |
473 |
|
.sp |
474 |
|
These options (which are mutually exclusive) control what the \eR escape |
475 |
|
sequence matches. The choice is either to match only CR, LF, or CRLF, or to |
476 |
|
match any Unicode newline sequence. The default is specified when PCRE is |
477 |
|
built. It can be overridden from within the pattern, or by setting an option |
478 |
|
when a compiled pattern is matched. |
479 |
|
.sp |
480 |
PCRE_CASELESS |
PCRE_CASELESS |
481 |
.sp |
.sp |
482 |
If this bit is set, letters in the pattern match both upper and lower case |
If this bit is set, letters in the pattern match both upper and lower case |
549 |
the first newline in the subject string, though the matched text may continue |
the first newline in the subject string, though the matched text may continue |
550 |
over the newline. |
over the newline. |
551 |
.sp |
.sp |
552 |
|
PCRE_JAVASCRIPT_COMPAT |
553 |
|
.sp |
554 |
|
If this option is set, PCRE's behaviour is changed in some ways so that it is |
555 |
|
compatible with JavaScript rather than Perl. The changes are as follows: |
556 |
|
.P |
557 |
|
(1) A lone closing square bracket in a pattern causes a compile-time error, |
558 |
|
because this is illegal in JavaScript (by default it is treated as a data |
559 |
|
character). Thus, the pattern AB]CD becomes illegal when this option is set. |
560 |
|
.P |
561 |
|
(2) At run time, a back reference to an unset subpattern group matches an empty |
562 |
|
string (by default this causes the current matching alternative to fail). A |
563 |
|
pattern such as (\e1)(a) succeeds when this option is set (assuming it can find |
564 |
|
an "a" in the subject), whereas it fails by default, for Perl compatibility. |
565 |
|
.sp |
566 |
PCRE_MULTILINE |
PCRE_MULTILINE |
567 |
.sp |
.sp |
568 |
By default, PCRE treats the subject string as consisting of a single line of |
By default, PCRE treats the subject string as consisting of a single line of |
648 |
PCRE_NO_UTF8_CHECK |
PCRE_NO_UTF8_CHECK |
649 |
.sp |
.sp |
650 |
When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is |
When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is |
651 |
automatically checked. If an invalid UTF-8 sequence of bytes is found, |
automatically checked. There is a discussion about the |
652 |
\fBpcre_compile()\fP returns an error. If you already know that your pattern is |
.\" HTML <a href="pcre.html#utf8strings"> |
653 |
valid, and you want to skip this check for performance reasons, you can set the |
.\" </a> |
654 |
PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid |
validity of UTF-8 strings |
655 |
UTF-8 string as a pattern is undefined. It may cause your program to crash. |
.\" |
656 |
Note that this option can also be passed to \fBpcre_exec()\fP and |
in the main |
657 |
\fBpcre_dfa_exec()\fP, to suppress the UTF-8 validity checking of subject |
.\" HREF |
658 |
strings. |
\fBpcre\fP |
659 |
|
.\" |
660 |
|
page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_compile()\fP |
661 |
|
returns an error. If you already know that your pattern is valid, and you want |
662 |
|
to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK |
663 |
|
option. When it is set, the effect of passing an invalid UTF-8 string as a |
664 |
|
pattern is undefined. It may cause your program to crash. Note that this option |
665 |
|
can also be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress |
666 |
|
the UTF-8 validity checking of subject strings. |
667 |
. |
. |
668 |
. |
. |
669 |
.SH "COMPILATION ERROR CODES" |
.SH "COMPILATION ERROR CODES" |
686 |
9 nothing to repeat |
9 nothing to repeat |
687 |
10 [this code is not in use] |
10 [this code is not in use] |
688 |
11 internal error: unexpected repeat |
11 internal error: unexpected repeat |
689 |
12 unrecognized character after (? |
12 unrecognized character after (? or (?- |
690 |
13 POSIX named classes are supported only within a class |
13 POSIX named classes are supported only within a class |
691 |
14 missing ) |
14 missing ) |
692 |
15 reference to non-existent subpattern |
15 reference to non-existent subpattern |
694 |
17 unknown option bit(s) set |
17 unknown option bit(s) set |
695 |
18 missing ) after comment |
18 missing ) after comment |
696 |
19 [this code is not in use] |
19 [this code is not in use] |
697 |
20 regular expression too large |
20 regular expression is too large |
698 |
21 failed to get memory |
21 failed to get memory |
699 |
22 unmatched parentheses |
22 unmatched parentheses |
700 |
23 internal error: code overflow |
23 internal error: code overflow |
723 |
46 malformed \eP or \ep sequence |
46 malformed \eP or \ep sequence |
724 |
47 unknown property name after \eP or \ep |
47 unknown property name after \eP or \ep |
725 |
48 subpattern name is too long (maximum 32 characters) |
48 subpattern name is too long (maximum 32 characters) |
726 |
49 too many named subpatterns (maximum 10,000) |
49 too many named subpatterns (maximum 10000) |
727 |
50 [this code is not in use] |
50 [this code is not in use] |
728 |
51 octal value is greater than \e377 (not in UTF-8 mode) |
51 octal value is greater than \e377 (not in UTF-8 mode) |
729 |
52 internal error: overran compiling workspace |
52 internal error: overran compiling workspace |
730 |
53 internal error: previously-checked referenced subpattern not found |
53 internal error: previously-checked referenced subpattern not found |
731 |
54 DEFINE group contains more than one branch |
54 DEFINE group contains more than one branch |
732 |
55 repeating a DEFINE group is not allowed |
55 repeating a DEFINE group is not allowed |
733 |
56 inconsistent NEWLINE options" |
56 inconsistent NEWLINE options |
734 |
57 \eg is not followed by a braced name or an optionally braced |
57 \eg is not followed by a braced, angle-bracketed, or quoted |
735 |
non-zero number |
name/number or by a plain number |
736 |
58 (?+ or (?- or (?(+ or (?(- must be followed by a non-zero number |
58 a numbered reference must not be zero |
737 |
|
59 (*VERB) with an argument is not supported |
738 |
|
60 (*VERB) not recognized |
739 |
|
61 number is too big |
740 |
|
62 subpattern name expected |
741 |
|
63 digit expected after (?+ |
742 |
|
64 ] is an invalid data character in JavaScript compatibility mode |
743 |
|
.sp |
744 |
|
The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may |
745 |
|
be used if the limits were changed when PCRE was built. |
746 |
. |
. |
747 |
. |
. |
748 |
.SH "STUDYING A PATTERN" |
.SH "STUDYING A PATTERN" |
938 |
string, a pointer to the table is returned. Otherwise NULL is returned. The |
string, a pointer to the table is returned. Otherwise NULL is returned. The |
939 |
fourth argument should point to an \fBunsigned char *\fP variable. |
fourth argument should point to an \fBunsigned char *\fP variable. |
940 |
.sp |
.sp |
941 |
|
PCRE_INFO_HASCRORLF |
942 |
|
.sp |
943 |
|
Return 1 if the pattern contains any explicit matches for CR or LF characters, |
944 |
|
otherwise 0. The fourth argument should point to an \fBint\fP variable. An |
945 |
|
explicit match is either a literal CR or LF character, or \er or \en. |
946 |
|
.sp |
947 |
PCRE_INFO_JCHANGED |
PCRE_INFO_JCHANGED |
948 |
.sp |
.sp |
949 |
Return 1 if the (?J) option setting is used in the pattern, otherwise 0. The |
Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise |
950 |
fourth argument should point to an \fBint\fP variable. The (?J) internal option |
0. The fourth argument should point to an \fBint\fP variable. (?J) and |
951 |
setting changes the local PCRE_DUPNAMES option. |
(?-J) set and unset the local PCRE_DUPNAMES option, respectively. |
952 |
.sp |
.sp |
953 |
PCRE_INFO_LASTLITERAL |
PCRE_INFO_LASTLITERAL |
954 |
.sp |
.sp |
1231 |
.\" |
.\" |
1232 |
documentation for a discussion of saving compiled patterns for later use. |
documentation for a discussion of saving compiled patterns for later use. |
1233 |
. |
. |
1234 |
|
.\" HTML <a name="execoptions"></a> |
1235 |
.SS "Option bits for \fBpcre_exec()\fP" |
.SS "Option bits for \fBpcre_exec()\fP" |
1236 |
.rs |
.rs |
1237 |
.sp |
.sp |
1238 |
The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP must be |
The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP must be |
1239 |
zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP, |
zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP, |
1240 |
PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. |
PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_START_OPTIMIZE, |
1241 |
|
PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. |
1242 |
.sp |
.sp |
1243 |
PCRE_ANCHORED |
PCRE_ANCHORED |
1244 |
.sp |
.sp |
1247 |
to be anchored by virtue of its contents, it cannot be made unachored at |
to be anchored by virtue of its contents, it cannot be made unachored at |
1248 |
matching time. |
matching time. |
1249 |
.sp |
.sp |
1250 |
|
PCRE_BSR_ANYCRLF |
1251 |
|
PCRE_BSR_UNICODE |
1252 |
|
.sp |
1253 |
|
These options (which are mutually exclusive) control what the \eR escape |
1254 |
|
sequence matches. The choice is either to match only CR, LF, or CRLF, or to |
1255 |
|
match any Unicode newline sequence. These options override the choice that was |
1256 |
|
made or defaulted when the pattern was compiled. |
1257 |
|
.sp |
1258 |
PCRE_NEWLINE_CR |
PCRE_NEWLINE_CR |
1259 |
PCRE_NEWLINE_LF |
PCRE_NEWLINE_LF |
1260 |
PCRE_NEWLINE_CRLF |
PCRE_NEWLINE_CRLF |
1266 |
\fBpcre_compile()\fP above. During matching, the newline choice affects the |
\fBpcre_compile()\fP above. During matching, the newline choice affects the |
1267 |
behaviour of the dot, circumflex, and dollar metacharacters. It may also alter |
behaviour of the dot, circumflex, and dollar metacharacters. It may also alter |
1268 |
the way the match position is advanced after a match failure for an unanchored |
the way the match position is advanced after a match failure for an unanchored |
1269 |
pattern. When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is |
pattern. |
1270 |
set, and a match attempt fails when the current position is at a CRLF sequence, |
.P |
1271 |
the match position is advanced by two characters instead of one, in other |
When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a |
1272 |
words, to after the CRLF. |
match attempt for an unanchored pattern fails when the current position is at a |
1273 |
|
CRLF sequence, and the pattern contains no explicit matches for CR or LF |
1274 |
|
characters, the match position is advanced by two characters instead of one, in |
1275 |
|
other words, to after the CRLF. |
1276 |
|
.P |
1277 |
|
The above rule is a compromise that makes the most common cases work as |
1278 |
|
expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not |
1279 |
|
set), it does not match the string "\er\enA" because, after failing at the |
1280 |
|
start, it skips both the CR and the LF before retrying. However, the pattern |
1281 |
|
[\er\en]A does match that string, because it contains an explicit CR or LF |
1282 |
|
reference, and so advances only by one character after the first failure. |
1283 |
|
.P |
1284 |
|
An explicit match for CR of LF is either a literal appearance of one of those |
1285 |
|
characters, or one of the \er or \en escape sequences. Implicit matches such as |
1286 |
|
[^X] do not count, nor does \es (which includes CR and LF in the characters |
1287 |
|
that it matches). |
1288 |
|
.P |
1289 |
|
Notwithstanding the above, anomalous effects may still occur when CRLF is a |
1290 |
|
valid newline sequence and explicit \er or \en escapes appear in the pattern. |
1291 |
.sp |
.sp |
1292 |
PCRE_NOTBOL |
PCRE_NOTBOL |
1293 |
.sp |
.sp |
1325 |
starting offset (see below) and trying an ordinary match again. There is some |
starting offset (see below) and trying an ordinary match again. There is some |
1326 |
code that demonstrates how to do this in the \fIpcredemo.c\fP sample program. |
code that demonstrates how to do this in the \fIpcredemo.c\fP sample program. |
1327 |
.sp |
.sp |
1328 |
|
PCRE_NO_START_OPTIMIZE |
1329 |
|
.sp |
1330 |
|
There are a number of optimizations that \fBpcre_exec()\fP uses at the start of |
1331 |
|
a match, in order to speed up the process. For example, if it is known that a |
1332 |
|
match must start with a specific character, it searches the subject for that |
1333 |
|
character, and fails immediately if it cannot find it, without actually running |
1334 |
|
the main matching function. When callouts are in use, these optimizations can |
1335 |
|
cause them to be skipped. This option disables the "start-up" optimizations, |
1336 |
|
causing performance to suffer, but ensuring that the callouts do occur. |
1337 |
|
.sp |
1338 |
PCRE_NO_UTF8_CHECK |
PCRE_NO_UTF8_CHECK |
1339 |
.sp |
.sp |
1340 |
When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 |
When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 |
1341 |
string is automatically checked when \fBpcre_exec()\fP is subsequently called. |
string is automatically checked when \fBpcre_exec()\fP is subsequently called. |
1342 |
The value of \fIstartoffset\fP is also checked to ensure that it points to the |
The value of \fIstartoffset\fP is also checked to ensure that it points to the |
1343 |
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 |
1344 |
\fBpcre_exec()\fP returns the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP |
strings in the |
1345 |
contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned. |
.\" HTML <a href="pcre.html#utf8strings"> |
1346 |
|
.\" </a> |
1347 |
|
section on UTF-8 support |
1348 |
|
.\" |
1349 |
|
in the main |
1350 |
|
.\" HREF |
1351 |
|
\fBpcre\fP |
1352 |
|
.\" |
1353 |
|
page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fP returns |
1354 |
|
the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP contains an invalid value, |
1355 |
|
PCRE_ERROR_BADUTF8_OFFSET is returned. |
1356 |
.P |
.P |
1357 |
If you already know that your subject is valid, and you want to skip these |
If you already know that your subject is valid, and you want to skip these |
1358 |
checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when |
checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when |
1382 |
.rs |
.rs |
1383 |
.sp |
.sp |
1384 |
The subject string is passed to \fBpcre_exec()\fP as a pointer in |
The subject string is passed to \fBpcre_exec()\fP as a pointer in |
1385 |
\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 |
1386 |
\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 |
1387 |
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 |
1388 |
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 |
1389 |
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. |
1390 |
.P |
.P |
1391 |
A non-zero starting offset is useful when searching for another match in the |
A non-zero starting offset is useful when searching for another match in the |
1392 |
same subject by calling \fBpcre_exec()\fP again after a previous success. |
same subject by calling \fBpcre_exec()\fP again after a previous success. |
1420 |
a fragment of a pattern that picks out a substring. PCRE supports several other |
a fragment of a pattern that picks out a substring. PCRE supports several other |
1421 |
kinds of parenthesized subpattern that do not cause substrings to be captured. |
kinds of parenthesized subpattern that do not cause substrings to be captured. |
1422 |
.P |
.P |
1423 |
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 |
1424 |
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 |
1425 |
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 |
1426 |
this argument is NOT the size of \fIovector\fP in bytes. |
argument is NOT the size of \fIovector\fP in bytes. |
1427 |
.P |
.P |
1428 |
The first two-thirds of the vector is used to pass back captured substrings, |
The first two-thirds of the vector is used to pass back captured substrings, |
1429 |
each substring using a pair of integers. The remaining third of the vector is |
each substring using a pair of integers. The remaining third of the vector is |
1430 |
used as workspace by \fBpcre_exec()\fP while matching capturing subpatterns, |
used as workspace by \fBpcre_exec()\fP while matching capturing subpatterns, |
1431 |
and is not available for passing back information. The length passed in |
and is not available for passing back information. The number passed in |
1432 |
\fIovecsize\fP should always be a multiple of three. If it is not, it is |
\fIovecsize\fP should always be a multiple of three. If it is not, it is |
1433 |
rounded down. |
rounded down. |
1434 |
.P |
.P |
1435 |
When a match is successful, information about captured substrings is returned |
When a match is successful, information about captured substrings is returned |
1436 |
in pairs of integers, starting at the beginning of \fIovector\fP, and |
in pairs of integers, starting at the beginning of \fIovector\fP, and |
1437 |
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 |
1438 |
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 |
1439 |
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 |
1440 |
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 |
1441 |
subject string matched by the entire pattern. The next pair is used for the |
mode. They are not character counts. |
1442 |
first capturing subpattern, and so on. The value returned by \fBpcre_exec()\fP |
.P |
1443 |
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 |
1444 |
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 |
1445 |
capturing subpatterns, the return value from a successful match is 1, |
used for the first capturing subpattern, and so on. The value returned by |
1446 |
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. |
1447 |
|
For example, if two substrings have been captured, the returned value is 3. If |
1448 |
|
there are no capturing subpatterns, the return value from a successful match is |
1449 |
|
1, indicating that just the first pair of offsets has been set. |
1450 |
.P |
.P |
1451 |
If a capturing subpattern is matched repeatedly, it is the last portion of the |
If a capturing subpattern is matched repeatedly, it is the last portion of the |
1452 |
string that it matched that is returned. |
string that it matched that is returned. |
1453 |
.P |
.P |
1454 |
If the vector is too small to hold all the captured substring offsets, it is |
If the vector is too small to hold all the captured substring offsets, it is |
1455 |
used as far as possible (up to two-thirds of its length), and the function |
used as far as possible (up to two-thirds of its length), and the function |
1456 |
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, |
1457 |
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 |
1458 |
\fIovecsize\fP as zero. However, if the pattern contains back references and |
\fIovecsize\fP as zero. However, if the pattern contains back references and |
1459 |
the \fIovector\fP is not big enough to remember the related substrings, PCRE |
the \fIovector\fP is not big enough to remember the related substrings, PCRE |
1460 |
has to get additional memory for use during matching. Thus it is usually |
has to get additional memory for use during matching. Thus it is usually |
1740 |
then call \fBpcre_copy_substring()\fP or \fBpcre_get_substring()\fP, as |
then call \fBpcre_copy_substring()\fP or \fBpcre_get_substring()\fP, as |
1741 |
appropriate. \fBNOTE:\fP If PCRE_DUPNAMES is set and there are duplicate names, |
appropriate. \fBNOTE:\fP If PCRE_DUPNAMES is set and there are duplicate names, |
1742 |
the behaviour may not be what you want (see the next section). |
the behaviour may not be what you want (see the next section). |
1743 |
. |
.P |
1744 |
|
\fBWarning:\fP If the pattern uses the "(?|" feature to set up multiple |
1745 |
|
subpatterns with the same number, you cannot use names to distinguish them, |
1746 |
|
because names are not included in the compiled code. The matching process uses |
1747 |
|
only numbers. |
1748 |
. |
. |
1749 |
.SH "DUPLICATE SUBPATTERN NAMES" |
.SH "DUPLICATE SUBPATTERN NAMES" |
1750 |
.rs |
.rs |
1760 |
.\" HREF |
.\" HREF |
1761 |
\fBpcrepattern\fP |
\fBpcrepattern\fP |
1762 |
.\" |
.\" |
1763 |
documentation. |
documentation. |
1764 |
.P |
.P |
1765 |
When duplicates are present, \fBpcre_copy_named_substring()\fP and |
When duplicates are present, \fBpcre_copy_named_substring()\fP and |
1766 |
\fBpcre_get_named_substring()\fP return the first substring corresponding to |
\fBpcre_get_named_substring()\fP return the first substring corresponding to |
1993 |
.rs |
.rs |
1994 |
.sp |
.sp |
1995 |
.nf |
.nf |
1996 |
Last updated: 30 July 2007 |
Last updated: 15 March 2009 |
1997 |
Copyright (c) 1997-2007 University of Cambridge. |
Copyright (c) 1997-2009 University of Cambridge. |
1998 |
.fi |
.fi |