1[/ 2 Copyright 2006-2007 John Maddock. 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt). 6] 7 8 9[section:captures Understanding Marked Sub-Expressions and Captures] 10 11Captures are the iterator ranges that are "captured" by marked 12sub-expressions as a regular expression gets matched. Each marked 13sub-expression can result in more than one capture, if it is matched 14more than once. This document explains how captures and marked 15sub-expressions in Boost.Regex are represented and accessed. 16 17[h4 Marked sub-expressions] 18 19Every time a Perl regular expression contains a parenthesis group `()`, it 20spits out an extra field, known as a marked sub-expression, 21for example the expression: 22 23[pre (\w+)\W+(\w+)] 24 25Has two marked sub-expressions (known as $1 and $2 respectively), in 26addition the complete match is known as $&, everything before the 27first match as $\`, and everything after the match as $'. So 28if the above expression is searched for within `"@abc def--"`, then we obtain: 29 30[table 31[[Sub-expression][Text found]] 32[[$\`]["@"]] 33[[$&]["abc def"]] 34[[$1]["abc"]] 35[[$2]["def"]] 36[[$']["--"]] 37] 38 39In Boost.Regex all these are accessible via the [match_results] class that 40gets filled in when calling one of the regular expression matching algorithms 41([regex_search], [regex_match], or [regex_iterator]). So given: 42 43 boost::match_results<IteratorType> m; 44 45The Perl and Boost.Regex equivalents are as follows: 46 47[table 48[[Perl][Boost.Regex]] 49[[$\`][`m.prefix()`]] 50[[$&][`m[0]`]] 51[[$n][`m[n]`]] 52[[$\'][`m.suffix()`]] 53] 54 55In Boost.Regex each sub-expression match is represented by a [sub_match] object, 56this is basically just a pair of iterators denoting the start and end 57position of the sub-expression match, but there are some additional 58operators provided so that objects of type [sub_match] behave a lot like a 59`std::basic_string`: for example they are implicitly convertible to a 60`basic_string`, they can be compared to a string, added to a string, or 61streamed out to an output stream. 62 63[h4 Unmatched Sub-Expressions] 64 65When a regular expression match is found there is no need for all of the 66marked sub-expressions to have participated in the match, for example the expression: 67 68[pre (abc)|(def)] 69 70can match either $1 or $2, but never both at the same time. In Boost.Regex 71you can determine which sub-expressions matched by accessing the 72`sub_match::matched` data member. 73 74[h4 Repeated Captures] 75 76When a marked sub-expression is repeated, then the sub-expression gets 77"captured" multiple times, however normally only the final capture is available, 78for example if 79 80[pre (?:(\w+)\W+)+] 81 82is matched against 83 84[pre one fine day] 85 86Then $1 will contain the string "day", and all the previous captures will have 87been forgotten. 88 89However, Boost.Regex has an experimental feature that allows all the capture 90information to be retained - this is accessed either via the 91`match_results::captures` member function or the `sub_match::captures` member 92function. These functions return a container that contains a sequence of all 93the captures obtained during the regular expression matching. The following 94example program shows how this information may be used: 95 96 #include <boost/regex.hpp> 97 #include <iostream> 98 99 void print_captures(const std::string& regx, const std::string& text) 100 { 101 boost::regex e(regx); 102 boost::smatch what; 103 std::cout << "Expression: \"" << regx << "\"\n"; 104 std::cout << "Text: \"" << text << "\"\n"; 105 if(boost::regex_match(text, what, e, boost::match_extra)) 106 { 107 unsigned i, j; 108 std::cout << "** Match found **\n Sub-Expressions:\n"; 109 for(i = 0; i < what.size(); ++i) 110 std::cout << " $" << i << " = \"" << what[i] << "\"\n"; 111 std::cout << " Captures:\n"; 112 for(i = 0; i < what.size(); ++i) 113 { 114 std::cout << " $" << i << " = {"; 115 for(j = 0; j < what.captures(i).size(); ++j) 116 { 117 if(j) 118 std::cout << ", "; 119 else 120 std::cout << " "; 121 std::cout << "\"" << what.captures(i)[j] << "\""; 122 } 123 std::cout << " }\n"; 124 } 125 } 126 else 127 { 128 std::cout << "** No Match found **\n"; 129 } 130 } 131 132 int main(int , char* []) 133 { 134 print_captures("(([[:lower:]]+)|([[:upper:]]+))+", "aBBcccDDDDDeeeeeeee"); 135 print_captures("(.*)bar|(.*)bah", "abcbar"); 136 print_captures("(.*)bar|(.*)bah", "abcbah"); 137 print_captures("^(?:(\\w+)|(?>\\W+))*$", 138 "now is the time for all good men to come to the aid of the party"); 139 return 0; 140 } 141 142Which produces the following output: 143 144[pre 145Expression: "((\[\[:lower:\]\]+)|(\[\[:upper:\]\]+))+" 146Text: "aBBcccDDDDDeeeeeeee" 147'''**''' Match found '''**''' 148 Sub-Expressions: 149 $0 = "aBBcccDDDDDeeeeeeee" 150 $1 = "eeeeeeee" 151 $2 = "eeeeeeee" 152 $3 = "DDDDD" 153 Captures: 154 $0 = { "aBBcccDDDDDeeeeeeee" } 155 $1 = { "a", "BB", "ccc", "DDDDD", "eeeeeeee" } 156 $2 = { "a", "ccc", "eeeeeeee" } 157 $3 = { "BB", "DDDDD" } 158Expression: "(.'''*''')bar|(.'''*''')bah" 159Text: "abcbar" 160'''**''' Match found '''**''' 161 Sub-Expressions: 162 $0 = "abcbar" 163 $1 = "abc" 164 $2 = "" 165 Captures: 166 $0 = { "abcbar" } 167 $1 = { "abc" } 168 $2 = { } 169Expression: "(.'''*''')bar|(.'''*''')bah" 170Text: "abcbah" 171'''**''' Match found '''**''' 172 Sub-Expressions: 173 $0 = "abcbah" 174 $1 = "" 175 $2 = "abc" 176 Captures: 177 $0 = { "abcbah" } 178 $1 = { } 179 $2 = { "abc" } 180Expression: "^(?:(\w+)|(?>\W+))'''*$'''" 181Text: "now is the time for all good men to come to the aid of the party" 182'''**''' Match found '''**''' 183 Sub-Expressions: 184 $0 = "now is the time for all good men to come to the aid of the party" 185 $1 = "party" 186 Captures: 187 $0 = { "now is the time for all good men to come to the aid of the party" } 188 $1 = { "now", "is", "the", "time", "for", "all", "good", "men", "to", 189 "come", "to", "the", "aid", "of", "the", "party" } 190] 191 192Unfortunately enabling this feature has an impact on performance 193(even if you don't use it), and a much bigger impact if you do use it, 194therefore to use this feature you need to: 195 196* Define BOOST_REGEX_MATCH_EXTRA for all translation units including the library source (the best way to do this is to uncomment this define in boost/regex/user.hpp and then rebuild everything. 197* Pass the match_extra flag to the particular algorithms where you actually need the captures information (regex_search, regex_match, or regex_iterator). 198 199[endsect] 200 201