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 num- ber. For example, for this pattern


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 com- piled 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. Sec- ond, 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 appropri- ate. 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 subpat- terns 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.