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

foo: A predicate function object or function pointer, see below for more
information.

first: The start of the range to search.

last: The end of the range to search.

e: The regular expression to search for.

flags: The flags that determine how matching is carried out, one of the
match_flags enumerators.

The algorithm finds all of the non-overlapping matches of the expression
e, for each match it fills a match_results<iterator> structure, which contains information
on what matched, and calls the predicate foo, passing
the match_results<iterator>
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.

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.

The algorithm may throw std::runtime_error
if the complexity of matching the expression against an N
character string begins to exceed O(N2), or if the program runs out of
stack space while matching the expression (if Boost.Regex is configured
in recursive mode), or if the matcher exhausts it's permitted memory allocation
(if Boost.Regex is configured in non-recursive mode).

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 typedefstd::map<std::string,int,std::less<std::string>>map_type;constchar*re=// possibly leading whitespace: "^[[:space:]]*"// possible template declaration:"(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"// class or struct:"(class|struct)[[:space:]]*"// leading declspec macros etc:"(""\\<\\w+\\>""(""[[:blank:]]*\\([^)]*\\)"")?""[[:space:]]*"")*"// the class name"(\\<\\w*\\>)[[:space:]]*"// template specialisation parameters"(<[^;:{]+>)?[[:space:]]*"// terminate in { or :"(\\{|:[^;\\{()]*\\{)";boost::regexexpression(re);classIndexClassesPred{map_type&m;std::string::const_iteratorbase;public:IndexClassesPred(map_type&a,std::string::const_iteratorb):m(a),base(b){}booloperator()(constsmatch&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;returntrue;}};voidIndexClasses(map_type&m,conststd::string&file){std::string::const_iteratorstart,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 typedefstd::map<std::string,int,std::less<std::string>>map_type;constchar*re=// possibly leading whitespace: "^[[:space:]]*"// possible template declaration:"(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"// class or struct:"(class|struct)[[:space:]]*"// leading declspec macros etc:"(""\\<\\w+\\>""(""[[:blank:]]*\\([^)]*\\)"")?""[[:space:]]*"")*"// the class name"(\\<\\w*\\>)[[:space:]]*"// template specialisation parameters"(<[^;:{]+>)?[[:space:]]*"// terminate in { or :"(\\{|:[^;\\{()]*\\{)";boost::regexexpression(re);map_typeclass_index;std::string::const_iteratorbase;boolgrep_callback(constboost::smatch&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;returntrue;}voidIndexClasses(conststd::string&file){std::string::const_iteratorstart,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 typedefstd::map<std::string,int,std::less<std::string>>map_type;classclass_index{boost::regexexpression;map_typeindex;std::string::const_iteratorbase;boolgrep_callback(boost::smatchwhat);public:voidIndexClasses(conststd::string&file);class_index():index(),expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?""(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?""[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?""(\\{|:[^;\\{()]*\\{)"){}};boolclass_index::grep_callback(boost::smatchwhat){// 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;returntrue;}voidclass_index::IndexClasses(conststd::string&file){std::string::const_iteratorstart,end;start=file.begin();end=file.end();base=start;regex_grep(std::bind1st(std::mem_fun(&class_index::grep_callback),this),start,end,expression);}

#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 typedefstd::map<std::string,int,std::less<std::string>>map_type;classclass_index{boost::regexexpression;map_typeindex;std::string::const_iteratorbase;typedefboost::smatcharg_type;boolgrep_callback(constarg_type&what);public:typedefbool(__closure*grep_callback_type)(constarg_type&);voidIndexClasses(conststd::string&file);class_index():index(),expression("^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?""(class|struct)[[:space:]]*(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?""[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*(<[^;:{]+>[[:space:]]*)?""(\\{|:[^;\\{()]*\\{)"){}};boolclass_index::grep_callback(constarg_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;returntrue;}voidclass_index::IndexClasses(conststd::string&file){std::string::const_iteratorstart,end;start=file.begin();end=file.end();base=start;class_index::grep_callback_typecl=&(this->grep_callback);regex_grep(cl,start,end,expression);}