libs/regex/doc/old_regex.qbk

   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
  11 The high level wrapper class RegEx is now deprecated and does not form
  12 part of the regular expression standardization proposal.  This type still
  13 exists, and existing code will continue to compile, however the following
  14 documentation is unlikely to be further updated.
  15
  16    #include <boost/cregex.hpp>
  17
  18 The class RegEx provides a high level simplified interface to the regular
  19 expression library, this class only handles narrow character strings, and
  20 regular expressions always follow the "normal" syntax - that is the
  21 same 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
  92 Member 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(constchar* 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 occurance 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 occurance 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