ceph/src/boost/libs/regex/doc/regex_search.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:regex_search regex_search]
  10
  11    #include <boost/regex.hpp>
  12
  13 The algorithm [regex_search] will search a range denoted by a pair of
  14 bidirectional-iterators for a given regular expression. The algorithm
  15 uses various heuristics to reduce the search time by only checking
  16 for a match if a match could conceivably start at that position. The
  17 algorithm is defined as follows:
  18
  19    template <class BidirectionalIterator,
  20             class Allocator, class charT, class traits>
  21    bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
  22                      match_results<BidirectionalIterator, Allocator>& m,
  23                      const basic_regex<charT, traits>& e,
  24                      match_flag_type flags = match_default);
  25
  26    template <class ST, class SA,
  27             class Allocator, class charT, class traits>
  28    bool regex_search(const basic_string<charT, ST, SA>& s,
  29                      match_results<
  30                      typename basic_string<charT, ST,SA>::const_iterator,
  31                      Allocator>& m,
  32                      const basic_regex<charT, traits>& e,
  33                      match_flag_type flags = match_default);
  34
  35    template<class charT, class Allocator, class traits>
  36    bool regex_search(const charT* str,
  37                      match_results<const charT*, Allocator>& m,
  38                      const basic_regex<charT, traits>& e,
  39                      match_flag_type flags = match_default);
  40
  41    template <class BidirectionalIterator, class charT, class traits>
  42    bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
  43                      const basic_regex<charT, traits>& e,
  44                      match_flag_type flags = match_default);
  45
  46    template <class charT, class traits>
  47    bool regex_search(const charT* str,
  48                      const basic_regex<charT, traits>& e,
  49                      match_flag_type flags = match_default);
  50
  51    template<class ST, class SA, class charT, class traits>
  52    bool regex_search(const basic_string<charT, ST, SA>& s,
  53                      const basic_regex<charT, traits>& e,
  54                      match_flag_type flags = match_default);
  55
  56 [h4 Description]
  57
  58    template <class BidirectionalIterator, class Allocator, class charT, class traits>
  59    bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
  60                      match_results<BidirectionalIterator, Allocator>& m,
  61                      const basic_regex<charT, traits>& e,
  62                      match_flag_type flags = match_default);
  63
  64 [*Requires]: Type BidirectionalIterator meets the requirements of a Bidirectional Iterator (24.1.4).
  65
  66 [*Effects]: Determines whether there is some sub-sequence within \[first,last)
  67 that matches the regular expression /e/, parameter /flags/ is used to control
  68 how the expression is matched against the character sequence. Returns
  69 true if such a sequence exists, false otherwise.
  70
  71 [*Throws]: `std::runtime_error` if the complexity of matching the expression
  72 against an N character string begins to exceed O(N[super 2]), or if the
  73 program runs out of stack space while matching the expression (if Boost.Regex is
  74 configured in recursive mode), or if the matcher exhausts its permitted
  75 memory allocation (if Boost.Regex is configured in non-recursive mode).
  76
  77 [*Postconditions]: If the function returns false, then the effect on
  78 parameter /m/ is undefined, otherwise the effects on parameter /m/
  79 are given in the table:
  80
  81 [table
  82 [[Element][Value]]
  83 [[`m.size()`][`1 + e.mark_count()`]]
  84 [[`m.empty()`][`false`]]
  85 [[`m.prefix().first`][`first`]]
  86 [[`m.prefix().last`][`m[0].first`]]
  87 [[`m.prefix().matched`][`m.prefix().first != m.prefix().second`]]
  88 [[`m.suffix().first`][`m[0].second`]]
  89 [[`m.suffix().last`][`last`]]
  90 [[`m.suffix().matched`][`m.suffix().first != m.suffix().second`]]
  91 [[`m[0].first`][The start of the sequence of characters that matched the regular expression]]
  92 [[`m[0].second`][The end of the sequence of characters that matched the regular expression]]
  93 [[`m[0].matched`][true if a full match was found, and false if it was a partial match (found as a result of the match_partial flag being set).]]
  94 [[`m[n].first`][For all integers `n < m.size()`, the start of the sequence that
  95       matched sub-expression /n/. Alternatively, if sub-expression /n/ did not
  96       participate in the match, then last.]]
  97 [[`m[n].second`][For all integers `n < m.size()`, the end of the sequence that
  98       matched sub-expression /n/. Alternatively, if sub-expression /n/ did not
  99       participate in the match, then `last`.]]
 100 [[`m[n].matched`][For all integers `n < m.size()`, true if sub-expression /n/
 101       participated in the match, false otherwise.]]
 102 ]
 103
 104    template <class charT, class Allocator, class traits>
 105    bool regex_search(const charT* str, match_results<const charT*, Allocator>& m,
 106                      const basic_regex<charT, traits>& e,
 107                      match_flag_type flags = match_default);
 108
 109 [*Effects]: Returns the result of `regex_search(str, str + char_traits<charT>::length(str), m, e, flags)`.
 110
 111    template <class ST, class SA, class Allocator, class charT,
 112             class traits>
 113    bool regex_search(const basic_string<charT, ST, SA>& s,
 114                      match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
 115                      const basic_regex<charT, traits>& e,
 116                      match_flag_type flags = match_default);
 117
 118 [*Effects]: Returns the result of `regex_search(s.begin(), s.end(), m, e, flags)`.
 119
 120    template <class iterator, class charT, class traits>
 121    bool regex_search(iterator first, iterator last,
 122                      const basic_regex<charT, traits>& e,
 123                      match_flag_type flags = match_default);
 124
 125 [*Effects]: Behaves "as if" by constructing an instance of
 126 `match_results<BidirectionalIterator> what`, and then returning the result of
 127 `regex_search(first, last, what, e, flags)`.
 128
 129    template <class charT, class traits>
 130    bool regex_search(const charT* str
 131                      const basic_regex<charT, traits>& e,
 132                      match_flag_type flags = match_default);
 133
 134 [*Effects]: Returns the result of `regex_search(str, str + char_traits<charT>::length(str), e, flags)`.
 135
 136    template <class ST, class SA, class charT, class traits>
 137    bool regex_search(const basic_string<charT, ST, SA>& s,
 138                      const basic_regex<charT, traits>& e,
 139                      match_flag_type flags = match_default);
 140
 141 [*Effects]: Returns the result of `regex_search(s.begin(), s.end(), e, flags)`.
 142
 143 [h4 Examples]
 144
 145 The following example, takes the contents of a file in the form of a string,
 146 and searches for all the C++ class declarations in the file. The code will
 147 work regardless of the way that `std::string` is implemented, for example it
 148 could easily be modified to work with the SGI rope class, which uses a
 149 non-contiguous storage strategy.
 150
 151    #include <string>
 152    #include <map>
 153    #include <boost/regex.hpp>
 154
 155    // purpose:
 156    // takes the contents of a file in the form of a string
 157    // and searches for all the C++ class definitions, storing
 158    // their locations in a map of strings/int's
 159    typedef std::map<std::string, int, std::less<std::string> > map_type;
 160
 161    boost::regex expression(
 162       "^(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"
 163       "(class|struct)[[:space:]]*"
 164       "(\\<\\w+\\>([[:blank:]]*\\([^)]*\\))?"
 165       "[[:space:]]*)*(\\<\\w*\\>)[[:space:]]*"
 166       "(<[^;:{]+>[[:space:]]*)?(\\{|:[^;\\{()]*\\{)");
 167
 168    void IndexClasses(map_type& m, const std::string& file)
 169    {
 170       std::string::const_iterator start, end;
 171       start = file.begin();
 172       end = file.end();
 173          boost::match_results<std::string::const_iterator> what;
 174       boost::match_flag_type flags = boost::match_default;
 175       while(regex_search(start, end, what, expression, flags))
 176       {
 177          // what[0] contains the whole string
 178          // what[5] contains the class name.
 179          // what[6] contains the template specialisation if any.
 180          // add class name and position to map:
 181          m[std::string(what[5].first, what[5].second)
 182                + std::string(what[6].first, what[6].second)]
 183             = what[5].first - file.begin();
 184          // update search position:
 185          start = what[0].second;
 186          // update flags:
 187          flags |= boost::match_prev_avail;
 188          flags |= boost::match_not_bob;
 189       }
 190    }
 191
 192 [endsect]
 193