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

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

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

revision 456 by ph10, Fri Oct 2 08:53:31 2009 UTC revision 457 by ph10, Sat Oct 3 16:24:08 2009 UTC
# Line 1012  entry; both of these return an \fBint\fP Line 1012  entry; both of these return an \fBint\fP
1012  length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first  length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first
1013  entry of the table (a pointer to \fBchar\fP). The first two bytes of each entry  entry of the table (a pointer to \fBchar\fP). The first two bytes of each entry
1014  are the number of the capturing parenthesis, most significant byte first. The  are the number of the capturing parenthesis, most significant byte first. The
1015  rest of the entry is the corresponding name, zero terminated. The names are in  rest of the entry is the corresponding name, zero terminated.
1016  alphabetical order. When PCRE_DUPNAMES is set, duplicate names are in order of  .P
1017  their parentheses numbers. For example, consider the following pattern (assume  The names are in alphabetical order. Duplicate names may appear if (?| is used
1018  PCRE_EXTENDED is set, so white space - including newlines - is ignored):  to create multiple groups with the same number, as described in the
1019    .\" HTML <a href="pcrepattern.html#dupsubpatternnumber">
1020    .\" </a>
1021    section on duplicate subpattern numbers
1022    .\"
1023    in the
1024    .\" HREF
1025    \fBpcrepattern\fP
1026    .\"
1027    page. Duplicate names for subpatterns with different numbers are permitted only
1028    if PCRE_DUPNAMES is set. In all cases of duplicate names, they appear in the
1029    table in the order in which they were found in the pattern. In the absence of
1030    (?| this is the order of increasing number; when (?| is used this is not
1031    necessarily the case because later subpatterns may have lower numbers.
1032    .P
1033    As a simple example of the name/number table, consider the following pattern
1034    (assume PCRE_EXTENDED is set, so white space - including newlines - is
1035    ignored):
1036  .sp  .sp
1037  .\" JOIN  .\" JOIN
1038    (?<date> (?<year>(\ed\ed)?\ed\ed) -    (?<date> (?<year>(\ed\ed)?\ed\ed) -
# Line 1789  then call \fBpcre_copy_substring()\fP or Line 1806  then call \fBpcre_copy_substring()\fP or
1806  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,
1807  the behaviour may not be what you want (see the next section).  the behaviour may not be what you want (see the next section).
1808  .P  .P
1809  \fBWarning:\fP If the pattern uses the "(?|" feature to set up multiple  \fBWarning:\fP If the pattern uses the (?| feature to set up multiple
1810  subpatterns with the same number, you cannot use names to distinguish them,  subpatterns with the same number, as described in the
1811  because names are not included in the compiled code. The matching process uses  .\" HTML <a href="pcrepattern.html#dupsubpatternnumber">
1812  only numbers.  .\" </a>
1813    section on duplicate subpattern numbers
1814    .\"
1815    in the
1816    .\" HREF
1817    \fBpcrepattern\fP
1818    .\"
1819    page, you cannot use names to distinguish the different subpatterns, because
1820    names are not included in the compiled code. The matching process uses only
1821    numbers. For this reason, the use of different names for subpatterns of the
1822    same number causes an error at compile time.
1823  .  .
1824  .SH "DUPLICATE SUBPATTERN NAMES"  .SH "DUPLICATE SUBPATTERN NAMES"
1825  .rs  .rs
# Line 1802  only numbers. Line 1829  only numbers.
1829  .B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);  .B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);
1830  .PP  .PP
1831  When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns  When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns
1832  are not required to be unique. Normally, patterns with duplicate names are such  are not required to be unique. (Duplicate names are always allowed for
1833  that in any one match, only one of the named subpatterns participates. An  subpatterns with the same number, created by using the (?| feature. Indeed, if
1834  example is shown in the  such subpatterns are named, they are required to use the same names.)
1835    .P
1836    Normally, patterns with duplicate names are such that in any one match, only
1837    one of the named subpatterns participates. An example is shown in the
1838  .\" HREF  .\" HREF
1839  \fBpcrepattern\fP  \fBpcrepattern\fP
1840  .\"  .\"
# Line 2045  Cambridge CB2 3QH, England. Line 2075  Cambridge CB2 3QH, England.
2075  .rs  .rs
2076  .sp  .sp
2077  .nf  .nf
2078  Last updated: 29 September 2009  Last updated: 03 October 2009
2079  Copyright (c) 1997-2009 University of Cambridge.  Copyright (c) 1997-2009 University of Cambridge.
2080  .fi  .fi
Legend:
Removed from v.456  
changed lines
  Added in v.457
webmaster@exim.org
 ViewVC Help
Powered by ViewVC 1.1.12