| Home | Libraries | People | FAQ | More

#### 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 syntax.

    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:

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(const char* 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 occurrence of the pattern found is replaced. Returns the new string. See also 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 occurrence of the pattern found is replaced. Returns the new string. See also 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.