FCL/sf/os/fshell: libraries/spcre/libpcre/pcre/doc/html/pcrecpp.html@7f656887cf89 (annotated)

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

author	Tom Sutcliffe <thomas.sutcliffe@accenture.com>
	Wed, 23 Jun 2010 15:52:26 +0100
changeset 0	7f656887cf89
permissions	-rw-r--r--