Captures are the iterator ranges that are "captured" by marked sub-expressions
as a regular expression gets matched. Each marked sub-expression can result
in more than one capture, if it is matched more than once. This document explains
how captures and marked sub-expressions in Boost.Regex are represented and
accessed.

Every time a Perl regular expression contains a parenthesis group (), it spits out an extra field, known as a
marked sub-expression, for example the expression:

(\w+)\W+(\w+)

Has two marked sub-expressions (known as $1 and $2 respectively), in addition
the complete match is known as $&, everything before the first match as
$`, and everything after the match as $'. So if the above expression is searched
for within "@abc def--",
then we obtain:

In Boost.Regex each sub-expression match is represented by a sub_match object, this is basically
just a pair of iterators denoting the start and end position of the sub-expression
match, but there are some additional operators provided so that objects of
type sub_match
behave a lot like a std::basic_string: for example they are implicitly
convertible to a basic_string,
they can be compared to a string, added to a string, or streamed out to an
output stream.

When a marked sub-expression is repeated, then the sub-expression gets "captured"
multiple times, however normally only the final capture is available, for example
if

(?:(\w+)\W+)+

is matched against

one fine day

Then $1 will contain the string "day", and all the previous captures
will have been forgotten.

However, Boost.Regex has an experimental feature that allows all the capture
information to be retained - this is accessed either via the match_results::captures member function or the sub_match::captures member function. These functions
return a container that contains a sequence of all the captures obtained during
the regular expression matching. The following example program shows how this
information may be used:

#include<boost/regex.hpp>#include<iostream>voidprint_captures(conststd::string&regx,conststd::string&text){boost::regexe(regx);boost::smatchwhat;std::cout<<"Expression: \""<<regx<<"\"\n";std::cout<<"Text: \""<<text<<"\"\n";if(boost::regex_match(text,what,e,boost::match_extra)){unsignedi,j;std::cout<<"** Match found **\n Sub-Expressions:\n";for(i=0;i<what.size();++i)std::cout<<" $"<<i<<" = \""<<what[i]<<"\"\n";std::cout<<" Captures:\n";for(i=0;i<what.size();++i){std::cout<<" $"<<i<<" = {";for(j=0;j<what.captures(i).size();++j){if(j)std::cout<<", ";elsestd::cout<<" ";std::cout<<"\""<<what.captures(i)[j]<<"\"";}std::cout<<" }\n";}}else{std::cout<<"** No Match found **\n";}}intmain(int,char*[]){print_captures("(([[:lower:]]+)|([[:upper:]]+))+","aBBcccDDDDDeeeeeeee");print_captures("(.*)bar|(.*)bah","abcbar");print_captures("(.*)bar|(.*)bah","abcbah");print_captures("^(?:(\\w+)|(?>\\W+))*$","now is the time for all good men to come to the aid of the party");return0;}