trunk/doc/pcre_get_named_substring.3

.TH PCRE_GET_NAMED_SUBSTRING 3 "24 June 2012" "PCRE 8.30"
.SH NAME
PCRE - Perl-compatible regular expressions
.SH SYNOPSIS
.rs
.sp
.B #include <pcre.h>
.PP
.nf
.B int pcre_get_named_substring(const pcre *\fIcode\fP,
.B "     const char *\fIsubject\fP, int *\fIovector\fP,"
.B "     int \fIstringcount\fP, const char *\fIstringname\fP,"
.B "     const char **\fIstringptr\fP);"
.sp
.B int pcre16_get_named_substring(const pcre16 *\fIcode\fP,
.B "     PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP,"
.B "     int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP,"
.B "     PCRE_SPTR16 *\fIstringptr\fP);"
.sp
.B int pcre32_get_named_substring(const pcre32 *\fIcode\fP,
.B "     PCRE_SPTR32 \fIsubject\fP, int *\fIovector\fP,"
.B "     int \fIstringcount\fP, PCRE_SPTR32 \fIstringname\fP,"
.B "     PCRE_SPTR32 *\fIstringptr\fP);"
.fi
.
.SH DESCRIPTION
.rs
.sp
This is a convenience function for extracting a captured substring by name. The
arguments are:
.sp
  \fIcode\fP          Compiled pattern
  \fIsubject\fP       Subject that has been successfully matched
  \fIovector\fP       Offset vector that \fBpcre[16|32]_exec()\fP used
  \fIstringcount\fP   Value returned by \fBpcre[16|32]_exec()\fP
  \fIstringname\fP    Name of the required substring
  \fIstringptr\fP     Where to put the string pointer
.sp
The memory in which the substring is placed is obtained by calling
\fBpcre[16|32]_malloc()\fP. The convenience function
\fBpcre[16|32]_free_substring()\fP can be used to free it when it is no longer
needed. The yield of the function is the length of the extracted substring,
PCRE_ERROR_NOMEMORY if sufficient memory could not be obtained, or
PCRE_ERROR_NOSUBSTRING if the string name is invalid.
.P
There is a complete description of the PCRE native API in the
.\" HREF
\fBpcreapi\fP
.\"
page and a description of the POSIX API in the
.\" HREF
\fBpcreposix\fP
.\"
page.
1	chpe	1055	.TH PCRE_GET_NAMED_SUBSTRING 3 "24 June 2012" "PCRE 8.30"
2	nigel	63	.SH NAME
3			PCRE - Perl-compatible regular expressions
4			.SH SYNOPSIS
5			.rs
6			.sp
7			.B #include <pcre.h>
8			.PP
9	ph10	1339	.nf
10	nigel	75	.B int pcre_get_named_substring(const pcre *\fIcode\fP,
11	ph10	1339	.B " const char \fIsubject\fP, int \fIovector\fP,"
12			.B " int \fIstringcount\fP, const char *\fIstringname\fP,"
13			.B " const char **\fIstringptr\fP);"
14			.sp
15	ph10	868	.B int pcre16_get_named_substring(const pcre16 *\fIcode\fP,
16	ph10	1339	.B " PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP,"
17			.B " int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP,"
18			.B " PCRE_SPTR16 *\fIstringptr\fP);"
19			.sp
20	chpe	1055	.B int pcre32_get_named_substring(const pcre32 *\fIcode\fP,
21	ph10	1339	.B " PCRE_SPTR32 \fIsubject\fP, int *\fIovector\fP,"
22			.B " int \fIstringcount\fP, PCRE_SPTR32 \fIstringname\fP,"
23			.B " PCRE_SPTR32 *\fIstringptr\fP);"
24			.fi
25	nigel	75	.
26	nigel	63	.SH DESCRIPTION
27			.rs
28			.sp
29			This is a convenience function for extracting a captured substring by name. The
30			arguments are:
31	nigel	75	.sp
32			\fIcode\fP Compiled pattern
33			\fIsubject\fP Subject that has been successfully matched
34	chpe	1055	\fIovector\fP Offset vector that \fBpcre[16\|32]_exec()\fP used
35			\fIstringcount\fP Value returned by \fBpcre[16\|32]_exec()\fP
36	nigel	75	\fIstringname\fP Name of the required substring
37			\fIstringptr\fP Where to put the string pointer
38			.sp
39			The memory in which the substring is placed is obtained by calling
40	chpe	1055	\fBpcre[16\|32]_malloc()\fP. The convenience function
41			\fBpcre[16\|32]_free_substring()\fP can be used to free it when it is no longer
42	ph10	868	needed. The yield of the function is the length of the extracted substring,
43			PCRE_ERROR_NOMEMORY if sufficient memory could not be obtained, or
44			PCRE_ERROR_NOSUBSTRING if the string name is invalid.
45	nigel	75	.P
46			There is a complete description of the PCRE native API in the
47	nigel	63	.\" HREF
48	nigel	75	\fBpcreapi\fP
49	nigel	63	.\"
50	nigel	75	page and a description of the POSIX API in the
51			.\" HREF
52			\fBpcreposix\fP
53			.\"
54	nigel	63	page.
Name	Value
svn:eol-style	native
svn:keywords	"Author Date Id Revision Url"