Boost.Regex

class RegEx (deprecated)

The high level wrapper class RegEx is now deprecated and does not form a 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:

	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 flags. 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 flags flags - see match 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 format string syntax, match flags and format flags.
	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 format string syntax, match flags and format flags.
	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.

Revised 04 Feb 2004

Use, modification and distribution are subject to 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)