<P>Class regbase is the template argument independent base class for reg_expression, the only public members are the <I>flag_type</I> enumerated values that determine how regular expressions are interpreted. </P>
</I></FONT> limited_ops = intervals << 1, <I><FONTCOLOR="#000080">// all of + ? and | are normal characters
</I></FONT> newline_alt = limited_ops << 1, <I><FONTCOLOR="#000080">// \n is the same as |
</I></FONT> bk_plus_qm = newline_alt << 1, <I><FONTCOLOR="#000080">// uses \+ and \?
</I></FONT> bk_braces = bk_plus_qm << 1, <I><FONTCOLOR="#000080">// uses \{ and \}
</I></FONT> bk_parens = bk_braces << 1, <I><FONTCOLOR="#000080">// uses \( and \)
</I></FONT> use_except = bk_vbar << 1, <I><FONTCOLOR="#000080">// exception on error
</I></FONT> failbit = use_except << 1, <I><FONTCOLOR="#000080">// error flag
</I></FONT> literal = failbit << 1, <I><FONTCOLOR="#000080">// all characters are literals
</I></FONT> icase = literal << 1, <I><FONTCOLOR="#000080">// characters are matched regardless of case
</I></FONT> nocollate = icase << 1, <I><FONTCOLOR="#000080">// don't use locale specific collation
<P>The enumerated type <I>regbase::flag_type</I> determines the syntax rules for regular expression compilation, the various flags have the following effects: <BR>
<P>Allows the use of the escape "\" character in sets of characters, for example [\]] represents the set of characters containing only "]". If this flag is not set then "\" is an ordinary character inside sets.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase::char_classes</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set, character classes [:classname:] are allowed inside character set declarations, for example "[[:word:]]" represents the set of all characters that belong to the character class "word".</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: intervals</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set, repetition intervals are allowed, for example "a{2,4}" represents a repeat of between 2 and 4 letter a's.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: limited_ops</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set all of "+", "?" and "|" are ordinary characters in all situations.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: newline_alt</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set, then the newline character "\n" has the same effect as the alternation operator "|".</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: bk_plus_qm</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set then "\+" represents the one or more repetition operator and "\?" represents the zero or one repetition operator. When this bit is not set then "+" and "?" are used instead.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: bk_braces</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set then "\{" and "\}" are used for bounded repetitions and "{" and "}" are normal characters. This is the opposite of default behavior.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: bk_parens</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set then "\(" and "\)" are used to group sub-expressions and "(" and ")" are ordinary characters, this is the opposite of default behaviour.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: bk_refs</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set then back references are allowed.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: bk_vbar</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set then "\|" represents the alternation operator and "|" is an ordinary character. This is the opposite of default behaviour.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: use_except</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>When this bit is set then a <AHREF="#bad_expression">bad_expression</A> exception will be thrown on error. Use of this flag is deprecated - reg_expression will always throw on error.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase:: failbit</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>This bit is set on error, if regbase::use_except is not set, then this bit should be checked to see if a regular expression is valid before usage.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase::literal</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>All characters in the string are treated as literals, there are no special characters or escape sequences.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase::icase</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>All characters in the string are matched regardless of case.</TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase::nocollate</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>Locale specific collation is disabled when dealing with ranges in character set declarations. For example when this bit is set the expression [a-c] would match the characters a, b and c only regardless of locale, where as when this is not set , then [a-c] matches any character which collates in the range a to c.</TD>
<TDWIDTH="5%"VALIGN="TOP">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>regbase::basic</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>Equivalent to the POSIX basic regular expression syntax: char_classes | intervals | limited_ops | bk_braces | bk_parens | bk_refs.</TD>
<TDWIDTH="5%"VALIGN="TOP">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP">
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>Regbase::extended</TD>
<TDWIDTH="45%"VALIGN="TOP">
<P>Equivalent to the POSIX extended regular expression syntax: char_classes | intervals | bk_refs.</TD>
<TDWIDTH="5%"VALIGN="TOP">
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>regbase::normal</TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>This is the default setting, and represents how most people expect the library to behave. Equivalent to the POSIX extended syntax, but with locale specific collation disabled, and escape characters inside set declarations enabled: regbase::escape_in_lists | regbase::char_classes | regbase::intervals | regbase::bk_refs | regbase::nocollate.</TD>
<TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>regbase::emacs</TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>Provides compatability with the emacs editor, eqivalent to: bk_braces | bk_parens | bk_refs | bk_vbar.</TD>
<TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>regbase::awk </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>Provides compatabilty with the Unix utility Awk, the same as POSIX extended regular expressions, but allows escapes inside bracket-expressions (character sets). Equivalent to extended | escape_in_lists.</TD>
<TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>regbase::grep</TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>Provides compatabilty with the Unix grep utility, the same as POSIX basic regular expressions, but with the newline character equivalent to the alternation operator. the same as basic | newline_alt.</TD>
<TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>regbase::egrep</TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>Provides compatabilty with the Unix egrep utility, the same as POSIX extended regular expressions, but with the newline character equivalent to the alternation operator. the same as extended | newline_alt.</TD>
<TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>regbase::sed</TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>Provides compatabilty with the Unix sed utility, the same as POSIX basic regular expressions.</TD>
<TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="TOP"HEIGHT=24>
<P> </TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>regbase::perl</TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=24>
<P>Provides compatibility with the perl programming language, the same as regbase::normal.</TD>
<P>Footnotes: the class <I>bad_pattern </I>forms the base class for all pattern-matching exceptions, of which <I>bad_expression</I> is one. The choice of <I>std::runtime_error </I>as the base class for <I>bad_pattern</I> is moot, depending upon how the library is used exceptions may be either logic errors (programmer supplied expressions) or run time errors (user supplied expressions). </P>
<P>The template class <I>reg_expression </I>encapsulates regular expression parsing and compilation. The class derives from class <AHREF="#regbase"><I>regbase</I></A> and takes three template parameters: </P>
<B><I><P>charT</B></I>: determines the character type, i.e. either char or wchar_t. </P>
<B><I><P>traits</B></I>: determines the behaviour of the character type, for example whether character matching is case sensitive or not, and which character class names are recognized. A default traits class is provided: <AHREF="#regex_char_traits">regex_traits<charT></A>. </P>
<B><I><P>Allocator</B></I>: the allocator class used to allocate memory by the class. </P>
<P>For ease of use there are two typedefs that define the two standard <I>reg_expression</I> instances, unless you want to use custom allocators, you won't need to use anything other than these: </P>
<P>The definition of <I>reg_expression</I> follows: it is based very closely on class basic_string, and fulfils the requirements for a container of <I>charT</I>. </P>
iterator last,
flag_type f = regbase::normal);
<FONTSIZE=2><P>reg_expression(Allocator a = Allocator());</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P> Constructs a default instance of reg_expression without any expression.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>reg_expression(charT* p, <B>unsigned</B> f = regbase::normal, Allocator a = Allocator());</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P> Constructs an instance of reg_expression from the expression denoted by the null terminated string <B>p</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>reg_expression(charT* p1, charT* p2, <B>unsigned</B> f = regbase::normal, Allocator a = Allocator());</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P> Constructs an instance of reg_expression from the expression denoted by pair of iterators <B>p1</B> and <B>p2</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>reg_expression(charT* p, size_type len, <B>unsigned</B> f, Allocator a = Allocator());</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P> Constructs an instance of reg_expression from the expression denoted by the string <B>p</B> of length <B>len</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<B><FONTSIZE=2><P>template</B><class ST, class SA><BR>
reg_expression(<B>const</B> std::basic_string<charT, ST, SA>& p, jm_uintfast32_t f = regbase::normal, <B>const</B> Allocator& a = Allocator());</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P> Constructs an instance of reg_expression from the expression denoted by the string <B>p</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values. </P>
<P>Note - this member may not be available depending upon your compiler capabilities.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>template <class I><BR>
reg_expression(I first, I last, flag_type f = regbase::normal, const Allocator& a = Allocator());</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P> Constructs an instance of reg_expression from the expression denoted by pair of iterators <B>p1</B> and <B>p2</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values.</FONT></TD>
<FONTSIZE=2><P>Copies the regular expression contained by <B>that</B>, throws </FONT><AHREF="#bad_expression"><FONTSIZE=2>bad_expression</FONT></A><FONTSIZE=2> if <B>that</B> does not contain a valid expression. Returns *this.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>reg_expression& assign(<B>const</B> charT* p, flag_type f = regbase::normal);</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>Compiles a regular expression from the expression denoted by the null terminated string <B>p</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values. Throws </FONT><AHREF="#bad_expression"><FONTSIZE=2>bad_expression</FONT></A><FONTSIZE=2> if <B>p</B> does not contain a valid expression. Returns *this.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>reg_expression& assign(<B>const</B> charT* first, <B>const</B> charT* last, flag_type f = regbase::normal);</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>Compiles a regular expression from the expression denoted by the pair of iterators <B>first-last</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values. Throws </FONT><AHREF="#bad_expression"><FONTSIZE=2>bad_expression</FONT></A><FONTSIZE=2> if <B>first-last</B> does not contain a valid expression. Returns *this.</FONT></TD>
reg_expression& assign(<B>const</B> std::basic_string<charT, string_traits, A>& s, flag_type f = regbase::normal);</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>Compiles a regular expression from the expression denoted by the string <B>s</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values. Throws </FONT><AHREF="#bad_expression"><FONTSIZE=2>bad_expression</FONT></A><FONTSIZE=2> if <B>s</B> does not contain a valid expression. Returns *this.</FONT></TD>
reg_expression& assign(iterator first, iterator last, flag_type f = regbase::normal);</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>Compiles a regular expression from the expression denoted by the pair of iterators <B>first-last</B>, using the flags <B>f</B> to determine regular expression syntax. See class </FONT><AHREF="#regbase"><FONTSIZE=2>regbase</FONT></A><FONTSIZE=2> for allowable flag values. Throws </FONT><AHREF="#bad_expression"><FONTSIZE=2>bad_expression</FONT></A><FONTSIZE=2> if <B>first-last</B> does not contain a valid expression. Returns *this.</FONT></TD>
<FONTSIZE=2><P>Returns the number of sub-expressions in the compiled regular expression. Note that this includes the whole match (subexpression zero), so the value returned is always >= 1.</FONT></TD>
<I><P>This is a preliminary version of the regular expression traits class, and is subject to change</I>. </P>
<P>The purpose of the traits class is to make it easier to customise the behaviour of <I>reg_expression </I>and the associated matching algorithms. Custom traits classes can handle special character sets or define additional character classes, for example one could define [[:kanji:]] as the set of all (Unicode) kanji characters. This library provides three traits classes and a wrapper class <I>regex_traits</I>, which inherits from one of these depending upon the default localisation model in use, class <I>c_regex_traits</I> encapsulates the global C locale, class <I>w32_regex_traits</I> encapsulates the global Win32 locale (only available on Win32 systems), and class <I>cpp_regex_traits</I> encapsulates the C++ locale (only provided if std::locale is supported): </P>
</FONT><PRE>template <class charT> class c_regex_traits;
template <class charT> class regex_traits : public base_type { /*detailts*/ };</PRE>
<FONTSIZE=2><P>Where "<I>base_type</I>" defaults to <I>w32_regex_traits</I> on Win32 systems, and <I>c_regex_traits</I> otherwise. The default behaviour can be changed by defining one of BOOST_RE_LOCALE_C (forces use of <I>c_regex_traits</I> by default), or BOOST_RE_LOCALE_CPP (forces use of <I>cpp_regex_traits</I> by default). Alternatively a specific traits class can be passed to the <I>reg_expression</I> template. </P>
<P>The requirements for custom traits classes are </FONT><AHREF="traits_class_ref.htm"><FONTSIZE=2>documented separately here....</FONT></A><FONTSIZE=2></P>
<P>Regular expressions are different from many simple pattern-matching algorithms in that as well as finding an overall match they can also produce sub-expression matches: each sub-expression being delimited in the pattern by a pair of parenthesis (...). There has to be some method for reporting sub-expression matches back to the user: this is achieved this by defining a class <I>match_results</I> that acts as an indexed collection of sub-expression matches, each sub-expression match being contained in an object of type <I>sub_match</I>. </P>
<FONTSIZE=2><P>Class match_results is used for reporting what matched a regular expression, it is passed to the matching algorithms </FONT><AHREF="#query_match"><FONTSIZE=2>regex_match</FONT></A><FONTSIZE=2> and </FONT><AHREF="#reg_search"><FONTSIZE=2>regex_search</FONT></A><FONTSIZE=2>, and is used by </FONT><AHREF="#reg_grep"><FONTSIZE=2>regex_grep</FONT></A><FONTSIZE=2> to notify the callback function (or function object) what matched. Note that the default allocator parameter has been chosen to match the default allocator parameter to reg_expression. match_results has the following public member functions: <BR>
<FONTSIZE=2><P>Returns the allocator used by the class.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>difference_type length(<B>unsigned int</B> sub = 0);</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>Returns the length of the matched subexpression, defaults to the length of the whole match, in effect this is equivalent to operator[](sub).second - operator[](sub).first.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>difference_type position(<B>unsigned int</B> sub = 0);</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>Returns the position of the matched sub-expression, defaults to the position of the whole match. The returned value is the position of the match relative to the start of the string.</FONT></TD>
<FONTSIZE=2><P>Returns the index of the line on which the match occurred, indices start with 1, not zero. Equivalent to the number of newline characters prior to operator[](0).first plus one.</FONT></TD>
<FONTSIZE=2><P>Returns how many sub-expressions are present in the match, including sub-expression zero (the whole match). Returns zero if no matches were found in the search operation.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
</TABLE>
<FONTSIZE=2><P><BR>
</P>
<P>The operator[] member function needs further explanation: it returns a const reference to a structure of type sub_match<iterator>, which has the following public members: <BR>
<FONTSIZE=2><P>Converts the sub-expression match into an instance of std::basic_string<>. Note that this member may be either absent, or present to a more limited degree depending upon your compiler capabilities.</FONT></TD>
<TDWIDTH="5%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
</TABLE>
<FONTSIZE=2><P>Operator[] takes an integer as an argument that denotes the sub-expression for which to return information, the argument can take the following special values: <BR>
<FONTSIZE=2><P>Returns everything from the end of the match, to the end of the input string, equivalent to $' in perl. If this is a null string, then: </P>
<P>first == second </P>
<P>And </P>
<P>matched == false.</FONT></TD>
<TDWIDTH="5%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="6%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>-1</FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>Returns everything from the start of the input string (or the end of the last match if this is a grep operation), to the start of this match. Equivalent to $` in perl. If this is a null string, then: </P>
<P>first == second </P>
<P>And </P>
<P>matched == false.</FONT></TD>
<TDWIDTH="5%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="6%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>0</FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>Returns the whole of what matched, equivalent to $& in perl. The matched parameter is always true.</FONT></TD>
<TDWIDTH="5%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="6%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>0 < N < size()</FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>Returns what matched sub-expression N, if this sub-expression did not participate in the match then </P>
<P>matched == false </P>
<P>otherwise: </P>
<P>matched == true.</FONT></TD>
<TDWIDTH="5%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="6%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>N < -2 or N >= size()</FONT></TD>
<TDWIDTH="44%"VALIGN="TOP">
<FONTSIZE=2><P>Represents an out-of range non-existent sub-expression. Returns a "null" match in which </P>
<P>first == last </P>
<P>And </P>
<P>matched == false.</FONT></TD>
<TDWIDTH="5%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
</TABLE>
<FONTSIZE=2><P>Note that as well as being parameterised for an allocator, match_results<> also takes an iterator type, this allows any pair of iterators to be searched for a given regular expression, provided the iterators have at least bi-directional properties. </P>
<P>The algorithm regex _match determines whether a given regular expression matches a given sequence denoted by a pair of iterators, the algorithm is defined as follows, note that the result is true only if the expression matches the whole of the input sequence, the main use of this function is data input validation: </P>
<FONTSIZE=2><P>The library also defines the following convenience versions, which take either a const charT*, or a const std::basic_string<>& in place of a pair of iterators [note - these versions may not be available, or may be available in a more limited form, depending upon your compilers capabilities]: </P>
<FONTSIZE=2><P>An instance of match_results in which what matched will be reported. On exit if a match occurred then m[0] denotes the whole of the string that matched, m[0].first must be equal to first, m[0].second will be less than or equal to last. m[1] denotes the first subexpression m[2] the second subexpression and so on. If no match occurred then m[0].first = m[0].second = last.</FONT></TD>
<FONTSIZE=2><P>Determines the semantics used for matching, a combination of one or more </FONT><AHREF="#match_type"><FONTSIZE=2>match_flags</FONT></A><FONTSIZE=2> enumerators.</FONT></TD>
<FONTSIZE=2><P>regex_match returns false if no match occurs or true if it does. A match only occurs if it starts at <B>first</B> and finishes at <B>last</B>. Example: the following </FONT><AHREF="example/snippets/regex_match_example.cpp"><FONTSIZE=2>example</FONT></A><FONTSIZE=2> processes an ftp response: </P>
<FONTSIZE=2><P><ANAME="match_type"></A>The value of the flags parameter passed to the algorithm must be a combination of one or more of the following values: <BR>
<FONTSIZE=2><P>The default value, indicates that <B>first</B> represents the start of a line, the start of a buffer, and (possibly) the start of a word. Also implies that <B>last</B> represents the end of a line, the end of the buffer and (possibly) the end of a word. Implies that a dot sub-expression "." will match both the newline character and a null.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_bol</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then <B>first</B> does not represent the start of a new line.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_eol</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then <B>last</B> does not represent the end of a line.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_bob</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then <B>first</B> is not the beginning of a buffer.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_eob</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then <B>last</B> does not represent the end of a buffer.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_bow</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then <B>first</B> can never match the start of a word.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_eow</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then <B>last</B> can never match the end of a word.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_dot_newline</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then a dot expression "." can not match the newline character.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>match_not_dot_null</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP">
<FONTSIZE=2><P>When this flag is set then a dot expression "." can not match a null character.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE"HEIGHT=75>
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=75>
<FONTSIZE=2><P>match_prev_avail</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=75>
<FONTSIZE=2><P>When this flag is set, then *--<B>first</B> is a valid expression and the flags match_not_bol and match_not_bow have no effect, since the value of the previous character can be used to check these.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE"HEIGHT=75>
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE"HEIGHT=15>
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=15>
<FONTSIZE=2><P>match_any</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=15>
<FONTSIZE=2><P>When this flag is set, then the first string matched is returned, rather than the longest possible match. This flag can significantly reduce the time taken to find a match, but what matches is undefined.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE"HEIGHT=15>
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE"HEIGHT=15>
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=15>
<FONTSIZE=2><P>match_not_null</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=15>
<FONTSIZE=2><P>When this flag is set, then the expression will never match a null string.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE"HEIGHT=15>
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="5%"VALIGN="MIDDLE"HEIGHT=15>
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=15>
<FONTSIZE=2><P>match_continuous</FONT></TD>
<TDWIDTH="45%"VALIGN="TOP"HEIGHT=15>
<FONTSIZE=2><P>When this flags is set, then during a grep operation, each successive match must start from where the previous match finished.</FONT></TD>
<FONTSIZE=2><P>When this flag is set, the regex algorithms will report </FONT><AHREF="#partial_matches">partial matches</A><FONTSIZE=2> - that is where one or more characters at the end of the text input matched some prefix of the regular expression.</FONT></TD>
<P>The algorithm regex_search will search a range denoted by a pair of iterators for a given regular expression. The algorithm uses various heuristics to reduce the search time by only checking for a match if a match could conceivably start at that position. The algorithm is defined as follows: </P>
<FONTSIZE=2><P>The library also defines the following convenience versions, which take either a const charT*, or a const std::basic_string<>& in place of a pair of iterators [note - these versions may not be available, or may be available in a more limited form, depending upon your compilers capabilities]: </P>
<FONTSIZE=2><P>An instance of match_results in which what matched will be reported. On exit if a match occurred then m[0] denotes the whole of the string that matched, m[0].first and m[0].second will be less than or equal to last. m[1] denotes the first sub-expression m[2] the second sub-expression and so on. If no match occurred then m[0].first = m[0].second = last.</FONT></TD>
<FONTSIZE=2><P>The flags that determine what gets matched, a combination of one or more </FONT><AHREF="#match_type"><FONTSIZE=2>match_flags</FONT></A><FONTSIZE=2> enumerators.</FONT></TD>
<P>Example: the following </FONT><AHREF="example/snippets/regex_search_example.cpp"><FONTSIZE=2>example</FONT></A><FONTSIZE=2>, takes the contents of a file in the form of a string, and searches for all the C++ class declarations in the file. The code will work regardless of the way that std::string is implemented, for example it could easily be modified to work with the SGI rope class, which uses a non-contiguous storage strategy. </P>
<P> Regex_grep allows you to search through an iterator range and locate all the (non-overlapping) matches with a given regular expression. The function is declared as: </P>
<FONTSIZE=2><P>The library also defines the following convenience versions, which take either a const charT*, or a const std::basic_string<>& in place of a pair of iterators [note - these versions may not be available, or may be available in a more limited form, depending upon your compilers capabilities]: </P>
<FONTSIZE=2><P>A predicate function object or function pointer, see below for more information.</FONT></TD>
<TDWIDTH="5%"VALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>first</FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>The start of the range to search.</FONT></TD>
<TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>last</FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>The end of the range to search.</FONT></TD>
<TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>e</FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>The regular expression to search for.</FONT></TD>
<TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>flags</FONT></TD>
<TDWIDTH="50%"VALIGN="TOP">
<FONTSIZE=2><P>The flags that determine how matching is carried out, one of the </FONT><AHREF="#match_type"><FONTSIZE=2>match_flags</FONT></A><FONTSIZE=2> enumerators.</FONT></TD>
<TDVALIGN="MIDDLE">
<FONTSIZE=2><P> </FONT></TD>
</TR>
</TABLE>
<FONTSIZE=2><P> The algorithm finds all of the non-overlapping matches of the expression e, for each match it fills a </FONT><AHREF="#reg_match"><FONTSIZE=2>match_results</FONT></A><FONTSIZE=2><iterator, Allocator> structure, which contains information on what matched, and calls the predicate foo, passing the match_results<iterator, Allocator> as a single argument. If the predicate returns true, then the grep operation continues, otherwise it terminates without searching for further matches. The function returns the number of matches found.</P>
<FONTSIZE=2><P>For example the regular expression "a*b" would find one match in the string "aaaaab" and two in the string "aaabb". </P>
<P>Remember this algorithm can be used for a lot more than implementing a version of grep, the predicate can be and do anything that you want, grep utilities would output the results to the screen, another program could index a file based on a regular expression and store a set of bookmarks in a list, or a text file conversion utility would output to file. The results of one regex_grep can even be chained into another regex_grep to create recursive parsers. </P>
</FONT><P><AHREF="example/snippets/regex_grep_example_1.cpp"><FONTSIZE=2>Example</FONT></A><FONTSIZE=2>: convert the example from <I>regex_search</I> to use <I>regex_grep</I> instead: </P>
<P><AHREF="example/snippets/regex_grep_example_2.cpp"><FONTSIZE=2>Example</FONT></A><FONTSIZE=2>: Use regex_grep to call a global callback function: </P>
<P><AHREF="example/snippets/regex_grep_example_3.cpp"><FONTSIZE=2>Example</FONT></A><FONTSIZE=2>: use regex_grep to call a class member function, use the standard library adapters <I>std::mem_fun</I> and <I>std::bind1st</I> to convert the member function into a predicate: </P>
<P><AHREF="example/snippets/regex_grep_example_4.cpp"><FONTSIZE=2>Finally</FONT></A><FONTSIZE=2>, C++ Builder users can use C++ Builder's closure type as a callback argument: </P>
<P>The algorithm regex_format takes the results of a match and creates a new string based upon a </FONT><AHREF="format_string.htm#format_string"><FONTSIZE=2>format string</FONT></A><FONTSIZE=2>, regex_format can be used for search and replace operations: </P>
<B>const</B> match_results<iterator, Allocator>& m,
<B>const</B> match_results<iterator, Allocator>& m,
<FONTSIZE=2><P>The library also defines the following convenience variation of regex_format, which returns the result directly as a string, rather than outputting to an iterator [note - this version may not be available, or may be available in a more limited form, depending upon your compilers capabilities]: </P>
<FONTSIZE=2><P>Enables all syntax options (perl-like plus extentions).</FONT></TD>
<TDWIDTH="9%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="9%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="39%"VALIGN="TOP">
<FONTSIZE=2><P>format_sed</FONT></TD>
<TDWIDTH="43%"VALIGN="TOP">
<FONTSIZE=2><P>Allows only a sed-like syntax.</FONT></TD>
<TDWIDTH="9%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="9%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="39%"VALIGN="TOP">
<FONTSIZE=2><P>format_perl</FONT></TD>
<TDWIDTH="43%"VALIGN="TOP">
<FONTSIZE=2><P>Allows only a perl-like syntax.</FONT></TD>
<TDWIDTH="9%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
<TR><TDWIDTH="9%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
<TDWIDTH="39%"VALIGN="TOP">
<FONTSIZE=2><P>format_no_copy</FONT></TD>
<TDWIDTH="43%"VALIGN="TOP">
<FONTSIZE=2><P>Disables copying of unmatched sections to the output string during </FONT><AHREF="#reg_merge"><FONTSIZE=2>regex_merge</FONT></A><FONTSIZE=2> operations.</FONT></TD>
<TDWIDTH="9%"VALIGN="TOP">
<FONTSIZE=2><P> </FONT></TD>
</TR>
</TABLE>
<FONTSIZE=2><P><BR>
</P>
<P>The format string syntax (and available options) is described more fully under </FONT><AHREF="format_string.htm#format_string"><FONTSIZE=2>format strings</FONT></A><FONTSIZE=2>. </P>
<P>The algorithm regex_merge is a combination of </FONT><AHREF="#reg_grep"><FONTSIZE=2>regex_grep</FONT></A><FONTSIZE=2> and </FONT><AHREF="#reg_format"><FONTSIZE=2>regex_format</FONT></A><FONTSIZE=2>. That is, it greps through the string finding all the matches to the regular expression, for each match it then calls regex_format to format the string and sends the result to the output iterator. Sections of text that do not match are copied to the output unchanged only if the flags parameter does not have the flag </FONT><AHREF="#format_flags"><FONTSIZE=2>format_no_copy</FONT></A><FONTSIZE=2> set. </P>
iterator last,
iterator last,
<FONTSIZE=2><P>The library also defines the following convenience variation of regex_merge, which returns the result directly as a string, rather than outputting to an iterator [note - this version may not be available, or may be available in a more limited form, depending upon your compilers capabilities]: </P>
<FONTSIZE=2><P>Flags which determine how the expression is matched - see </FONT><AHREF="#match_type"><FONTSIZE=2>match_flags</FONT></A><FONTSIZE=2>, and how the format string is interpreted - see </FONT><AHREF="#format_flags"><FONTSIZE=2>format_flags</FONT></A><FONTSIZE=2>.</FONT></TD>
<FONTSIZE=2><P>Example: the following </FONT><AHREF="example/snippets/regex_merge_example.cpp"><FONTSIZE=2>example</FONT></A><FONTSIZE=2> takes C/C++ source code as input, and outputs syntax highlighted HTML code. </P>
<FONTSIZE=2><P>Each version takes an output-iterator for output, and a string for input. If the expression contains no marked sub-expressions, then the algorithm writes one string onto the output-iterator for each section of input that does not match the expression. If the expression does contain marked sub-expressions, then each time a match is found, one string for each marked sub-expression will be written to the output-iterator. No more than <I>max_split </I>strings will be written to the output-iterator. Before returning, all the input processed will be deleted from the string <I>s</I> (if <I>max_split </I>is not reached then all of <I>s</I> will be deleted). Returns the number of strings written to the output-iterator. If the parameter <I>max_split</I> is not specified then it defaults to UINT_MAX. If no expression is specified, then it defaults to "\s+", and splitting occurs on whitespace. </P>
</FONT><P><AHREF="example/snippets/regex_split_example_1.cpp"><FONTSIZE=2>Example</FONT></A><FONTSIZE=2>: the following function will split the input string into a series of tokens, and remove each token from the string <I>s</I>: </P>
<P><AHREF="example/snippets/regex_split_example_2.cpp"><FONTSIZE=2>Example</FONT></A><FONTSIZE=2>: the following short program will extract all of the URL's from a html file, and print them out to <I>cout</I>: </P>
<P>The match-flag <CODE>match_partial</CODE> can be passed to the following algorithms: <AHREF="#reg_match">regex_match</A>, <AHREF="#reg_search">regex_search</A>, and <AHREF="#reg_grep">regex_grep</A>. When used it indicates that partial as well as full matches should be found. A partial match is one that matched one or more characters at the end of the text input, but did not match all of the regular expression (although it may have done so had more input been available). Partial matches are typically used when either validating data input (checking each character as it is entered on the keyboard), or when searching texts that are either too long to load into memory (or even into a memory mapped file), or are of indeterminate length (for example the source may be a socket or similar). Partial and full matches can be differentiated as shown in the following table (the variable M represents an instance of match_results<> as filled in by regex_match, regex_search or regex_grep):<BR>
<P>The following <AHREF="example/snippets/partial_regex_match.cpp">example</A> tests to see whether the text could be a valid credit card number, as the user presses a key, the character entered would be added to the string being built up, and passed to <CODE>is_possible_card_number</CODE>. If this returns true then the text could be a valid card number, so the user interface's OK button would be enabled. If it returns false, then this is not yet a valid card number, but could be with more input, so the user interface would disable the OK button. Finally, if the procedure throws an exception the input could never become a valid number, and the inputted character must be discarded, and a suitable error indication displayed to the user.</P>
<P>In the following <AHREF="example/snippets/partial_regex_match.cpp">example</A>, text input is taken from a stream containing an unknown amount of text; this example simply counts the number of html tags encountered in the stream. The text is loaded into a buffer and searched a part at a time, if a partial match was encountered, then the partial match gets searched a second time as the start of the next batch of text:</P>
<I><P>Copyright </I></FONT><AHREF="mailto:John_Maddock@compuserve.com"><I><FONTSIZE=2>Dr John Maddock</I></FONT></A><I><FONTSIZE=2> 1998-2001 all rights reserved.</I></P></FONT></BODY>
