ceph/src/boost/libs/regex/doc/regex_match.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_match regex_match]
  10
  11    #include <boost/regex.hpp>
  12
  13 The algorithm [regex_match] determines whether a given regular expression
  14 matches [*all] of a given character sequence denoted by a pair of
  15 bidirectional-iterators, the algorithm is defined as follows,
  16 the main use of this function is data input validation.
  17
  18 [important Note that the result is true only if the expression matches the
  19 *whole* of the input sequence.  If you want to search for an
  20 expression somewhere within the sequence then use [regex_search].  If you
  21 want to match a prefix of the character string then use [regex_search]
  22 with the flag match_continuous set.]
  23
  24    template <class BidirectionalIterator, class Allocator, class charT, class traits>
  25    bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
  26                     match_results<BidirectionalIterator, Allocator>& m,
  27                     const basic_regex <charT, traits>& e,
  28                     match_flag_type flags = match_default);
  29
  30    template <class BidirectionalIterator, class charT, class traits>
  31    bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
  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_match(const charT* str, match_results<const charT*, Allocator>& m,
  37                     const basic_regex <charT, traits>& e,
  38                     match_flag_type flags = match_default);
  39
  40    template <class ST, class SA, class Allocator, class charT, class traits>
  41    bool regex_match(const basic_string<charT, ST, SA>& s,
  42                     match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
  43                     const basic_regex <charT, traits>& e,
  44                     match_flag_type flags = match_default);
  45
  46    template <class charT, class traits>
  47    bool regex_match(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_match(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_match(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
  65 Bidirectional Iterator (24.1.4).
  66
  67 [*Effects]: Determines whether there is an exact match between the regular expression /e/,
  68 and all of the character sequence \[first, last), parameter /flags/
  69 (see [match_flag_type]) is used to
  70 control how the expression is matched against the character sequence.
  71 Returns true if such a match exists, false otherwise.
  72
  73 [*Throws]: `std::runtime_error` if the complexity of matching the expression
  74 against an N character string begins to exceed O(N[super 2]), or if the
  75 program runs out of stack space while matching the expression (if Boost.Regex is
  76 configured in recursive mode), or if the matcher exhausts its permitted
  77 memory allocation (if Boost.Regex is configured in non-recursive mode).
  78
  79 [*Postconditions]: If the function returns false, then the effect on
  80 parameter /m/ is undefined, otherwise the effects on parameter /m/ are
  81 given in the table:
  82
  83 [table
  84 [[Element][Value]]
  85 [[`m.size()`][`1 + e.mark_count()`]]
  86 [[`m.empty()`][`false`]]
  87 [[`m.prefix().first`][`first`]]
  88 [[`m.prefix().last`][`first`]]
  89 [[`m.prefix().matched`][`false`]]
  90 [[`m.suffix().first`][`last`]]
  91 [[`m.suffix().last`][`last`]]
  92 [[`m.suffix().matched`][`false`]]
  93 [[`m[0].first`][`first`]]
  94 [[`m[0].second`][`last`]]
  95 [[`m[0].matched`][true if a full match was found, and false if it was a
  96 partial match (found as a result of the match_partial flag being set).]]
  97 [[`m[n].first`][For all integers `n < m.size()`, the start 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].second`][For all integers `n < m.size()`, the end of the sequence that
 101       matched sub-expression /n/. Alternatively, if sub-expression /n/ did not
 102       participate in the match, then `last`.]]
 103 [[`m[n].matched`][For all integers `n < m.size()`, true if sub-expression /n/
 104       participated in the match, false otherwise.]]
 105 ]
 106
 107
 108    template <class BidirectionalIterator, class charT, class traits>
 109    bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
 110                   const basic_regex <charT, traits>& e,
 111                   match_flag_type flags = match_default);
 112
 113 [*Effects]: Behaves "as if" by constructing an instance of
 114 `match_results<BidirectionalIterator> what`, and then returning the result of
 115 `regex_match(first, last, what, e, flags)`.
 116
 117    template <class charT, class Allocator, class traits>
 118    bool regex_match(const charT* str, match_results<const charT*, Allocator>& m,
 119                   const basic_regex <charT, traits>& e,
 120                   match_flag_type flags = match_default);
 121
 122 [*Effects]: Returns the result of `regex_match(str, str + char_traits<charT>::length(str), m, e, flags)`.
 123
 124    template <class ST, class SA, class Allocator,
 125             class charT, class traits>
 126    bool regex_match(const basic_string<charT, ST, SA>& s,
 127                   match_results<typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
 128                   const basic_regex <charT, traits>& e,
 129                   match_flag_type flags = match_default);
 130
 131 [*Effects]: Returns the result of `regex_match(s.begin(), s.end(), m, e, flags)`.
 132
 133    template <class charT, class traits>
 134    bool regex_match(const charT* str,
 135                   const basic_regex <charT, traits>& e,
 136                   match_flag_type flags = match_default);
 137
 138 [*Effects]: Returns the result of `regex_match(str, str + char_traits<charT>::length(str), e, flags)`.
 139
 140    template <class ST, class SA, class charT, class traits>
 141    bool regex_match(const basic_string<charT, ST, SA>& s,
 142                   const basic_regex <charT, traits>& e,
 143                   match_flag_type flags = match_default);
 144
 145 [*Effects]: Returns the result of `regex_match(s.begin(), s.end(), e, flags)`.
 146
 147 [h4 Examples]
 148
 149 The following example processes an ftp response:
 150
 151    #include <stdlib.h>
 152    #include <boost/regex.hpp>
 153    #include <string>
 154    #include <iostream>
 155
 156    using namespace boost;
 157
 158    regex expression("([0-9]+)(\\-| |$)(.*)");
 159
 160    // process_ftp:
 161    // on success returns the ftp response code, and fills
 162    // msg with the ftp response message.
 163    int process_ftp(const char* response, std::string* msg)
 164    {
 165       cmatch what;
 166       if(regex_match(response, what, expression))
 167       {
 168          // what[0] contains the whole string
 169          // what[1] contains the response code
 170          // what[2] contains the separator character
 171          // what[3] contains the text message.
 172          if(msg)
 173             msg->assign(what[3].first, what[3].second);
 174          return std::atoi(what[1].first);
 175       }
 176       // failure did not match
 177       if(msg)
 178          msg->erase();
 179       return -1;
 180    }
 181
 182
 183 [endsect]
 184