doc/html/pcrecpp.html

<html>
<head>
<title>pcrecpp specification</title>
</head>
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
<h1>pcrecpp man page</h1>
<p>
Return to the <a href="index.html">PCRE index page</a>.
</p>
<p>
This page is part of the PCRE HTML documentation. It was generated automatically
from the original man page. If there is any nonsense in it, please consult the
man page, in case the conversion went wrong.
<br>
<ul>
<li><a name="TOC1" href="#SEC1">SYNOPSIS OF C++ WRAPPER</a>
<li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
<li><a name="TOC3" href="#SEC3">MATCHING INTERFACE</a>
<li><a name="TOC4" href="#SEC4">PARTIAL MATCHES</a>
<li><a name="TOC5" href="#SEC5">UTF-8 AND THE MATCHING INTERFACE</a>
<li><a name="TOC6" href="#SEC6">SCANNING TEXT INCREMENTALLY</a>
<li><a name="TOC7" href="#SEC7">PARSING HEX/OCTAL/C-RADIX NUMBERS</a>
<li><a name="TOC8" href="#SEC8">REPLACING PARTS OF STRINGS</a>
<li><a name="TOC9" href="#SEC9">AUTHOR</a>
</ul>
<br><a name="SEC1" href="#TOC1">SYNOPSIS OF C++ WRAPPER</a><br>
<P>
<b>#include &#60;pcrecpp.h&#62;</b>
</P>
<P>
</P>
<br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
<P>
The C++ wrapper for PCRE was provided by Google Inc. This brief man page was
constructed from the notes in the <i>pcrecpp.h</i> file, which should be
consulted for further details.
</P>
<br><a name="SEC3" href="#TOC1">MATCHING INTERFACE</a><br>
<P>
The "FullMatch" operation checks that supplied text matches a supplied pattern
exactly. If pointer arguments are supplied, it copies matched sub-strings that
match sub-patterns into them.
<pre>
  Example: successful match
     pcrecpp::RE re("h.*o");
     re.FullMatch("hello");

  Example: unsuccessful match (requires full match):
     pcrecpp::RE re("e");
     !re.FullMatch("hello");

  Example: creating a temporary RE object:
     pcrecpp::RE("h.*o").FullMatch("hello");
</pre>
You can pass in a "const char*" or a "string" for "text". The examples below
tend to use a const char*. You can, as in the different examples above, store
the RE object explicitly in a variable or use a temporary RE object. The
examples below use one mode or the other arbitrarily. Either could correctly be
used for any of these examples.
</P>
<P>
You must supply extra pointer arguments to extract matched subpieces.
<pre>
  Example: extracts "ruby" into "s" and 1234 into "i"
     int i;
     string s;
     pcrecpp::RE re("(\\w+):(\\d+)");
     re.FullMatch("ruby:1234", &s, &i);

  Example: does not try to extract any extra sub-patterns
     re.FullMatch("ruby:1234", &s);

  Example: does not try to extract into NULL
     re.FullMatch("ruby:1234", NULL, &i);

  Example: integer overflow causes failure
     !re.FullMatch("ruby:1234567891234", NULL, &i);

  Example: fails because there aren't enough sub-patterns:
     !pcrecpp::RE("\\w+:\\d+").FullMatch("ruby:1234", &s);

  Example: fails because string cannot be stored in integer
     !pcrecpp::RE("(.*)").FullMatch("ruby", &i);
</pre>
The provided pointer arguments can be pointers to any scalar numeric
type, or one of:
<pre>
   string        (matched piece is copied to string)
   StringPiece   (StringPiece is mutated to point to matched piece)
   T             (where "bool T::ParseFrom(const char*, int)" exists)
   NULL          (the corresponding matched sub-pattern is not copied)
</pre>
The function returns true iff all of the following conditions are satisfied:
<pre>
  a. "text" matches "pattern" exactly;

  b. The number of matched sub-patterns is &#62;= number of supplied
     pointers;

  c. The "i"th argument has a suitable type for holding the
     string captured as the "i"th sub-pattern. If you pass in
     NULL for the "i"th argument, or pass fewer arguments than
     number of sub-patterns, "i"th captured sub-pattern is
     ignored.
</pre>
The matching interface supports at most 16 arguments per call.
If you need more, consider using the more general interface
<b>pcrecpp::RE::DoMatch</b>. See <b>pcrecpp.h</b> for the signature for
<b>DoMatch</b>.
</P>
<br><a name="SEC4" href="#TOC1">PARTIAL MATCHES</a><br>
<P>
You can use the "PartialMatch" operation when you want the pattern
to match any substring of the text.
<pre>
  Example: simple search for a string:
     pcrecpp::RE("ell").PartialMatch("hello");

  Example: find first number in a string:
     int number;
     pcrecpp::RE re("(\\d+)");
     re.PartialMatch("x*100 + 20", &number);
     assert(number == 100);
</PRE>
</P>
<br><a name="SEC5" href="#TOC1">UTF-8 AND THE MATCHING INTERFACE</a><br>
<P>
By default, pattern and text are plain text, one byte per character. The UTF8
flag, passed to the constructor, causes both pattern and string to be treated
as UTF-8 text, still a byte stream but potentially multiple bytes per
character. In practice, the text is likelier to be UTF-8 than the pattern, but
the match returned may depend on the UTF8 flag, so always use it when matching
UTF8 text. For example, "." will match one byte normally but with UTF8 set may
match up to three bytes of a multi-byte character.
<pre>
  Example:
     pcrecpp::RE_Options options;
     options.set_utf8();
     pcrecpp::RE re(utf8_pattern, options);
     re.FullMatch(utf8_string);

  Example: using the convenience function UTF8():
     pcrecpp::RE re(utf8_pattern, pcrecpp::UTF8());
     re.FullMatch(utf8_string);
</pre>
NOTE: The UTF8 flag is ignored if pcre was not configured with the
<pre>
      --enable-utf8 flag.
</PRE>
</P>
<br><a name="SEC6" href="#TOC1">SCANNING TEXT INCREMENTALLY</a><br>
<P>
The "Consume" operation may be useful if you want to repeatedly
match regular expressions at the front of a string and skip over
them as they match. This requires use of the "StringPiece" type,
which represents a sub-range of a real string. Like RE, StringPiece
is defined in the pcrecpp namespace.
<pre>
  Example: read lines of the form "var = value" from a string.
     string contents = ...;                 // Fill string somehow
     pcrecpp::StringPiece input(contents);  // Wrap in a StringPiece
</PRE>
</P>
<P>
<pre>
     string var;
     int value;
     pcrecpp::RE re("(\\w+) = (\\d+)\n");
     while (re.Consume(&input, &var, &value)) {
       ...;
     }
</pre>
Each successful call to "Consume" will set "var/value", and also
advance "input" so it points past the matched text.
</P>
<P>
The "FindAndConsume" operation is similar to "Consume" but does not
anchor your match at the beginning of the string. For example, you
could extract all words from a string by repeatedly calling
<pre>
  pcrecpp::RE("(\\w+)").FindAndConsume(&input, &word)
</PRE>
</P>
<br><a name="SEC7" href="#TOC1">PARSING HEX/OCTAL/C-RADIX NUMBERS</a><br>
<P>
By default, if you pass a pointer to a numeric value, the
corresponding text is interpreted as a base-10 number. You can
instead wrap the pointer with a call to one of the operators Hex(),
Octal(), or CRadix() to interpret the text in another base. The
CRadix operator interprets C-style "0" (base-8) and "0x" (base-16)
prefixes, but defaults to base-10.
<pre>
  Example:
    int a, b, c, d;
    pcrecpp::RE re("(.*) (.*) (.*) (.*)");
    re.FullMatch("100 40 0100 0x40",
                 pcrecpp::Octal(&a), pcrecpp::Hex(&b),
                 pcrecpp::CRadix(&c), pcrecpp::CRadix(&d));
</pre>
will leave 64 in a, b, c, and d.
</P>
<br><a name="SEC8" href="#TOC1">REPLACING PARTS OF STRINGS</a><br>
<P>
You can replace the first match of "pattern" in "str" with "rewrite".
Within "rewrite", backslash-escaped digits (\1 to \9) can be
used to insert text matching corresponding parenthesized group
from the pattern. \0 in "rewrite" refers to the entire matching
text. For example:
<pre>
  string s = "yabba dabba doo";
  pcrecpp::RE("b+").Replace("d", &s);
</pre>
will leave "s" containing "yada dabba doo". The result is true if the pattern
matches and a replacement occurs, false otherwise.
</P>
<P>
<b>GlobalReplace</b> is like <b>Replace</b> except that it replaces all
occurrences of the pattern in the string with the rewrite. Replacements are
not subject to re-matching. For example:
<pre>
  string s = "yabba dabba doo";
  pcrecpp::RE("b+").GlobalReplace("d", &s);
</pre>
will leave "s" containing "yada dada doo". It returns the number of
replacements made.
</P>
<P>
<b>Extract</b> is like <b>Replace</b>, except that if the pattern matches,
"rewrite" is copied into "out" (an additional argument) with substitutions.
The non-matching portions of "text" are ignored. Returns true iff a match
occurred and the extraction happened successfully;  if no match occurs, the
string is left unaffected.
</P>
<br><a name="SEC9" href="#TOC1">AUTHOR</a><br>
<P>
The C++ wrapper was contributed by Google Inc.
<br>
Copyright &copy; 2005 Google Inc.
<p>
Return to the <a href="index.html">PCRE index page</a>.
</p>
1	<html>
2	<head>
3	<title>pcrecpp specification</title>
4	</head>
5	<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6	<h1>pcrecpp man page</h1>
7	<p>
8	Return to the <a href="index.html">PCRE index page</a>.
9	</p>
10	<p>
11	This page is part of the PCRE HTML documentation. It was generated automatically
12	from the original man page. If there is any nonsense in it, please consult the
13	man page, in case the conversion went wrong.
14	<br>
15	<ul>
16	<li><a name="TOC1" href="#SEC1">SYNOPSIS OF C++ WRAPPER</a>
17	<li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
18	<li><a name="TOC3" href="#SEC3">MATCHING INTERFACE</a>
19	<li><a name="TOC4" href="#SEC4">PARTIAL MATCHES</a>
20	<li><a name="TOC5" href="#SEC5">UTF-8 AND THE MATCHING INTERFACE</a>
21	<li><a name="TOC6" href="#SEC6">SCANNING TEXT INCREMENTALLY</a>
22	<li><a name="TOC7" href="#SEC7">PARSING HEX/OCTAL/C-RADIX NUMBERS</a>
23	<li><a name="TOC8" href="#SEC8">REPLACING PARTS OF STRINGS</a>
24	<li><a name="TOC9" href="#SEC9">AUTHOR</a>
25	</ul>
26	<br><a name="SEC1" href="#TOC1">SYNOPSIS OF C++ WRAPPER</a><br>
27	<P>
28	<b>#include <pcrecpp.h></b>
29	</P>
30	<P>
31	</P>
32	<br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
33	<P>
34	The C++ wrapper for PCRE was provided by Google Inc. This brief man page was
35	constructed from the notes in the <i>pcrecpp.h</i> file, which should be
36	consulted for further details.
37	</P>
38	<br><a name="SEC3" href="#TOC1">MATCHING INTERFACE</a><br>
39	<P>
40	The "FullMatch" operation checks that supplied text matches a supplied pattern
41	exactly. If pointer arguments are supplied, it copies matched sub-strings that
42	match sub-patterns into them.
43	<pre>
44	Example: successful match
45	pcrecpp::RE re("h.*o");
46	re.FullMatch("hello");
47
48	Example: unsuccessful match (requires full match):
49	pcrecpp::RE re("e");
50	!re.FullMatch("hello");
51
52	Example: creating a temporary RE object:
53	pcrecpp::RE("h.*o").FullMatch("hello");
54	</pre>
55	You can pass in a "const char*" or a "string" for "text". The examples below
56	tend to use a const char*. You can, as in the different examples above, store
57	the RE object explicitly in a variable or use a temporary RE object. The
58	examples below use one mode or the other arbitrarily. Either could correctly be
59	used for any of these examples.
60	</P>
61	<P>
62	You must supply extra pointer arguments to extract matched subpieces.
63	<pre>
64	Example: extracts "ruby" into "s" and 1234 into "i"
65	int i;
66	string s;
67	pcrecpp::RE re("(\\w+):(\\d+)");
68	re.FullMatch("ruby:1234", &s, &i);
69
70	Example: does not try to extract any extra sub-patterns
71	re.FullMatch("ruby:1234", &s);
72
73	Example: does not try to extract into NULL
74	re.FullMatch("ruby:1234", NULL, &i);
75
76	Example: integer overflow causes failure
77	!re.FullMatch("ruby:1234567891234", NULL, &i);
78
79	Example: fails because there aren't enough sub-patterns:
80	!pcrecpp::RE("\\w+:\\d+").FullMatch("ruby:1234", &s);
81
82	Example: fails because string cannot be stored in integer
83	!pcrecpp::RE("(.*)").FullMatch("ruby", &i);
84	</pre>
85	The provided pointer arguments can be pointers to any scalar numeric
86	type, or one of:
87	<pre>
88	string (matched piece is copied to string)
89	StringPiece (StringPiece is mutated to point to matched piece)
90	T (where "bool T::ParseFrom(const char*, int)" exists)
91	NULL (the corresponding matched sub-pattern is not copied)
92	</pre>
93	The function returns true iff all of the following conditions are satisfied:
94	<pre>
95	a. "text" matches "pattern" exactly;
96
97	b. The number of matched sub-patterns is >= number of supplied
98	pointers;
99
100	c. The "i"th argument has a suitable type for holding the
101	string captured as the "i"th sub-pattern. If you pass in
102	NULL for the "i"th argument, or pass fewer arguments than
103	number of sub-patterns, "i"th captured sub-pattern is
104	ignored.
105	</pre>
106	The matching interface supports at most 16 arguments per call.
107	If you need more, consider using the more general interface
108	<b>pcrecpp::RE::DoMatch</b>. See <b>pcrecpp.h</b> for the signature for
109	<b>DoMatch</b>.
110	</P>
111	<br><a name="SEC4" href="#TOC1">PARTIAL MATCHES</a><br>
112	<P>
113	You can use the "PartialMatch" operation when you want the pattern
114	to match any substring of the text.
115	<pre>
116	Example: simple search for a string:
117	pcrecpp::RE("ell").PartialMatch("hello");
118
119	Example: find first number in a string:
120	int number;
121	pcrecpp::RE re("(\\d+)");
122	re.PartialMatch("x*100 + 20", &number);
123	assert(number == 100);
124	</PRE>
125	</P>
126	<br><a name="SEC5" href="#TOC1">UTF-8 AND THE MATCHING INTERFACE</a><br>
127	<P>
128	By default, pattern and text are plain text, one byte per character. The UTF8
129	flag, passed to the constructor, causes both pattern and string to be treated
130	as UTF-8 text, still a byte stream but potentially multiple bytes per
131	character. In practice, the text is likelier to be UTF-8 than the pattern, but
132	the match returned may depend on the UTF8 flag, so always use it when matching
133	UTF8 text. For example, "." will match one byte normally but with UTF8 set may
134	match up to three bytes of a multi-byte character.
135	<pre>
136	Example:
137	pcrecpp::RE_Options options;
138	options.set_utf8();
139	pcrecpp::RE re(utf8_pattern, options);
140	re.FullMatch(utf8_string);
141
142	Example: using the convenience function UTF8():
143	pcrecpp::RE re(utf8_pattern, pcrecpp::UTF8());
144	re.FullMatch(utf8_string);
145	</pre>
146	NOTE: The UTF8 flag is ignored if pcre was not configured with the
147	<pre>
148	--enable-utf8 flag.
149	</PRE>
150	</P>
151	<br><a name="SEC6" href="#TOC1">SCANNING TEXT INCREMENTALLY</a><br>
152	<P>
153	The "Consume" operation may be useful if you want to repeatedly
154	match regular expressions at the front of a string and skip over
155	them as they match. This requires use of the "StringPiece" type,
156	which represents a sub-range of a real string. Like RE, StringPiece
157	is defined in the pcrecpp namespace.
158	<pre>
159	Example: read lines of the form "var = value" from a string.
160	string contents = ...; // Fill string somehow
161	pcrecpp::StringPiece input(contents); // Wrap in a StringPiece
162	</PRE>
163	</P>
164	<P>
165	<pre>
166	string var;
167	int value;
168	pcrecpp::RE re("(\\w+) = (\\d+)\n");
169	while (re.Consume(&input, &var, &value)) {
170	...;
171	}
172	</pre>
173	Each successful call to "Consume" will set "var/value", and also
174	advance "input" so it points past the matched text.
175	</P>
176	<P>
177	The "FindAndConsume" operation is similar to "Consume" but does not
178	anchor your match at the beginning of the string. For example, you
179	could extract all words from a string by repeatedly calling
180	<pre>
181	pcrecpp::RE("(\\w+)").FindAndConsume(&input, &word)
182	</PRE>
183	</P>
184	<br><a name="SEC7" href="#TOC1">PARSING HEX/OCTAL/C-RADIX NUMBERS</a><br>
185	<P>
186	By default, if you pass a pointer to a numeric value, the
187	corresponding text is interpreted as a base-10 number. You can
188	instead wrap the pointer with a call to one of the operators Hex(),
189	Octal(), or CRadix() to interpret the text in another base. The
190	CRadix operator interprets C-style "0" (base-8) and "0x" (base-16)
191	prefixes, but defaults to base-10.
192	<pre>
193	Example:
194	int a, b, c, d;
195	pcrecpp::RE re("(.) (.) (.) (.)");
196	re.FullMatch("100 40 0100 0x40",
197	pcrecpp::Octal(&a), pcrecpp::Hex(&b),
198	pcrecpp::CRadix(&c), pcrecpp::CRadix(&d));
199	</pre>
200	will leave 64 in a, b, c, and d.
201	</P>
202	<br><a name="SEC8" href="#TOC1">REPLACING PARTS OF STRINGS</a><br>
203	<P>
204	You can replace the first match of "pattern" in "str" with "rewrite".
205	Within "rewrite", backslash-escaped digits (\1 to \9) can be
206	used to insert text matching corresponding parenthesized group
207	from the pattern. \0 in "rewrite" refers to the entire matching
208	text. For example:
209	<pre>
210	string s = "yabba dabba doo";
211	pcrecpp::RE("b+").Replace("d", &s);
212	</pre>
213	will leave "s" containing "yada dabba doo". The result is true if the pattern
214	matches and a replacement occurs, false otherwise.
215	</P>
216	<P>
217	<b>GlobalReplace</b> is like <b>Replace</b> except that it replaces all
218	occurrences of the pattern in the string with the rewrite. Replacements are
219	not subject to re-matching. For example:
220	<pre>
221	string s = "yabba dabba doo";
222	pcrecpp::RE("b+").GlobalReplace("d", &s);
223	</pre>
224	will leave "s" containing "yada dada doo". It returns the number of
225	replacements made.
226	</P>
227	<P>
228	<b>Extract</b> is like <b>Replace</b>, except that if the pattern matches,
229	"rewrite" is copied into "out" (an additional argument) with substitutions.
230	The non-matching portions of "text" are ignored. Returns true iff a match
231	occurred and the extraction happened successfully; if no match occurs, the
232	string is left unaffected.
233	</P>
234	<br><a name="SEC9" href="#TOC1">AUTHOR</a><br>
235	<P>
236	The C++ wrapper was contributed by Google Inc.
237	<br>
238	Copyright © 2005 Google Inc.
239	<p>
240	Return to the <a href="index.html">PCRE index page</a>.
241	</p>