trunk/doc/pcrecpp.3

.TH PCRECPP 3
.SH NAME
PCRE - Perl-compatible regular expressions.
.SH "SYNOPSIS OF C++ WRAPPER"
.rs
.sp
.B #include <pcrecpp.h>
.PP
.SM
.br
.SH DESCRIPTION
.rs
.sp
The C++ wrapper for PCRE was provided by Google Inc. Some additional
functionality was added by Giuseppe Maxia. This brief man page was constructed
from the notes in the \fIpcrecpp.h\fP file, which should be consulted for
further details.
.
.
.SH "MATCHING INTERFACE"
.rs
.sp
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.
.sp
  Example: successful match
     pcrecpp::RE re("h.*o");
     re.FullMatch("hello");
.sp
  Example: unsuccessful match (requires full match):
     pcrecpp::RE re("e");
     !re.FullMatch("hello");
.sp
  Example: creating a temporary RE object:
     pcrecpp::RE("h.*o").FullMatch("hello");
.sp
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
You must supply extra pointer arguments to extract matched subpieces.
.sp
  Example: extracts "ruby" into "s" and 1234 into "i"
     int i;
     string s;
     pcrecpp::RE re("(\e\ew+):(\e\ed+)");
     re.FullMatch("ruby:1234", &s, &i);
.sp
  Example: does not try to extract any extra sub-patterns
     re.FullMatch("ruby:1234", &s);
.sp
  Example: does not try to extract into NULL
     re.FullMatch("ruby:1234", NULL, &i);
.sp
  Example: integer overflow causes failure
     !re.FullMatch("ruby:1234567891234", NULL, &i);
.sp
  Example: fails because there aren't enough sub-patterns:
     !pcrecpp::RE("\e\ew+:\e\ed+").FullMatch("ruby:1234", &s);
.sp
  Example: fails because string cannot be stored in integer
     !pcrecpp::RE("(.*)").FullMatch("ruby", &i);
.sp
The provided pointer arguments can be pointers to any scalar numeric
type, or one of:
.sp
   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)
.sp
The function returns true iff all of the following conditions are satisfied:
.sp
  a. "text" matches "pattern" exactly;
.sp
  b. The number of matched sub-patterns is >= number of supplied
     pointers;
.sp
  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.
.sp
CAVEAT: An optional sub-pattern that does not exist in the matched
string is assigned the empty string. Therefore, the following will
return false (because the empty string is not a valid number):
.sp
   int number;
   pcrecpp::RE::FullMatch("abc", "[a-z]+(\\d+)?", &number);
.sp
The matching interface supports at most 16 arguments per call.
If you need more, consider using the more general interface
\fBpcrecpp::RE::DoMatch\fP. See \fBpcrecpp.h\fP for the signature for
\fBDoMatch\fP.
.
.SH "QUOTING METACHARACTERS"
.rs
.sp
You can use the "QuoteMeta" operation to insert backslashes before all
potentially meaningful characters in a string. The returned string, used as a
regular expression, will exactly match the original string.
.sp
  Example:
     string quoted = RE::QuoteMeta(unquoted);
.sp
Note that it's legal to escape a character even if it has no special meaning in
a regular expression -- so this function does that. (This also makes it
identical to the perl function of the same name; see "perldoc -f quotemeta".)
For example, "1.5-2.0?" becomes "1\e.5\e-2\e.0\e?".
.
.SH "PARTIAL MATCHES"
.rs
.sp
You can use the "PartialMatch" operation when you want the pattern
to match any substring of the text.
.sp
  Example: simple search for a string:
     pcrecpp::RE("ell").PartialMatch("hello");
.sp
  Example: find first number in a string:
     int number;
     pcrecpp::RE re("(\e\ed+)");
     re.PartialMatch("x*100 + 20", &number);
     assert(number == 100);
.
.
.SH "UTF-8 AND THE MATCHING INTERFACE"
.rs
.sp
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.
.sp
  Example:
     pcrecpp::RE_Options options;
     options.set_utf8();
     pcrecpp::RE re(utf8_pattern, options);
     re.FullMatch(utf8_string);
.sp
  Example: using the convenience function UTF8():
     pcrecpp::RE re(utf8_pattern, pcrecpp::UTF8());
     re.FullMatch(utf8_string);
.sp
NOTE: The UTF8 flag is ignored if pcre was not configured with the
      --enable-utf8 flag.
.
.
.SH "PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE"
.rs
.sp
PCRE defines some modifiers to change the behavior of the regular expression
engine. The C++ wrapper defines an auxiliary class, RE_Options, as a vehicle to
pass such modifiers to a RE class. Currently, the following modifiers are
supported:
.sp
   modifier              description               Perl corresponding
.sp
   PCRE_CASELESS         case insensitive match      /i
   PCRE_MULTILINE        multiple lines match        /m
   PCRE_DOTALL           dot matches newlines        /s
   PCRE_DOLLAR_ENDONLY   $ matches only at end       N/A
   PCRE_EXTRA            strict escape parsing       N/A
   PCRE_EXTENDED         ignore whitespaces          /x
   PCRE_UTF8             handles UTF8 chars          built-in
   PCRE_UNGREEDY         reverses * and *?           N/A
   PCRE_NO_AUTO_CAPTURE  disables capturing parens   N/A (*)
.sp
(*) Both Perl and PCRE allow non capturing parentheses by means of the
"?:" modifier within the pattern itself. e.g. (?:ab|cd) does not
capture, while (ab|cd) does.
.P
For a full account on how each modifier works, please check the
PCRE API reference page.
.P
For each modifier, there are two member functions whose name is made
out of the modifier in lowercase, without the "PCRE_" prefix. For
instance, PCRE_CASELESS is handled by
.sp
  bool caseless()
.sp
which returns true if the modifier is set, and
.sp
  RE_Options & set_caseless(bool)
.sp
which sets or unsets the modifier. Moreover, PCRE_EXTRA_MATCH_LIMIT can be
accessed through the \fBset_match_limit()\fR and \fBmatch_limit()\fR member
functions. Setting \fImatch_limit\fR to a non-zero value will limit the
execution of pcre to keep it from doing bad things like blowing the stack or
taking an eternity to return a result. A value of 5000 is good enough to stop
stack blowup in a 2MB thread stack. Setting \fImatch_limit\fR to zero disables
match limiting. Alternatively, you can call \fBmatch_limit_recursion()\fP
which uses PCRE_EXTRA_MATCH_LIMIT_RECURSION to limit how much PCRE
recurses. \fBmatch_limit()\fP limits the number of matches PCRE does;
\fBmatch_limit_recursion()\fP limits the depth of internal recursion, and
therefore the amount of stack that is used.
.P
Normally, to pass one or more modifiers to a RE class, you declare
a \fIRE_Options\fR object, set the appropriate options, and pass this
object to a RE constructor. Example:
.sp
   RE_options opt;
   opt.set_caseless(true);
   if (RE("HELLO", opt).PartialMatch("hello world")) ...
.sp
RE_options has two constructors. The default constructor takes no arguments and
creates a set of flags that are off by default. The optional parameter
\fIoption_flags\fR is to facilitate transfer of legacy code from C programs.
This lets you do
.sp
   RE(pattern,
     RE_Options(PCRE_CASELESS|PCRE_MULTILINE)).PartialMatch(str);
.sp
However, new code is better off doing
.sp
   RE(pattern,
     RE_Options().set_caseless(true).set_multiline(true))
       .PartialMatch(str);
.sp
If you are going to pass one of the most used modifiers, there are some
convenience functions that return a RE_Options class with the
appropriate modifier already set: \fBCASELESS()\fR, \fBUTF8()\fR,
\fBMULTILINE()\fR, \fBDOTALL\fR(), and \fBEXTENDED()\fR.
.P
If you need to set several options at once, and you don't want to go through
the pains of declaring a RE_Options object and setting several options, there
is a parallel method that give you such ability on the fly. You can concatenate
several \fBset_xxxxx()\fR member functions, since each of them returns a
reference to its class object. For example, to pass PCRE_CASELESS,
PCRE_EXTENDED, and PCRE_MULTILINE to a RE with one statement, you may write:
.sp
   RE(" ^ xyz \e\es+ .* blah$",
     RE_Options()
       .set_caseless(true)
       .set_extended(true)
       .set_multiline(true)).PartialMatch(sometext);
.sp
.
.
.SH "SCANNING TEXT INCREMENTALLY"
.rs
.sp
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.
.sp
  Example: read lines of the form "var = value" from a string.
     string contents = ...;                 // Fill string somehow
     pcrecpp::StringPiece input(contents);  // Wrap in a StringPiece

     string var;
     int value;
     pcrecpp::RE re("(\e\ew+) = (\e\ed+)\en");
     while (re.Consume(&input, &var, &value)) {
       ...;
     }
.sp
Each successful call to "Consume" will set "var/value", and also
advance "input" so it points past the matched text.
.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
.sp
  pcrecpp::RE("(\e\ew+)").FindAndConsume(&input, &word)
.
.
.SH "PARSING HEX/OCTAL/C-RADIX NUMBERS"
.rs
.sp
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.
.sp
  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));
.sp
will leave 64 in a, b, c, and d.
.
.
.SH "REPLACING PARTS OF STRINGS"
.rs
.sp
You can replace the first match of "pattern" in "str" with "rewrite".
Within "rewrite", backslash-escaped digits (\e1 to \e9) can be
used to insert text matching corresponding parenthesized group
from the pattern. \e0 in "rewrite" refers to the entire matching
text. For example:
.sp
  string s = "yabba dabba doo";
  pcrecpp::RE("b+").Replace("d", &s);
.sp
will leave "s" containing "yada dabba doo". The result is true if the pattern
matches and a replacement occurs, false otherwise.
.P
\fBGlobalReplace\fP is like \fBReplace\fP except that it replaces all
occurrences of the pattern in the string with the rewrite. Replacements are
not subject to re-matching. For example:
.sp
  string s = "yabba dabba doo";
  pcrecpp::RE("b+").GlobalReplace("d", &s);
.sp
will leave "s" containing "yada dada doo". It returns the number of
replacements made.
.P
\fBExtract\fP is like \fBReplace\fP, 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.
.
.
.SH AUTHOR
.rs
.sp
The C++ wrapper was contributed by Google Inc.
.br
Copyright (c) 2006 Google Inc.
1	nigel	79	.TH PCRECPP 3
2	nigel	77	.SH NAME
3			PCRE - Perl-compatible regular expressions.
4			.SH "SYNOPSIS OF C++ WRAPPER"
5			.rs
6			.sp
7			.B #include <pcrecpp.h>
8			.PP
9			.SM
10			.br
11			.SH DESCRIPTION
12			.rs
13			.sp
14	nigel	81	The C++ wrapper for PCRE was provided by Google Inc. Some additional
15			functionality was added by Giuseppe Maxia. This brief man page was constructed
16			from the notes in the \fIpcrecpp.h\fP file, which should be consulted for
17			further details.
18	nigel	77	.
19			.
20			.SH "MATCHING INTERFACE"
21			.rs
22			.sp
23			The "FullMatch" operation checks that supplied text matches a supplied pattern
24			exactly. If pointer arguments are supplied, it copies matched sub-strings that
25			match sub-patterns into them.
26			.sp
27			Example: successful match
28			pcrecpp::RE re("h.*o");
29			re.FullMatch("hello");
30			.sp
31			Example: unsuccessful match (requires full match):
32			pcrecpp::RE re("e");
33			!re.FullMatch("hello");
34			.sp
35			Example: creating a temporary RE object:
36			pcrecpp::RE("h.*o").FullMatch("hello");
37			.sp
38			You can pass in a "const char*" or a "string" for "text". The examples below
39			tend to use a const char*. You can, as in the different examples above, store
40			the RE object explicitly in a variable or use a temporary RE object. The
41			examples below use one mode or the other arbitrarily. Either could correctly be
42			used for any of these examples.
43			.P
44			You must supply extra pointer arguments to extract matched subpieces.
45			.sp
46			Example: extracts "ruby" into "s" and 1234 into "i"
47			int i;
48			string s;
49			pcrecpp::RE re("(\e\ew+):(\e\ed+)");
50			re.FullMatch("ruby:1234", &s, &i);
51			.sp
52			Example: does not try to extract any extra sub-patterns
53			re.FullMatch("ruby:1234", &s);
54			.sp
55			Example: does not try to extract into NULL
56			re.FullMatch("ruby:1234", NULL, &i);
57			.sp
58			Example: integer overflow causes failure
59			!re.FullMatch("ruby:1234567891234", NULL, &i);
60			.sp
61			Example: fails because there aren't enough sub-patterns:
62			!pcrecpp::RE("\e\ew+:\e\ed+").FullMatch("ruby:1234", &s);
63			.sp
64			Example: fails because string cannot be stored in integer
65			!pcrecpp::RE("(.*)").FullMatch("ruby", &i);
66			.sp
67			The provided pointer arguments can be pointers to any scalar numeric
68			type, or one of:
69			.sp
70			string (matched piece is copied to string)
71			StringPiece (StringPiece is mutated to point to matched piece)
72			T (where "bool T::ParseFrom(const char*, int)" exists)
73			NULL (the corresponding matched sub-pattern is not copied)
74			.sp
75			The function returns true iff all of the following conditions are satisfied:
76			.sp
77			a. "text" matches "pattern" exactly;
78			.sp
79			b. The number of matched sub-patterns is >= number of supplied
80			pointers;
81			.sp
82			c. The "i"th argument has a suitable type for holding the
83			string captured as the "i"th sub-pattern. If you pass in
84			NULL for the "i"th argument, or pass fewer arguments than
85			number of sub-patterns, "i"th captured sub-pattern is
86			ignored.
87			.sp
88	nigel	93	CAVEAT: An optional sub-pattern that does not exist in the matched
89			string is assigned the empty string. Therefore, the following will
90			return false (because the empty string is not a valid number):
91			.sp
92			int number;
93			pcrecpp::RE::FullMatch("abc", "[a-z]+(\\d+)?", &number);
94			.sp
95	nigel	77	The matching interface supports at most 16 arguments per call.
96			If you need more, consider using the more general interface
97			\fBpcrecpp::RE::DoMatch\fP. See \fBpcrecpp.h\fP for the signature for
98			\fBDoMatch\fP.
99			.
100	nigel	93	.SH "QUOTING METACHARACTERS"
101			.rs
102			.sp
103			You can use the "QuoteMeta" operation to insert backslashes before all
104			potentially meaningful characters in a string. The returned string, used as a
105			regular expression, will exactly match the original string.
106			.sp
107			Example:
108			string quoted = RE::QuoteMeta(unquoted);
109			.sp
110			Note that it's legal to escape a character even if it has no special meaning in
111			a regular expression -- so this function does that. (This also makes it
112			identical to the perl function of the same name; see "perldoc -f quotemeta".)
113			For example, "1.5-2.0?" becomes "1\e.5\e-2\e.0\e?".
114			.
115	nigel	77	.SH "PARTIAL MATCHES"
116			.rs
117			.sp
118			You can use the "PartialMatch" operation when you want the pattern
119			to match any substring of the text.
120			.sp
121			Example: simple search for a string:
122			pcrecpp::RE("ell").PartialMatch("hello");
123			.sp
124			Example: find first number in a string:
125			int number;
126			pcrecpp::RE re("(\e\ed+)");
127			re.PartialMatch("x*100 + 20", &number);
128			assert(number == 100);
129			.
130			.
131			.SH "UTF-8 AND THE MATCHING INTERFACE"
132			.rs
133			.sp
134			By default, pattern and text are plain text, one byte per character. The UTF8
135			flag, passed to the constructor, causes both pattern and string to be treated
136			as UTF-8 text, still a byte stream but potentially multiple bytes per
137			character. In practice, the text is likelier to be UTF-8 than the pattern, but
138			the match returned may depend on the UTF8 flag, so always use it when matching
139			UTF8 text. For example, "." will match one byte normally but with UTF8 set may
140			match up to three bytes of a multi-byte character.
141			.sp
142			Example:
143			pcrecpp::RE_Options options;
144			options.set_utf8();
145			pcrecpp::RE re(utf8_pattern, options);
146			re.FullMatch(utf8_string);
147			.sp
148			Example: using the convenience function UTF8():
149			pcrecpp::RE re(utf8_pattern, pcrecpp::UTF8());
150			re.FullMatch(utf8_string);
151			.sp
152			NOTE: The UTF8 flag is ignored if pcre was not configured with the
153			--enable-utf8 flag.
154			.
155			.
156	nigel	81	.SH "PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE"
157			.rs
158			.sp
159			PCRE defines some modifiers to change the behavior of the regular expression
160			engine. The C++ wrapper defines an auxiliary class, RE_Options, as a vehicle to
161			pass such modifiers to a RE class. Currently, the following modifiers are
162			supported:
163			.sp
164			modifier description Perl corresponding
165			.sp
166			PCRE_CASELESS case insensitive match /i
167			PCRE_MULTILINE multiple lines match /m
168			PCRE_DOTALL dot matches newlines /s
169			PCRE_DOLLAR_ENDONLY $ matches only at end N/A
170			PCRE_EXTRA strict escape parsing N/A
171			PCRE_EXTENDED ignore whitespaces /x
172			PCRE_UTF8 handles UTF8 chars built-in
173			PCRE_UNGREEDY reverses * and *? N/A
174			PCRE_NO_AUTO_CAPTURE disables capturing parens N/A (*)
175			.sp
176			(*) Both Perl and PCRE allow non capturing parentheses by means of the
177			"?:" modifier within the pattern itself. e.g. (?:ab\|cd) does not
178			capture, while (ab\|cd) does.
179			.P
180			For a full account on how each modifier works, please check the
181			PCRE API reference page.
182			.P
183			For each modifier, there are two member functions whose name is made
184			out of the modifier in lowercase, without the "PCRE_" prefix. For
185			instance, PCRE_CASELESS is handled by
186			.sp
187			bool caseless()
188			.sp
189			which returns true if the modifier is set, and
190			.sp
191			RE_Options & set_caseless(bool)
192			.sp
193	nigel	87	which sets or unsets the modifier. Moreover, PCRE_EXTRA_MATCH_LIMIT can be
194	nigel	81	accessed through the \fBset_match_limit()\fR and \fBmatch_limit()\fR member
195			functions. Setting \fImatch_limit\fR to a non-zero value will limit the
196			execution of pcre to keep it from doing bad things like blowing the stack or
197			taking an eternity to return a result. A value of 5000 is good enough to stop
198			stack blowup in a 2MB thread stack. Setting \fImatch_limit\fR to zero disables
199	nigel	87	match limiting. Alternatively, you can call \fBmatch_limit_recursion()\fP
200			which uses PCRE_EXTRA_MATCH_LIMIT_RECURSION to limit how much PCRE
201			recurses. \fBmatch_limit()\fP limits the number of matches PCRE does;
202			\fBmatch_limit_recursion()\fP limits the depth of internal recursion, and
203			therefore the amount of stack that is used.
204	nigel	81	.P
205			Normally, to pass one or more modifiers to a RE class, you declare
206			a \fIRE_Options\fR object, set the appropriate options, and pass this
207			object to a RE constructor. Example:
208			.sp
209			RE_options opt;
210			opt.set_caseless(true);
211			if (RE("HELLO", opt).PartialMatch("hello world")) ...
212			.sp
213			RE_options has two constructors. The default constructor takes no arguments and
214			creates a set of flags that are off by default. The optional parameter
215			\fIoption_flags\fR is to facilitate transfer of legacy code from C programs.
216			This lets you do
217			.sp
218			RE(pattern,
219			RE_Options(PCRE_CASELESS\|PCRE_MULTILINE)).PartialMatch(str);
220			.sp
221			However, new code is better off doing
222			.sp
223			RE(pattern,
224			RE_Options().set_caseless(true).set_multiline(true))
225			.PartialMatch(str);
226			.sp
227			If you are going to pass one of the most used modifiers, there are some
228			convenience functions that return a RE_Options class with the
229			appropriate modifier already set: \fBCASELESS()\fR, \fBUTF8()\fR,
230			\fBMULTILINE()\fR, \fBDOTALL\fR(), and \fBEXTENDED()\fR.
231			.P
232			If you need to set several options at once, and you don't want to go through
233			the pains of declaring a RE_Options object and setting several options, there
234			is a parallel method that give you such ability on the fly. You can concatenate
235			several \fBset_xxxxx()\fR member functions, since each of them returns a
236			reference to its class object. For example, to pass PCRE_CASELESS,
237			PCRE_EXTENDED, and PCRE_MULTILINE to a RE with one statement, you may write:
238			.sp
239			RE(" ^ xyz \e\es+ .* blah$",
240			RE_Options()
241			.set_caseless(true)
242			.set_extended(true)
243			.set_multiline(true)).PartialMatch(sometext);
244			.sp
245			.
246			.
247	nigel	77	.SH "SCANNING TEXT INCREMENTALLY"
248			.rs
249			.sp
250			The "Consume" operation may be useful if you want to repeatedly
251			match regular expressions at the front of a string and skip over
252			them as they match. This requires use of the "StringPiece" type,
253			which represents a sub-range of a real string. Like RE, StringPiece
254			is defined in the pcrecpp namespace.
255			.sp
256			Example: read lines of the form "var = value" from a string.
257			string contents = ...; // Fill string somehow
258			pcrecpp::StringPiece input(contents); // Wrap in a StringPiece
259
260			string var;
261			int value;
262			pcrecpp::RE re("(\e\ew+) = (\e\ed+)\en");
263			while (re.Consume(&input, &var, &value)) {
264			...;
265			}
266			.sp
267			Each successful call to "Consume" will set "var/value", and also
268			advance "input" so it points past the matched text.
269			.P
270			The "FindAndConsume" operation is similar to "Consume" but does not
271			anchor your match at the beginning of the string. For example, you
272			could extract all words from a string by repeatedly calling
273			.sp
274			pcrecpp::RE("(\e\ew+)").FindAndConsume(&input, &word)
275			.
276			.
277			.SH "PARSING HEX/OCTAL/C-RADIX NUMBERS"
278			.rs
279			.sp
280			By default, if you pass a pointer to a numeric value, the
281			corresponding text is interpreted as a base-10 number. You can
282			instead wrap the pointer with a call to one of the operators Hex(),
283			Octal(), or CRadix() to interpret the text in another base. The
284			CRadix operator interprets C-style "0" (base-8) and "0x" (base-16)
285			prefixes, but defaults to base-10.
286			.sp
287			Example:
288			int a, b, c, d;
289			pcrecpp::RE re("(.) (.) (.) (.)");
290			re.FullMatch("100 40 0100 0x40",
291			pcrecpp::Octal(&a), pcrecpp::Hex(&b),
292			pcrecpp::CRadix(&c), pcrecpp::CRadix(&d));
293			.sp
294			will leave 64 in a, b, c, and d.
295			.
296			.
297			.SH "REPLACING PARTS OF STRINGS"
298			.rs
299			.sp
300			You can replace the first match of "pattern" in "str" with "rewrite".
301			Within "rewrite", backslash-escaped digits (\e1 to \e9) can be
302			used to insert text matching corresponding parenthesized group
303			from the pattern. \e0 in "rewrite" refers to the entire matching
304			text. For example:
305			.sp
306			string s = "yabba dabba doo";
307			pcrecpp::RE("b+").Replace("d", &s);
308			.sp
309			will leave "s" containing "yada dabba doo". The result is true if the pattern
310			matches and a replacement occurs, false otherwise.
311			.P
312			\fBGlobalReplace\fP is like \fBReplace\fP except that it replaces all
313			occurrences of the pattern in the string with the rewrite. Replacements are
314			not subject to re-matching. For example:
315			.sp
316			string s = "yabba dabba doo";
317			pcrecpp::RE("b+").GlobalReplace("d", &s);
318			.sp
319			will leave "s" containing "yada dada doo". It returns the number of
320			replacements made.
321			.P
322			\fBExtract\fP is like \fBReplace\fP, except that if the pattern matches,
323			"rewrite" is copied into "out" (an additional argument) with substitutions.
324			The non-matching portions of "text" are ignored. Returns true iff a match
325			occurred and the extraction happened successfully; if no match occurs, the
326			string is left unaffected.
327			.
328			.
329			.SH AUTHOR
330			.rs
331			.sp
332			The C++ wrapper was contributed by Google Inc.
333			.br
334	nigel	93	Copyright (c) 2006 Google Inc.