[/ 
  Copyright 2006-2007 John Maddock.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]


[section:old_regex High Level Class RegEx (Deprecated)]

The high level wrapper class RegEx is now deprecated and does not form 
part of the regular expression standardization proposal.  This type still 
exists, and existing code will continue to compile, however the following 
documentation is unlikely to be further updated.

   #include <boost/cregex.hpp>

The class RegEx provides a high level simplified interface to the regular 
expression library, this class only handles narrow character strings, and 
regular expressions always follow the "normal" syntax - that is the 
same as the perl / ECMAScript synatx.

   typedef bool (*GrepCallback)(const RegEx& expression);
   typedef bool (*GrepFileCallback)(const char* file, const RegEx& expression);
   typedef bool (*FindFilesCallback)(const char* file);

   class  RegEx
   {
   public:
      RegEx();
      RegEx(const RegEx& o);
      ~RegEx();
      RegEx(const char* c, bool icase = false);
      explicit RegEx(const std::string& s, bool icase = false);
      RegEx& operator=(const RegEx& o);
      RegEx& operator=(const char* p);
      RegEx& operator=(const std::string& s);
      unsigned int SetExpression(const char* p, bool icase = false);
      unsigned int SetExpression(const std::string& s, bool icase = false);
      std::string Expression()const;
      //
      // now matching operators: 
      // 
      bool Match(const char* p, boost::match_flag_type flags = match_default);
      bool Match(const std::string& s, boost::match_flag_type flags = match_default); 
      bool Search(const char* p, boost::match_flag_type flags = match_default); 
      bool Search(const std::string& s, boost::match_flag_type flags = match_default); 
      unsigned int Grep(GrepCallback cb, const char* p, 
                        boost::match_flag_type flags = match_default); 
      unsigned int Grep(GrepCallback cb, const std::string& s, 
                        boost::match_flag_type flags = match_default); 
      unsigned int Grep(std::vector<std::string>& v, const char* p, 
                        boost::match_flag_type flags = match_default); 
      unsigned int Grep(std::vector<std::string>& v, const std::string& s, 
                        boost::match_flag_type flags = match_default); 
      unsigned int Grep(std::vector<unsigned int>& v, const char* p, 
                        boost::match_flag_type flags = match_default); 
      unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, 
                        boost::match_flag_type flags = match_default); 
      unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, 
                             boost::match_flag_type flags = match_default); 
      unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, 
                             bool recurse = false, 
                             boost::match_flag_type flags = match_default); 
      unsigned int FindFiles(FindFilesCallback cb, const char* files, 
                             bool recurse = false, 
                             boost::match_flag_type flags = match_default); 
      unsigned int FindFiles(FindFilesCallback cb, const std::string& files, 
                             bool recurse = false, 
                             boost::match_flag_type flags = match_default); 
      std::string Merge(const std::string& in, const std::string& fmt, 
                        bool copy = true, boost::match_flag_type flags = match_default); 
      std::string Merge(const char* in, const char* fmt, bool copy = true, 
                        boost::match_flag_type flags = match_default); 
      unsigned Split(std::vector<std::string>& v, std::string& s, 
                     boost::match_flag_type flags = match_default, 
                     unsigned max_count = ~0); 
      // 
      // now operators for returning what matched in more detail: 
      // 
      unsigned int Position(int i = 0)const; 
      unsigned int Length(int i = 0)const; 
      bool Matched(int i = 0)const;
      unsigned int Line()const; 
      unsigned int Marks() const; 
      std::string What(int i)const; 
      std::string operator[](int i)const ; 

      static const unsigned int npos;
   };    

Member functions for class RegEx are defined as follows:
 
[table
[[Member][Description]]
[[`RegEx();`][Default constructor, constructs an instance of RegEx without any valid expression. 	 ]]
[[`RegEx(const RegEx& o);`][Copy constructor, all the properties of parameter /o/ 
         are copied. 	 ]]
[[`RegEx(const char* c, bool icase = false);`][Constructs an instance of RegEx, 
         setting the expression to /c/, if /icase/ is true then matching is 
         insensitive to case, otherwise it is sensitive to case. Throws 
         [bad_expression] on failure. 	 ]]
[[`RegEx(const std::string& s, bool icase = false);`][Constructs an instance of 
         RegEx, setting the expression to /s/, if /icase/ is true then matching 
         is insensitive to case, otherwise it is sensitive to case. Throws 
         [bad_expression] on failure. 	 ]]
[[`RegEx& operator=(const RegEx& o);`][Default assignment operator. 	 ]]
[[`RegEx& operator=(const char* p);`][Assignment operator, equivalent to calling 
         `SetExpression(p, false)`. Throws [bad_expression] on failure. 	 ]]
[[`RegEx& operator=(const std::string& s);`][Assignment operator, equivalent to 
         calling `SetExpression(s, false)`. Throws [bad_expression] on failure. 	 ]]
[[`unsigned int SetExpression(constchar* p, bool icase = false);`][Sets the 
         current expression to /p/, if /icase/ is true then matching is 
         insensitive to case, otherwise it is sensitive to case. 
         Throws [bad_expression] on failure. 	 ]]
[[`unsigned int SetExpression(const std::string& s, bool icase = false);`]
         [Sets the current expression to /s/, if /icase/ is true then matching is 
         insensitive to case, otherwise it is sensitive to case. Throws 
         [bad_expression] on failure. 	 ]]
[[`std::string Expression()const;`][Returns a copy of the current regular expression. 	 ]]
[[`bool Match(const char* p, boost::match_flag_type flags = match_default);`]
         [Attempts to match the current expression against the text /p/ using 
         the match flags /flags/ - see [match_flag_type]. Returns /true/ if the 
         expression matches the whole of the input string. 	 ]]
[[`bool Match(const std::string& s, boost::match_flag_type flags = match_default);`]
         [Attempts to match the current expression against the text /s/ using 
         the [match_flag_type] /flags/. Returns /true/ if the expression matches 
         the whole of the input string. 	 ]]
[[`bool Search(const char* p, boost::match_flag_type flags = match_default);`]
         [Attempts to find a match for the current expression somewhere in 
         the text /p/ using the [match_flag_type] /flags/. Returns /true/ 
         if the match succeeds. 	 ]]
[[`bool Search(const std::string& s, boost::match_flag_type flags = match_default);`]
         [Attempts to find a match for the current expression somewhere in the 
         text /s/ using the [match_flag_type] flags. Returns /true/ if the 
         match succeeds. 	 ]]
[[`unsigned int Grep(GrepCallback cb, const char* p, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the text /p/ using the 
         [match_flag_type] /flags/. For each match found calls the call-back 
         function cb as: `cb(*this);`
         If at any stage the call-back function returns /false/ then the grep 
         operation terminates, otherwise continues until no further matches 
         are found. Returns the number of matches found.]]
[[`unsigned int Grep(GrepCallback cb, const std::string& s, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the text /s/ using the 
         [match_flag_type] flags. For each match found calls the call-back 
         function cb as: `cb(*this);`
         If at any stage the call-back function returns false then the grep operation 
         terminates, otherwise continues until no further matches are found. 
         Returns the number of matches found.]]
[[`unsigned int Grep(std::vector<std::string>& v, const char* p, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the text /p/ using the 
         [match_flag_type] flags. For each match pushes a copy of what matched 
         onto /v/. Returns the number of matches found. 	 ]]
[[`unsigned int Grep(std::vector<std::string>& v, const std::string& s, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the text /s/ using the 
         [match_flag_type] /flags/. For each match pushes a copy of what 
         matched onto /v/. Returns the number of matches found. 	 ]]
[[`unsigned int Grep(std::vector<unsigned int>& v, const char* p, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the text /p/ using the 
         [match_flag_type] /flags/. For each match pushes the starting index of 
         what matched onto /v/. Returns the number of matches found. 	 ]]
[[`unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the text /s/ using the 
         [match_flag_type] /flags/. For each match pushes the starting index of what 
         matched onto /v/. Returns the number of matches found. 	 ]]
[[`unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the files files using 
         the [match_flag_type] /flags/. For each match calls the call-back function cb. 
         If the call-back returns false then the algorithm returns without 
         considering further matches in the current file, or any further files. 
         
         The parameter /files/ can include wild card characters '\*' and '\?', if 
         the parameter recurse is true then searches sub-directories for matching 
         file names. 

         Returns the total number of matches found.

         May throw an exception derived from `std::runtime_error` if file io fails.]]
[[`unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`]
         [Finds all matches of the current expression in the files files using the 
         [match_flag_type] /flags/. For each match calls the call-back function cb. 

         If the call-back returns false then the algorithm returns without 
         considering further matches in the current file, or any further files. 

         The parameter /files/ can include wild card characters '\*' and '\?', if 
         the parameter recurse is true then searches sub-directories for 
         matching file names. 

         Returns the total number of matches found.

         May throw an exception derived from `std::runtime_error` if file io fails.]]
	 
[[`unsigned int FindFiles(FindFilesCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`]
         [Searches files to find all those which contain at least one match of 
         the current expression using the [match_flag_type] /flags/. For each 
         matching file calls the call-back function cb. 
         If the call-back returns false then the algorithm returns without 
         considering any further files. 

         The parameter /files/ can include wild card characters '\*' and '\?', if 
         the parameter /recurse/ is true then searches sub-directories for 
         matching file names. 

         Returns the total number of files found.

         May throw an exception derived from `std::runtime_error` if file io fails.]]
[[`unsigned int FindFiles(FindFilesCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`]
         [Searches files to find all those which contain at least one 
         match of the current expression using the [match_flag_type] /flags/. 
         For each matching file calls the call-back function cb. 

         If the call-back returns false then the algorithm returns without 
         considering any further files. 

         The parameter /files/ can include wild card characters '\*' and '\?', if 
         the parameter /recurse/ is true then searches sub-directories for 
         matching file names. 

         Returns the total number of files found.

         May throw an exception derived from `std::runtime_error` if file io fails.]]
         
[[`std::string Merge(const std::string& in, const std::string& fmt, bool copy = true, boost::match_flag_type flags = match_default);`]
         [Performs a search and replace operation: searches through the 
         string /in/ for all occurrences of the current expression, for each 
         occurrence replaces the match with the format string /fmt/. Uses /flags/ 
         to determine what gets matched, and how the format string should be 
         treated. If /copy/ is true then all unmatched sections of input are 
         copied unchanged to output, if the flag /format_first_only/ is set then 
         only the first occurance of the pattern found is replaced. 
         Returns the new string. See also 
         [link boost_regex.format format string syntax], and [match_flag_type].]]
[[`std::string Merge(const char* in, const char* fmt, bool copy = true, boost::match_flag_type flags = match_default);`]
         [Performs a search and replace operation: searches through the string /in/ 
         for all occurrences of the current expression, for each occurrence 
         replaces the match with the format string /fmt/. Uses /flags/ to determine 
         what gets matched, and how the format string should be treated. 
         If /copy/ is true then all unmatched sections of input are copied 
         unchanged to output, if the flag /format_first_only/ is set then only 
         the first occurance of the pattern found is replaced. Returns 
         the new string. See also [link boost_regex.format format string syntax], and [match_flag_type].]]
[[`unsigned Split(std::vector<std::string>& v, std::string& s, boost::match_flag_type flags = match_default, unsigned max_count = ~0);`]
         [Splits the input string and pushes each one onto the vector. 
         If the expression contains no marked sub-expressions, then one 
         string is outputted for each section of the input that does not 
         match the expression. If the expression does contain marked 
         sub-expressions, then outputs one string for each marked 
         sub-expression each time a match occurs. Outputs no more than 
         /max_count/ strings. Before returning, deletes from the input string 
         /s/ all of the input that has been processed (all of the string if 
         /max_count/ was not reached). Returns the number of strings pushed 
         onto the vector. 	 ]]
[[`unsigned int Position(int i = 0)const;`]
         [Returns the position of what matched sub-expression /i/. If `i = 0` 
         then returns the position of the whole match. Returns `RegEx::npos` if 
         the supplied index is invalid, or if the specified sub-expression 
         did not participate in the match. 	 ]]
[[`unsigned int Length(int i = 0)const;`]
         [Returns the length of what matched sub-expression i. If `i = 0` then 
         returns the length of the whole match. Returns `RegEx::npos` if the 
         supplied index is invalid, or if the specified sub-expression did not 
         participate in the match. 	 ]]
[[`bool Matched(int i = 0)const;`]
         [Returns true if sub-expression /i/ was matched, false otherwise. 	 ]]
[[`unsigned int Line()const;`][Returns the line on which the match occurred, 
         indexes start from 1 not zero, if no match occurred then returns `RegEx::npos`. 	 ]]
[[`unsigned int Marks() const;`][Returns the number of marked sub-expressions 
         contained in the expression. Note that this includes the whole 
         match (sub-expression zero), so the value returned is always >= 1. 	 ]]
[[`std::string What(int i)const;`]
         [Returns a copy of what matched sub-expression /i/. If `i = 0` then 
         returns a copy of the whole match. Returns a null string if the 
         index is invalid or if the specified sub-expression did not 
         participate in a match. 	 ]]
[[`std::string operator[](int i)const ;`][Returns `what(i);`
         Can be used to simplify access to sub-expression matches, and make 
         usage more perl-like.]]
]

[endsect]