class regbase

#include <boost/regex.hpp>

Class regbase is the template argument independent base class for reg_expression, the only public members are the flag_type enumerated values that determine how regular expressions are interpreted.

class regbase
{
public:
   enum flag_type_
   {
      escape_in_lists = 1,                          // '\\' special inside [...] 
      char_classes = escape_in_lists << 1,          // [[:CLASS:]] allowed 
      intervals = char_classes << 1,                // {x,y} allowed 
      limited_ops = intervals << 1,                 // all of + ? and | are normal characters 
      newline_alt = limited_ops << 1,               // \n is the same as | 
      bk_plus_qm = newline_alt << 1,                // uses \+ and \? 
      bk_braces = bk_plus_qm << 1,                  // uses \{ and \} 
      bk_parens = bk_braces << 1,                   // uses \( and \) 
      bk_refs = bk_parens << 1,                     // \d allowed 
      bk_vbar = bk_refs << 1,                       // uses \| 
      use_except = bk_vbar << 1,                    // exception on error 
      failbit = use_except << 1,                    // error flag 
      literal = failbit << 1,                       // all characters are literals 
      icase = literal << 1,                         // characters are matched regardless of case 
      nocollate = icase << 1,                       // don't use locale specific collation 

      basic = char_classes | intervals | limited_ops | bk_braces | bk_parens | bk_refs,
      extended = char_classes | intervals | bk_refs,
      normal = escape_in_lists | char_classes | intervals | bk_refs | nocollate,
      emacs = bk_braces | bk_parens | bk_refs | bk_vbar,
      awk = extended | escape_in_lists,
      grep = basic | newline_alt,
      egrep = extended | newline_alt,
      sed = basic,
      perl = normal
   }; 
   typedef unsigned int flag_type;
};   

The enumerated type regbase::flag_type determines the syntax rules for regular expression compilation, the various flags have the following effects:
 

Exception classes.

#include <boost/pat_except.hpp>

An instance of bad_expression is thrown whenever a bad regular expression is encountered.

namespace boost{

class bad_pattern : public std::runtime_error
{
public:
   explicit bad_pattern(const std::string& s) : std::runtime_error(s){};
};

class bad_expression : public bad_pattern
{
public:
   bad_expression(const std::string& s) : bad_pattern(s) {}
};


} // namespace boost

Footnotes: the class bad_pattern forms the base class for all pattern-matching exceptions, of which bad_expression is one. The choice of std::runtime_error as the base class for bad_pattern 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).

Class reg_expression

#include <boost/regex.hpp>

The template class reg_expression encapsulates regular expression parsing and compilation. The class derives from class regbase and takes three template parameters:

charT: determines the character type, i.e. either char or wchar_t.

traits: 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: regex_traits<charT>.

Allocator: the allocator class used to allocate memory by the class.

For ease of use there are two typedefs that define the two standard reg_expression instances, unless you want to use custom allocators, you won't need to use anything other than these:

namespace boost{
template <class charT, class traits = regex_traits<charT>, class Allocator = std::allocator<charT>  >
class reg_expression;
typedef reg_expression<char> regex;
typedef reg_expression<wchar_t> wregex;
}

The definition of reg_expression follows: it is based very closely on class basic_string, and fulfils the requirements for a container of charT.

namespace boost{
template <class charT, class traits = regex_traits<charT>, class Allocator = std::allocator<charT>  >
class reg_expression : public regbase
{
public: 
   // typedefs:  
   typedef charT char_type; 
   typedef traits traits_type; 
   // locale_type 
   // placeholder for actual locale type used by the 
   // traits class to localise *this. 
   typedef typename traits::locale_type locale_type; 
   // value_type 
   typedef charT value_type; 
   // reference, const_reference 
   typedef charT& reference; 
   typedef const charT& const_reference; 
   // iterator, const_iterator 
   typedef const charT* const_iterator; 
   typedef const_iterator iterator; 
   // difference_type 
   typedef typename Allocator::difference_type difference_type; 
   // size_type 
   typedef typename Allocator::size_type size_type; 
   // allocator_type 
   typedef Allocator allocator_type; 
   typedef Allocator alloc_type; 
   // flag_type 
   typedef boost::int_fast32_t flag_type; 
public: 
   // constructors 
   explicit reg_expression(const Allocator& a = Allocator()); 
   explicit reg_expression(const charT* p, flag_type f = regbase::normal, const Allocator& a = Allocator()); 
   reg_expression(const charT* p1, const charT* p2, flag_type f = regbase::normal, const Allocator& a = Allocator()); 
   reg_expression(const charT* p, size_type len, flag_type f, const Allocator& a = Allocator()); 
   reg_expression(const reg_expression&); 
   template <class ST, class SA> 
   explicit reg_expression(const std::basic_string<charT, ST, SA>& p, flag_type f = regbase::normal, const Allocator& a = Allocator()); 
   template <class I> 
   reg_expression(I first, I last, flag_type f = regbase::normal, const Allocator& a = Allocator()); 
   ~reg_expression(); 
   reg_expression& operator=(const reg_expression&); 
   reg_expression& operator=(const charT* ptr); 
   template <class ST, class SA> 
   reg_expression& operator=(const std::basic_string<charT, ST, SA>& p); 
   // 
   // assign: 
   reg_expression& assign(const reg_expression& that); 
   reg_expression& assign(const charT* ptr, flag_type f = regbase::normal); 
   reg_expression& assign(const charT* first, const charT* last, flag_type f = regbase::normal); 
   template <class string_traits, class A> 
   reg_expression& assign( 
       const std::basic_string<charT, string_traits, A>& s, 
       flag_type f = regbase::normal); 
   template <class iterator> 
   reg_expression& assign(iterator first, 
                          iterator last, 
                          flag_type f = regbase::normal); 
   // 
   // allocator access: 
   Allocator get_allocator()const; 
   // 
   // locale: 
   locale_type imbue(locale_type l); 
   locale_type getloc()const; 
   // 
   // flags: 
   flag_type getflags()const; 
   // 
   // str: 
   std::basic_string<charT> str()const; 
   // 
   // begin, end: 
   const_iterator begin()const; 
   const_iterator end()const; 
   // 
   // swap: 
   void swap(reg_expression&)throw(); 
   // 
   // size: 
   size_type size()const; 
   // 
   // max_size: 
   size_type max_size()const; 
   // 
   // empty: 
   bool empty()const; 
   unsigned mark_count()const; 
   bool operator==(const reg_expression&)const; 
   bool operator<(const reg_expression&)const; 
};
} // namespace boost 

Class reg_expression has the following public member functions:
 

Class regex_traits

#include <boost/regex/regex_traits.hpp>

This is a preliminary version of the regular expression traits class, and is subject to change.

The purpose of the traits class is to make it easier to customise the behaviour of reg_expression 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 regex_traits, which inherits from one of these depending upon the default localisation model in use, class c_regex_traits encapsulates the global C locale, class w32_regex_traits encapsulates the global Win32 locale (only available on Win32 systems), and class cpp_regex_traits encapsulates the C++ locale (only provided if std::locale is supported):

template <class charT> class c_regex_traits;
template<> class c_regex_traits<char> { /*details*/ };
template<> class c_regex_traits<wchar_t> { /*details*/ };

template <class charT> class w32_regex_traits;
template<> class w32_regex_traits<char> { /*details*/ };
template<> class w32_regex_traits<wchar_t> { /*details*/ };

template <class charT> class cpp_regex_traits;
template<> class cpp_regex_traits<char> { /*details*/ };
template<> class cpp_regex_traits<wchar_t> { /*details*/ };

template <class charT> class regex_traits : public base_type { /*detailts*/ };

Where "base_type" defaults to w32_regex_traits on Win32 systems, and c_regex_traits otherwise. The default behaviour can be changed by defining one of BOOST_REGEX_USE_C_LOCALE (forces use of c_regex_traits by default), or BOOST_REGEX_USE_CPP_LOCALE (forces use of cpp_regex_traits by default). Alternatively a specific traits class can be passed to the reg_expression template.

The requirements for custom traits classes are documented separately here....

There is also an example of a custom traits class supplied by Christian Engström, see iso8859_1_regex_traits.cpp and iso8859_1_regex_traits.hpp, see the readme file for more details.

Class match_results

#include <boost/regex.hpp>

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 match_results that acts as an indexed collection of sub-expression matches, each sub-expression match being contained in an object of type sub_match.

// 
// class sub_match: 
// denotes one sub-expression match. 
//         
template <class iterator>
struct sub_match
{
   typedef typename std::iterator_traits<iterator>::value_type       value_type;
   typedef typename std::iterator_traits<iterator>::difference_type  difference_type;
   typedef iterator                                                  iterator_type;
   
   iterator first;
   iterator second;
   bool matched;

   operator std::basic_string<value_type>()const;

   bool operator==(const sub_match& that)const;
   bool operator !=(const sub_match& that)const;
   difference_type length()const;
};

// 
// class match_results: 
// contains an indexed collection of matched sub-expressions. 
// 
template <class iterator, class Allocator = std::allocator<typename std::iterator_traits<iterator>::value_type > > 
class match_results 
{ 
public: 
   typedef Allocator                                                 alloc_type; 
   typedef typename Allocator::template Rebind<iterator>::size_type  size_type; 
   typedef typename std::iterator_traits<iterator>::value_type       char_type; 
   typedef sub_match<iterator>                                       value_type; 
   typedef typename std::iterator_traits<iterator>::difference_type  difference_type; 
   typedef iterator                                                  iterator_type; 
   explicit match_results(const Allocator& a = Allocator()); 
   match_results(const match_results& m); 
   match_results& operator=(const match_results& m); 
   ~match_results(); 
   size_type size()const; 
   const sub_match<iterator>& operator[](int n) const; 
   Allocator allocator()const; 
   difference_type length(int sub = 0)const; 
   difference_type position(unsigned int sub = 0)const; 
   unsigned int line()const; 
   iterator line_start()const; 
   std::basic_string<char_type> str(int sub = 0)const; 
   void swap(match_results& that); 
   bool operator==(const match_results& that)const; 
   bool operator<(const match_results& that)const; 
};
typedef match_results<const char*> cmatch;
typedef match_results<const wchar_t*> wcmatch; 
typedef match_results<std::string::const_iterator> smatch;
typedef match_results<std::wstring::const_iterator> wsmatch; 

Class match_results is used for reporting what matched a regular expression, it is passed to the matching algorithms regex_match and regex_search, and is used by regex_grep 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:
 

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:
 

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:
 

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.

Algorithm regex_match

#include <boost/regex.hpp>

The algorithm regex _match determines whether a given regular expression matches a given sequence denoted by a pair of bidirectional-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:

template <class iterator, class Allocator, class charT, class traits, class Allocator2>
bool regex_match(iterator first, 
                 iterator last, 
                 match_results<iterator, Allocator>& m, 
                 const reg_expression<charT, traits, Allocator2>& e, 
                 unsigned flags = match_default);

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]:

template <class charT, class Allocator, class traits, class Allocator2>
bool regex_match(const charT* str, 
                 match_results<const charT*, Allocator>& m, 
                 const reg_expression<charT, traits, Allocator2>& e, 
                 unsigned flags = match_default)

template <class ST, class SA, class Allocator, class charT, class traits, class Allocator2>
bool regex_match(const std::basic_string<charT, ST, SA>& s, 
                 match_results<typename std::basic_string<charT, ST, SA>::const_iterator, Allocator>& m, 
                 const reg_expression<charT, traits, Allocator2>& e, 
                 unsigned flags = match_default);

Finally there is a set of convenience versions that simply return true or false and do not indicate what matched:

template <class iterator, class Allocator, class charT, class traits, class Allocator2>
bool regex_match(iterator first, 
                 iterator last, 
                 const reg_expression<charT, traits, Allocator2>& e, 
                 unsigned flags = match_default);

template <class charT, class Allocator, class traits, class Allocator2>
bool regex_match(const charT* str, 
                 const reg_expression<charT, traits, Allocator2>& e, 
                 unsigned flags = match_default)

template <class ST, class SA, class Allocator, class charT, class traits, class Allocator2>
bool regex_match(const std::basic_string<charT, ST, SA>& s, 
                 const reg_expression<charT, traits, Allocator2>& e, 
                 unsigned flags = match_default);

The parameters for the main function version are as follows:
 

regex_match returns false if no match occurs or true if it does. A match only occurs if it starts at first and finishes at last. Example: the following example processes an ftp response:

#include <stdlib.h> 
#include <boost/regex.hpp> 
#include <string> 
#include <iostream> 

using namespace boost; 

regex expression("([0-9]+)(\\-| |$)(.*)"); 

// process_ftp: 
// on success returns the ftp response code, and fills 
// msg with the ftp response message. 
int process_ftp(const char* response, std::string* msg) 
{ 
   cmatch what; 
   if(regex_match(response, what, expression)) 
   { 
      // what[0] contains the whole string 
      // what[1] contains the response code 
      // what[2] contains the separator character 
      // what[3] contains the text message. 
      if(msg) 
         msg->assign(what[3].first, what[3].second); 
      return std::atoi(what[1].first); 
   } 
   // failure did not match 
   if(msg) 
      msg->erase(); 
   return -1; 
}

The value of the flags parameter passed to the algorithm must be a combination of one or more of the following values:
 

Algorithm regex_search

 #include <boost/regex.hpp>

The algorithm regex_search will search a range denoted by a pair of bidirectional-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:

template <class iterator, class Allocator, class charT, class traits, class Allocator2>
bool regex_search(iterator first, 
                iterator last, 
                match_results<iterator, Allocator>& m, 
                const reg_expression<charT, traits, Allocator2>& e, 
                unsigned flags = match_default);

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]:

template <class charT, class Allocator, class traits, class Allocator2>
bool regex_search(const charT* str, 
                match_results<const charT*, Allocator>& m, 
                const reg_expression<charT, traits, Allocator2>& e, 
                unsigned flags = match_default);

template <class ST, class SA, class Allocator, class charT, class traits, class Allocator2>
bool regex_search(const std::basic_string<charT, ST, SA>& s, 
                match_results<typename std::basic_string<charT, ST, SA>::const_iterator, Allocator>& m, 
                const reg_expression<charT, traits, Allocator2>& e, 
                unsigned flags = match_default);

The parameters for the main function version are as follows:
 

Example: the following example, 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.

#include <string> 
#include <map> 
#include <boost/regex.hpp> 

// purpose: 
// takes the contents of a file in the form of a string 
// and searches for all the C++ class definitions, storing 
// their locations in a map of strings/int's 
typedef std::map<std::string, int, std::less<std::string> > map_type; 

boost::regex expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?(\\{|:[^;\\{()]*\\{)"); 

void IndexClasses(map_type& m, const std::string& file) 
{ 
   std::string::const_iterator start, end; 
   start = file.begin(); 
   end = file.end(); 
      boost::match_results<std::string::const_iterator> what; 
   unsigned int flags = boost::match_default; 
   while(regex_search(start, end, what, expression, flags)) 
   { 
      // what[0] contains the whole string 
      // what[5] contains the class name. 
      // what[6] contains the template specialisation if any. 
      // add class name and position to map: 
      m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] = 
                what[5].first - file.begin(); 
      // update search position: 
      start = what[0].second; 
      // update flags: 
      flags |= boost::match_prev_avail; 
      flags |= boost::match_not_bob; 
   } 
}
 

Algorithm regex_grep

#include <boost/regex.hpp>

 Regex_grep allows you to search through a bidirectional-iterator range and locate all the (non-overlapping) matches with a given regular expression. The function is declared as:

template <class Predicate, class iterator, class charT, class traits, class Allocator>
unsigned int regex_grep(Predicate foo, 
                        iterator first, 
                        iterator last, 
                        const reg_expression<charT, traits, Allocator>& e, 
                        unsigned flags = match_default)

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]:

template <class Predicate, class charT, class Allocator, class traits>
unsigned int regex_grep(Predicate foo, 
              const charT* str, 
              const reg_expression<charT, traits, Allocator>& e, 
              unsigned flags = match_default);

template <class Predicate, class ST, class SA, class Allocator, class charT, class traits>
unsigned int regex_grep(Predicate foo, 
              const std::basic_string<charT, ST, SA>& s, 
              const reg_expression<charT, traits, Allocator>& e, 
              unsigned flags = match_default);

The parameters for the primary version of regex_grep have the following meanings:
 

 The algorithm finds all of the non-overlapping matches of the expression e, for each match it fills a match_results<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.

The general form of the predicate is:

struct grep_predicate
{
   bool operator()(const match_results<iterator_type, expression_type::alloc_type>& m);
};

For example the regular expression "a*b" would find one match in the string "aaaaab" and two in the string "aaabb".

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.

Example: convert the example from regex_search to use regex_grep instead:

#include <string> 
#include <map> 
#include <boost/regex.hpp> 

// IndexClasses: 
// takes the contents of a file in the form of a string 
// and searches for all the C++ class definitions, storing 
// their locations in a map of strings/int's 

typedef std::map<std::string, int, std::less<std::string> > map_type; 

boost::regex expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?" 
                 "(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?[[:space:]]*)*(\\<\\w*\\>)" 
                 "[[:space:]]*(<[^;:{]+>[[:space:]]*)?(\\{|:[^;\\{()]*\\{)"); 

class IndexClassesPred 
{ 
   map_type& m; 
   std::string::const_iterator base; 
public: 
   IndexClassesPred(map_type& a, std::string::const_iterator b) : m(a), base(b) {} 
   bool operator()(const match_results<std::string::const_iterator, regex::alloc_type>& what) 
   { 
      // what[0] contains the whole string 
      // what[5] contains the class name. 
      // what[6] contains the template specialisation if any. 
      // add class name and position to map: 
      m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] = 
                what[5].first - base; 
      return true; 
   } 
}; 

void IndexClasses(map_type& m, const std::string& file) 
{ 
   std::string::const_iterator start, end; 
   start = file.begin(); 
   end = file.end(); 
   regex_grep(IndexClassesPred(m, start), start, end, expression); 
} 

Example: Use regex_grep to call a global callback function:

#include <string> 
#include <map> 
#include <boost/regex.hpp> 

// purpose: 
// takes the contents of a file in the form of a string 
// and searches for all the C++ class definitions, storing 
// their locations in a map of strings/int's 

typedef std::map<std::string, int, std::less<std::string> > map_type; 

boost::regex expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?(\\{|:[^;\\{()]*\\{)"); 

map_type class_index; 
std::string::const_iterator base; 

bool grep_callback(const boost::match_results<std::string::const_iterator, boost::regex::alloc_type>& what) 
{ 
   // what[0] contains the whole string 
   // what[5] contains the class name. 
   // what[6] contains the template specialisation if any. 
   // add class name and position to map: 
   class_index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] = 
                what[5].first - base; 
   return true; 
} 

void IndexClasses(const std::string& file) 
{ 
   std::string::const_iterator start, end; 
   start = file.begin(); 
   end = file.end(); 
   base = start; 
   regex_grep(grep_callback, start, end, expression, match_default); 
}
  

Example: use regex_grep to call a class member function, use the standard library adapters std::mem_fun and std::bind1st to convert the member function into a predicate:

#include <string> 
#include <map> 
#include <boost/regex.hpp> 
#include <functional> 

// purpose: 
// takes the contents of a file in the form of a string 
// and searches for all the C++ class definitions, storing 
// their locations in a map of strings/int's 

typedef std::map<std::string, int, std::less<std::string> > map_type; 

class class_index 
{ 
   boost::regex expression; 
   map_type index; 
   std::string::const_iterator base; 
   bool grep_callback(boost::match_results<std::string::const_iterator, boost::regex::alloc_type> what); 
public: 
   void IndexClasses(const std::string& file); 
   class_index() 
      : index(), 
        expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?" 
                   "(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?" 
                   "[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?" 
                   "(\\{|:[^;\\{()]*\\{)" 
                   ){} 
}; 

bool class_index::grep_callback(boost::match_results<std::string::const_iterator, boost::regex::alloc_type> what) 
{ 
   // what[0] contains the whole string 
   // what[5] contains the class name. 
   // what[6] contains the template specialisation if any. 
   // add class name and position to map: 
   index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] = 
               what[5].first - base; 
   return true; 
} 

void class_index::IndexClasses(const std::string& file) 
{ 
   std::string::const_iterator start, end; 
   start = file.begin(); 
   end = file.end(); 
   base = start; 
   regex_grep(std::bind1st(std::mem_fun(&class_index::grep_callback), this), 
              start, 
              end, 
              expression); 
} 
  

Finally, C++ Builder users can use C++ Builder's closure type as a callback argument:

#include <string> 
#include <map> 
#include <boost/regex.hpp> 
#include <functional> 

// purpose: 
// takes the contents of a file in the form of a string 
// and searches for all the C++ class definitions, storing 
// their locations in a map of strings/int's 

typedef std::map<std::string, int, std::less<std::string> > map_type; 
class class_index 
{ 
   boost::regex expression; 
   map_type index; 
   std::string::const_iterator base; 
   typedef boost::match_results<std::string::const_iterator, boost::regex::alloc_type> arg_type; 
   bool grep_callback(const arg_type& what); 
public: 
   typedef bool (__closure* grep_callback_type)(const arg_type&); 
   void IndexClasses(const std::string& file); 
   class_index() 
      : index(), 
        expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?" 
                   "(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?" 
                   "[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?" 
                   "(\\{|:[^;\\{()]*\\{)" 
                   ){} 
}; 

bool class_index::grep_callback(const arg_type& what) 
{ 
   // what[0] contains the whole string    
// what[5] contains the class name.    
// what[6] contains the template specialisation if any.    
// add class name and position to map:    
index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] = 
               what[5].first - base; 
   return true; 
} 

void class_index::IndexClasses(const std::string& file) 
{ 
   std::string::const_iterator start, end; 
   start = file.begin(); 
   end = file.end(); 
   base = start; 
   class_index::grep_callback_type cl = &(this->grep_callback); 
   regex_grep(cl, 
            start, 
            end, 
            expression); 
} 

 Algorithm regex_format

#include <boost/regex.hpp>

The algorithm regex_format takes the results of a match and creates a new string based upon a format string, regex_format can be used for search and replace operations:

template <class OutputIterator, class iterator, class Allocator, class charT>
OutputIterator regex_format(OutputIterator out,
                            const match_results<iterator, Allocator>& m,
                            const charT* fmt,
                            unsigned flags = 0);

template <class OutputIterator, class iterator, class Allocator, class charT>
OutputIterator regex_format(OutputIterator out,
                            const match_results<iterator, Allocator>& m,
                            const std::basic_string<charT>& fmt,
                            unsigned flags = 0);

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]:

template <class iterator, class Allocator, class charT>
std::basic_string<charT> regex_format
                                 (const match_results<iterator, Allocator>& m, 
                                  const charT* fmt,
                                  unsigned flags = 0);

template <class iterator, class Allocator, class charT>
std::basic_string<charT> regex_format
                                 (const match_results<iterator, Allocator>& m, 
                                  const std::basic_string<charT>& fmt,
                                  unsigned flags = 0);

Parameters to the main version of the function are passed as follows:
 

Format flags are defined as follows:
 

The format string syntax (and available options) is described more fully under format strings.

Algorithm regex_merge

#include <boost/regex.hpp>

The algorithm regex_merge is a combination of regex_grep and regex_format. 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 format_no_copy set. If the flag format_first_only is set then only the first occurance is replaced rather than all occurrences.

template <class OutputIterator, class iterator, class traits, class Allocator, class charT>
OutputIterator regex_merge(OutputIterator out, 
                          iterator first,
                          iterator last,
                          const reg_expression<charT, traits, Allocator>& e, 
                          const charT* fmt, 
                          unsigned int flags = match_default);

template <class OutputIterator, class iterator, class traits, class Allocator, class charT>
OutputIterator regex_merge(OutputIterator out, 
                           iterator first,
                           iterator last,
                           const reg_expression<charT, traits, Allocator>& e, 
                           std::basic_string<charT>& fmt, 
                           unsigned int flags = match_default);

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]:

template <class traits, class Allocator, class charT>
std::basic_string<charT> regex_merge(const std::basic_string<charT>& text,
                                     const reg_expression<charT, traits, Allocator>& e, 
                                     const charT* fmt, 
                                     unsigned int flags = match_default);

template <class traits, class Allocator, class charT>
std::basic_string<charT> regex_merge(const std::basic_string<charT>& text,
                                     const reg_expression<charT, traits, Allocator>& e, 
                                     const std::basic_string<charT>& fmt, 
                                     unsigned int flags = match_default);

Parameters to the main version of the function are passed as follows:
 

Example: the following example takes C/C++ source code as input, and outputs syntax highlighted HTML code.

#include <fstream>
#include <sstream>
#include <string>
#include <iterator>
#include <boost/regex.hpp>
#include <fstream>
#include <iostream>

// purpose:
// takes the contents of a file and transform to
// syntax highlighted code in html format

boost::regex e1, e2;
extern const char* expression_text;
extern const char* format_string;
extern const char* pre_expression;
extern const char* pre_format;
extern const char* header_text;
extern const char* footer_text;

void load_file(std::string& s, std::istream& is)
{
   s.erase();
   s.reserve(is.rdbuf()->in_avail());
   char c;
   while(is.get(c))
   {
      if(s.capacity() == s.size())
         s.reserve(s.capacity() * 3);
      s.append(1, c);
   }
}

int main(int argc, const char** argv)
{
   try{
   e1.assign(expression_text);
   e2.assign(pre_expression);
   for(int i = 1; i < argc; ++i)
   {
      std::cout << "Processing file " << argv[i] << std::endl;
      std::ifstream fs(argv[i]);
      std::string in;
      load_file(in, fs);
      std::string out_name(std::string(argv[i]) + std::string(".htm"));
      std::ofstream os(out_name.c_str());
      os << header_text;
      // strip '<' and '>' first by outputting to a
      // temporary string stream
      std::ostringstream t(std::ios::out | std::ios::binary);
      std::ostream_iterator<char, char> oi(t);
      boost::regex_merge(oi, in.begin(), in.end(), e2, pre_format);
      // then output to final output stream
      // adding syntax highlighting:
      std::string s(t.str());
      std::ostream_iterator<char, char> out(os);
      boost::regex_merge(out, s.begin(), s.end(), e1, format_string);
      os << footer_text;
   }
   }
   catch(...)
   { return -1; }
   return 0;
}

extern const char* pre_expression = "(<)|(>)|\\r";
extern const char* pre_format = "(?1<)(?2>)";


const char* expression_text = // preprocessor directives: index 1
                              "(^[[:blank:]]*#(?:[^\\\\\\n]|\\\\[^\\n[:punct:][:word:]]*[\\n[:punct:][:word:]])*)|"
                              // comment: index 2
                              "(//[^\\n]*|/\\*.*?\\*/)|"
                              // literals: index 3
                              "\\<([+-]?(?:(?:0x[[:xdigit:]]+)|(?:(?:[[:digit:]]*\\.)?[[:digit:]]+(?:[eE][+-]?[[:digit:]]+)?))u?(?:(?:int(?:8|16|32|64))|L)?)\\>|"
                              // string literals: index 4
                              "('(?:[^\\\\']|\\\\.)*'|\"(?:[^\\\\\"]|\\\\.)*\")|"
                              // keywords: index 5
                              "\\<(__asm|__cdecl|__declspec|__export|__far16|__fastcall|__fortran|__import"
                              "|__pascal|__rtti|__stdcall|_asm|_cdecl|__except|_export|_far16|_fastcall"
                              "|__finally|_fortran|_import|_pascal|_stdcall|__thread|__try|asm|auto|bool"
                              "|break|case|catch|cdecl|char|class|const|const_cast|continue|default|delete"
                              "|do|double|dynamic_cast|else|enum|explicit|extern|false|float|for|friend|goto"
                              "|if|inline|int|long|mutable|namespace|new|operator|pascal|private|protected"
                              "|public|register|reinterpret_cast|return|short|signed|sizeof|static|static_cast"
                              "|struct|switch|template|this|throw|true|try|typedef|typeid|typename|union|unsigned"
                              "|using|virtual|void|volatile|wchar_t|while)\\>"
                              ;

const char* format_string = "(?1<font color=\"#008040\">$&</font>)"
                            "(?2<I><font color=\"#000080\">$&</font></I>)"
                            "(?3<font color=\"#0000A0\">$&</font>)"
                            "(?4<font color=\"#0000FF\">$&</font>)"
                            "(?5<B>$&</B>)";

const char* header_text = "<HTML>\n<HEAD>\n"
                          "<TITLE>Auto-generated html formated source</TITLE>\n"
                          "<META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html; charset=windows-1252\">\n"
                          "</HEAD>\n"
                          "<BODY LINK=\"#0000ff\" VLINK=\"#800080\" BGCOLOR=\"#ffffff\">\n"
                          "<P> </P>\n<PRE>";

const char* footer_text = "</PRE>\n</BODY>\n\n";

Algorithm regex_split

#include <boost/regex.hpp>

Algorithm regex_split performs a similar operation to the perl split operation, and comes in three overloaded forms:

template <class OutputIterator, class charT, class Traits1, class Alloc1, class Traits2, class Alloc2>
std::size_t regex_split(OutputIterator out, 
                        std::basic_string<charT, Traits1, Alloc1>& s, 
                        const reg_expression<charT, Traits2, Alloc2>& e,
                        unsigned flags,
                        std::size_t max_split);

template <class OutputIterator, class charT, class Traits1, class Alloc1, class Traits2, class Alloc2>
std::size_t regex_split(OutputIterator out, 
                        std::basic_string<charT, Traits1, Alloc1>& s, 
                        const reg_expression<charT, Traits2, Alloc2>& e,
                        unsigned flags = match_default);

template <class OutputIterator, class charT, class Traits1, class Alloc1>
std::size_t regex_split(OutputIterator out, 
                        std::basic_string<charT, Traits1, Alloc1>& s);

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 max_split strings will be written to the output-iterator. Before returning, all the input processed will be deleted from the string s (if max_split is not reached then all of s will be deleted). Returns the number of strings written to the output-iterator. If the parameter max_split is not specified then it defaults to UINT_MAX. If no expression is specified, then it defaults to "\s+", and splitting occurs on whitespace.

Example: the following function will split the input string into a series of tokens, and remove each token from the string s:

unsigned tokenise(std::list<std::string>& l, std::string& s)
{
   return boost::regex_split(std::back_inserter(l), s);
}

Example: the following short program will extract all of the URL's from a html file, and print them out to cout:

#include <list>
#include <fstream>
#include <iostream>
#include <boost/regex.hpp>

boost::regex e("<\\s*A\\s+[^>]*href\\s*=\\s*\"([^\"]*)\"",
               boost::regbase::normal | boost::regbase::icase);

void load_file(std::string& s, std::istream& is)
{
   s.erase();
   //
   // attempt to grow string buffer to match file size,
   // this doesn't always work...
   s.reserve(is.rdbuf()-&gtin_avail());
   char c;
   while(is.get(c))
   {
      // use logarithmic growth stategy, in case
      // in_avail (above) returned zero:
      if(s.capacity() == s.size())
         s.reserve(s.capacity() * 3);
      s.append(1, c);
   }
}


int main(int argc, char** argv)
{
   std::string s;
   std::list<std::string> l;

   for(int i = 1; i < argc; ++i)
   {
      std::cout << "Findings URL's in " << argv[i] << ":" << std::endl;
      s.erase();
      std::ifstream is(argv[i]);
      load_file(s, is);
      boost::regex_split(std::back_inserter(l), s, e);
      while(l.size())
      {
         s = *(l.begin());
         l.pop_front();
         std::cout << s << std::endl;
      }
   }
   return 0;
}

Partial Matches

The match-flag match_partial can be passed to the following algorithms: regex_match, regex_search, and regex_grep. 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):

The following example 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 is_possible_card_number. 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.

#include <string>
#include <iostream>
#include <boost/regex.hpp>

boost::regex e("(\\d{3,4})[- ]?(\\d{4})[- ]?(\\d{4})[- ]?(\\d{4})");

bool is_possible_card_number(const std::string& input)
{
   //
   // return false for partial match, true for full match, or throw for
   // impossible match based on what we have so far...
   boost::match_results<std::string::const_iterator> what;
   if(0 == boost::regex_match(input, what, e, boost::match_default | boost::match_partial))
   {
      // the input so far could not possibly be valid so reject it:
      throw std::runtime_error("Invalid data entered - this could not possibly be a valid card number");
   }
   // OK so far so good, but have we finished?
   if(what[0].matched)
   {
      // excellent, we have a result:
      return true;
   }
   // what we have so far is only a partial match...
   return false;
}

In the following example, 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:

#include <iostream>
#include <fstream>
#include <sstream>
#include <string>
#include <boost/regex.hpp>

// match some kind of html tag:
boost::regex e("<[^>]*>");
// count how many:
unsigned int tags = 0;
// saved position of partial match:
char* next_pos = 0;

bool grep_callback(const boost::match_results<char*>& m)
{
   if(m[0].matched == false)
   {
      // save position and return:
      next_pos = m[0].first;
   }
   else
      ++tags;
   return true;
}

void search(std::istream& is)
{
   char buf[4096];
   next_pos = buf + sizeof(buf);
   bool have_more = true;
   while(have_more)
   {
      // how much do we copy forward from last try:
      unsigned leftover = (buf + sizeof(buf)) - next_pos;
      // and how much is left to fill:
      unsigned size = next_pos - buf;
      // copy forward whatever we have left:
      memcpy(buf, next_pos, leftover);
      // fill the rest from the stream:
      unsigned read = is.readsome(buf + leftover, size);
      // check to see if we've run out of text:
      have_more = read == size;
      // reset next_pos:
      next_pos = buf + sizeof(buf);
      // and then grep:
      boost::regex_grep(grep_callback,
                        buf,
                        buf + read + leftover,
                        e,
                        boost::match_default | boost::match_partial);
   }
}

Copyright Dr John Maddock 1998-2001 all rights reserved.