int pcre_get_stringnumber(const pcre *code,
const char *name);
int pcre_copy_named_substring(const pcre *code,
const char *subject, int *ovector,
int stringcount, const char *stringname,
char *buffer, int buffersize);
int pcre_get_named_substring(const pcre *code,
const char *subject, int *ovector,
int stringcount, const char *stringname,
const char **stringptr);
To extract a substring by name, you first have to find associated
number. For example, for this pattern
(a+)b(?<xxx>\d+)...
the number of the subpattern called "xxx" is 2. If the name is
known to be unique (PCRE_DUPNAMES was not set), you can find the
number from the name by calling pcre_get_stringnumber(). The
first argument is the compiled pattern, and the second is the
name. The yield of the function is the subpattern number, or
PCRE_ERROR_NOSUBSTRING (-7) if there is no subpattern of that
name.
Given the number, you can extract the substring directly, or use
one of the functions described in the previous section. For
convenience, there are also two functions that do the whole job.
Most of the arguments of pcre_copy_named_substring() and
pcre_get_named_substring() are the same as those for the
similarly named functions that extract by number. As these are
described in the previous section, they are not re-described
here. There are just two differences:
First, instead of a substring number, a substring name is given.
Second, there is an extra argument, given at the start, which is
a pointer to the compiled pattern. This is needed in order to
gain access to the name-to-number translation table.
These functions call pcre_get_stringnumber(), and if it succeeds,
they then call pcre_copy_substring() or pcre_get_substring(), as
appropriate. NOTE: If PCRE_DUPNAMES is set and there are
duplicate names, the behaviour may not be what you want (see the
next section).
Warning: If the pattern uses the (?| feature to set up multiple
subpatterns with the same number, as described in the section on
duplicate subpattern numbers in the pcrepattern page, you cannot
use names to distinguish the different subpatterns, because names
are not included in the compiled code. The matching process uses
only numbers. For this reason, the use of different names for
subpatterns of the same number causes an error at compile time.
