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:old_regex High Level Class RegEx (Deprecated)] 10 11The high level wrapper class RegEx is now deprecated and does not form 12part of the regular expression standardization proposal. This type still 13exists, and existing code will continue to compile, however the following 14documentation is unlikely to be further updated. 15 16 #include <boost/cregex.hpp> 17 18The class RegEx provides a high level simplified interface to the regular 19expression library, this class only handles narrow character strings, and 20regular expressions always follow the "normal" syntax - that is the 21same as the perl / ECMAScript syntax. 22 23 typedef bool (*GrepCallback)(const RegEx& expression); 24 typedef bool (*GrepFileCallback)(const char* file, const RegEx& expression); 25 typedef bool (*FindFilesCallback)(const char* file); 26 27 class RegEx 28 { 29 public: 30 RegEx(); 31 RegEx(const RegEx& o); 32 ~RegEx(); 33 RegEx(const char* c, bool icase = false); 34 explicit RegEx(const std::string& s, bool icase = false); 35 RegEx& operator=(const RegEx& o); 36 RegEx& operator=(const char* p); 37 RegEx& operator=(const std::string& s); 38 unsigned int SetExpression(const char* p, bool icase = false); 39 unsigned int SetExpression(const std::string& s, bool icase = false); 40 std::string Expression()const; 41 // 42 // now matching operators: 43 // 44 bool Match(const char* p, boost::match_flag_type flags = match_default); 45 bool Match(const std::string& s, boost::match_flag_type flags = match_default); 46 bool Search(const char* p, boost::match_flag_type flags = match_default); 47 bool Search(const std::string& s, boost::match_flag_type flags = match_default); 48 unsigned int Grep(GrepCallback cb, const char* p, 49 boost::match_flag_type flags = match_default); 50 unsigned int Grep(GrepCallback cb, const std::string& s, 51 boost::match_flag_type flags = match_default); 52 unsigned int Grep(std::vector<std::string>& v, const char* p, 53 boost::match_flag_type flags = match_default); 54 unsigned int Grep(std::vector<std::string>& v, const std::string& s, 55 boost::match_flag_type flags = match_default); 56 unsigned int Grep(std::vector<unsigned int>& v, const char* p, 57 boost::match_flag_type flags = match_default); 58 unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, 59 boost::match_flag_type flags = match_default); 60 unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, 61 boost::match_flag_type flags = match_default); 62 unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, 63 bool recurse = false, 64 boost::match_flag_type flags = match_default); 65 unsigned int FindFiles(FindFilesCallback cb, const char* files, 66 bool recurse = false, 67 boost::match_flag_type flags = match_default); 68 unsigned int FindFiles(FindFilesCallback cb, const std::string& files, 69 bool recurse = false, 70 boost::match_flag_type flags = match_default); 71 std::string Merge(const std::string& in, const std::string& fmt, 72 bool copy = true, boost::match_flag_type flags = match_default); 73 std::string Merge(const char* in, const char* fmt, bool copy = true, 74 boost::match_flag_type flags = match_default); 75 unsigned Split(std::vector<std::string>& v, std::string& s, 76 boost::match_flag_type flags = match_default, 77 unsigned max_count = ~0); 78 // 79 // now operators for returning what matched in more detail: 80 // 81 unsigned int Position(int i = 0)const; 82 unsigned int Length(int i = 0)const; 83 bool Matched(int i = 0)const; 84 unsigned int Line()const; 85 unsigned int Marks() const; 86 std::string What(int i)const; 87 std::string operator[](int i)const ; 88 89 static const unsigned int npos; 90 }; 91 92Member functions for class RegEx are defined as follows: 93 94[table 95[[Member][Description]] 96[[`RegEx();`][Default constructor, constructs an instance of RegEx without any valid expression. ]] 97[[`RegEx(const RegEx& o);`][Copy constructor, all the properties of parameter /o/ 98 are copied. ]] 99[[`RegEx(const char* c, bool icase = false);`][Constructs an instance of RegEx, 100 setting the expression to /c/, if /icase/ is true then matching is 101 insensitive to case, otherwise it is sensitive to case. Throws 102 [bad_expression] on failure. ]] 103[[`RegEx(const std::string& s, bool icase = false);`][Constructs an instance of 104 RegEx, setting the expression to /s/, if /icase/ is true then matching 105 is insensitive to case, otherwise it is sensitive to case. Throws 106 [bad_expression] on failure. ]] 107[[`RegEx& operator=(const RegEx& o);`][Default assignment operator. ]] 108[[`RegEx& operator=(const char* p);`][Assignment operator, equivalent to calling 109 `SetExpression(p, false)`. Throws [bad_expression] on failure. ]] 110[[`RegEx& operator=(const std::string& s);`][Assignment operator, equivalent to 111 calling `SetExpression(s, false)`. Throws [bad_expression] on failure. ]] 112[[`unsigned int SetExpression(const char* p, bool icase = false);`][Sets the 113 current expression to /p/, if /icase/ is true then matching is 114 insensitive to case, otherwise it is sensitive to case. 115 Throws [bad_expression] on failure. ]] 116[[`unsigned int SetExpression(const std::string& s, bool icase = false);`] 117 [Sets the current expression to /s/, if /icase/ is true then matching is 118 insensitive to case, otherwise it is sensitive to case. Throws 119 [bad_expression] on failure. ]] 120[[`std::string Expression()const;`][Returns a copy of the current regular expression. ]] 121[[`bool Match(const char* p, boost::match_flag_type flags = match_default);`] 122 [Attempts to match the current expression against the text /p/ using 123 the match flags /flags/ - see [match_flag_type]. Returns /true/ if the 124 expression matches the whole of the input string. ]] 125[[`bool Match(const std::string& s, boost::match_flag_type flags = match_default);`] 126 [Attempts to match the current expression against the text /s/ using 127 the [match_flag_type] /flags/. Returns /true/ if the expression matches 128 the whole of the input string. ]] 129[[`bool Search(const char* p, boost::match_flag_type flags = match_default);`] 130 [Attempts to find a match for the current expression somewhere in 131 the text /p/ using the [match_flag_type] /flags/. Returns /true/ 132 if the match succeeds. ]] 133[[`bool Search(const std::string& s, boost::match_flag_type flags = match_default);`] 134 [Attempts to find a match for the current expression somewhere in the 135 text /s/ using the [match_flag_type] flags. Returns /true/ if the 136 match succeeds. ]] 137[[`unsigned int Grep(GrepCallback cb, const char* p, boost::match_flag_type flags = match_default);`] 138 [Finds all matches of the current expression in the text /p/ using the 139 [match_flag_type] /flags/. For each match found calls the call-back 140 function cb as: `cb(*this);` 141 If at any stage the call-back function returns /false/ then the grep 142 operation terminates, otherwise continues until no further matches 143 are found. Returns the number of matches found.]] 144[[`unsigned int Grep(GrepCallback cb, const std::string& s, boost::match_flag_type flags = match_default);`] 145 [Finds all matches of the current expression in the text /s/ using the 146 [match_flag_type] flags. For each match found calls the call-back 147 function cb as: `cb(*this);` 148 If at any stage the call-back function returns false then the grep operation 149 terminates, otherwise continues until no further matches are found. 150 Returns the number of matches found.]] 151[[`unsigned int Grep(std::vector<std::string>& v, const char* p, boost::match_flag_type flags = match_default);`] 152 [Finds all matches of the current expression in the text /p/ using the 153 [match_flag_type] flags. For each match pushes a copy of what matched 154 onto /v/. Returns the number of matches found. ]] 155[[`unsigned int Grep(std::vector<std::string>& v, const std::string& s, boost::match_flag_type flags = match_default);`] 156 [Finds all matches of the current expression in the text /s/ using the 157 [match_flag_type] /flags/. For each match pushes a copy of what 158 matched onto /v/. Returns the number of matches found. ]] 159[[`unsigned int Grep(std::vector<unsigned int>& v, const char* p, boost::match_flag_type flags = match_default);`] 160 [Finds all matches of the current expression in the text /p/ using the 161 [match_flag_type] /flags/. For each match pushes the starting index of 162 what matched onto /v/. Returns the number of matches found. ]] 163[[`unsigned int Grep(std::vector<unsigned int>& v, const std::string& s, boost::match_flag_type flags = match_default);`] 164 [Finds all matches of the current expression in the text /s/ using the 165 [match_flag_type] /flags/. For each match pushes the starting index of what 166 matched onto /v/. Returns the number of matches found. ]] 167[[`unsigned int GrepFiles(GrepFileCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`] 168 [Finds all matches of the current expression in the files /files/ using 169 the [match_flag_type] /flags/. For each match calls the call-back function cb. 170 If the call-back returns false then the algorithm returns without 171 considering further matches in the current file, or any further files. 172 173 The parameter /files/ can include wild card characters '\*' and '\?', if 174 the parameter recurse is true then searches sub-directories for matching 175 file names. 176 177 Returns the total number of matches found. 178 179 May throw an exception derived from `std::runtime_error` if file io fails.]] 180[[`unsigned int GrepFiles(GrepFileCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`] 181 [Finds all matches of the current expression in the files /files/ using the 182 [match_flag_type] /flags/. For each match calls the call-back function cb. 183 184 If the call-back returns false then the algorithm returns without 185 considering further matches in the current file, or any further files. 186 187 The parameter /files/ can include wild card characters '\*' and '\?', if 188 the parameter recurse is true then searches sub-directories for 189 matching file names. 190 191 Returns the total number of matches found. 192 193 May throw an exception derived from `std::runtime_error` if file io fails.]] 194 195[[`unsigned int FindFiles(FindFilesCallback cb, const char* files, bool recurse = false, boost::match_flag_type flags = match_default);`] 196 [Searches files to find all those which contain at least one match of 197 the current expression using the [match_flag_type] /flags/. For each 198 matching file calls the call-back function cb. 199 If the call-back returns false then the algorithm returns without 200 considering any further files. 201 202 The parameter /files/ can include wild card characters '\*' and '\?', if 203 the parameter /recurse/ is true then searches sub-directories for 204 matching file names. 205 206 Returns the total number of files found. 207 208 May throw an exception derived from `std::runtime_error` if file io fails.]] 209[[`unsigned int FindFiles(FindFilesCallback cb, const std::string& files, bool recurse = false, boost::match_flag_type flags = match_default);`] 210 [Searches files to find all those which contain at least one 211 match of the current expression using the [match_flag_type] /flags/. 212 For each matching file calls the call-back function cb. 213 214 If the call-back returns false then the algorithm returns without 215 considering any further files. 216 217 The parameter /files/ can include wild card characters '\*' and '\?', if 218 the parameter /recurse/ is true then searches sub-directories for 219 matching file names. 220 221 Returns the total number of files found. 222 223 May throw an exception derived from `std::runtime_error` if file io fails.]] 224 225[[`std::string Merge(const std::string& in, const std::string& fmt, bool copy = true, boost::match_flag_type flags = match_default);`] 226 [Performs a search and replace operation: searches through the 227 string /in/ for all occurrences of the current expression, for each 228 occurrence replaces the match with the format string /fmt/. Uses /flags/ 229 to determine what gets matched, and how the format string should be 230 treated. If /copy/ is true then all unmatched sections of input are 231 copied unchanged to output, if the flag /format_first_only/ is set then 232 only the first occurrence of the pattern found is replaced. 233 Returns the new string. See also 234 [link boost_regex.format format string syntax], and [match_flag_type].]] 235[[`std::string Merge(const char* in, const char* fmt, bool copy = true, boost::match_flag_type flags = match_default);`] 236 [Performs a search and replace operation: searches through the string /in/ 237 for all occurrences of the current expression, for each occurrence 238 replaces the match with the format string /fmt/. Uses /flags/ to determine 239 what gets matched, and how the format string should be treated. 240 If /copy/ is true then all unmatched sections of input are copied 241 unchanged to output, if the flag /format_first_only/ is set then only 242 the first occurrence of the pattern found is replaced. Returns 243 the new string. See also [link boost_regex.format format string syntax], and [match_flag_type].]] 244[[`unsigned Split(std::vector<std::string>& v, std::string& s, boost::match_flag_type flags = match_default, unsigned max_count = ~0);`] 245 [Splits the input string and pushes each one onto the vector. 246 If the expression contains no marked sub-expressions, then one 247 string is outputted for each section of the input that does not 248 match the expression. If the expression does contain marked 249 sub-expressions, then outputs one string for each marked 250 sub-expression each time a match occurs. Outputs no more than 251 /max_count/ strings. Before returning, deletes from the input string 252 /s/ all of the input that has been processed (all of the string if 253 /max_count/ was not reached). Returns the number of strings pushed 254 onto the vector. ]] 255[[`unsigned int Position(int i = 0)const;`] 256 [Returns the position of what matched sub-expression /i/. If `i = 0` 257 then returns the position of the whole match. Returns `RegEx::npos` if 258 the supplied index is invalid, or if the specified sub-expression 259 did not participate in the match. ]] 260[[`unsigned int Length(int i = 0)const;`] 261 [Returns the length of what matched sub-expression i. If `i = 0` then 262 returns the length of the whole match. Returns `RegEx::npos` if the 263 supplied index is invalid, or if the specified sub-expression did not 264 participate in the match. ]] 265[[`bool Matched(int i = 0)const;`] 266 [Returns true if sub-expression /i/ was matched, false otherwise. ]] 267[[`unsigned int Line()const;`][Returns the line on which the match occurred, 268 indexes start from 1 not zero, if no match occurred then returns `RegEx::npos`. ]] 269[[`unsigned int Marks() const;`][Returns the number of marked sub-expressions 270 contained in the expression. Note that this includes the whole 271 match (sub-expression zero), so the value returned is always >= 1. ]] 272[[`std::string What(int i)const;`] 273 [Returns a copy of what matched sub-expression /i/. If `i = 0` then 274 returns a copy of the whole match. Returns a null string if the 275 index is invalid or if the specified sub-expression did not 276 participate in a match. ]] 277[[`std::string operator[](int i)const ;`][Returns `what(i);` 278 Can be used to simplify access to sub-expression matches, and make 279 usage more perl-like.]] 280] 281 282[endsect] 283 284