]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |