]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2008 Eric Niebler | |
3 | / | |
4 | / Distributed under the Boost Software License, Version 1.0. (See accompanying | |
5 | / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | /] | |
7 | ||
8 | [section Matching and Searching] | |
9 | ||
10 | [h2 Overview] | |
11 | ||
12 | Once you have created a regex object, you can use the _regex_match_ and _regex_search_ algorithms to find patterns | |
13 | in strings. This page covers the basics of regex matching and searching. In all cases, if you are familiar with | |
14 | how _regex_match_ and _regex_search_ in the _regexpp_ library work, xpressive's versions work the same way. | |
15 | ||
16 | [h2 Seeing if a String Matches a Regex] | |
17 | ||
18 | The _regex_match_ algorithm checks to see if a regex matches a given input. | |
19 | ||
20 | [warning The _regex_match_ algorithm will only report success if the regex matches the ['whole input], | |
21 | from beginning to end. If the regex matches only a part of the input, _regex_match_ will return false. If you | |
22 | want to search through the string looking for sub-strings that the regex matches, use the _regex_search_ | |
23 | algorithm.] | |
24 | ||
25 | The input can be a bidirectional range such as `std::string`, a C-style null-terminated string or a pair of | |
26 | iterators. In all cases, the type of the iterator used to traverse the input sequence must match the iterator | |
27 | type used to declare the regex object. (You can use the table in the | |
28 | [link boost_xpressive.user_s_guide.quick_start.know_your_iterator_type Quick Start] to find the correct regex | |
29 | type for your iterator.) | |
30 | ||
31 | cregex cre = +_w; // this regex can match C-style strings | |
32 | sregex sre = +_w; // this regex can match std::strings | |
33 | ||
34 | if( regex_match( "hello", cre ) ) // OK | |
35 | { /*...*/ } | |
36 | ||
37 | if( regex_match( std::string("hello"), sre ) ) // OK | |
38 | { /*...*/ } | |
39 | ||
40 | if( regex_match( "hello", sre ) ) // ERROR! iterator mis-match! | |
41 | { /*...*/ } | |
42 | ||
43 | The _regex_match_ algorithm optionally accepts a _match_results_ struct as an out parameter. If given, the _regex_match_ | |
44 | algorithm fills in the _match_results_ struct with information about which parts of the regex matched which | |
45 | parts of the input. | |
46 | ||
47 | cmatch what; | |
48 | cregex cre = +(s1= _w); | |
49 | ||
50 | // store the results of the regex_match in "what" | |
51 | if( regex_match( "hello", what, cre ) ) | |
52 | { | |
53 | std::cout << what[1] << '\n'; // prints "o" | |
54 | } | |
55 | ||
56 | The _regex_match_ algorithm also optionally accepts a _match_flag_type_ bitmask. With _match_flag_type_, you can | |
57 | control certain aspects of how the match is evaluated. See the _match_flag_type_ reference for a complete list | |
58 | of the flags and their meanings. | |
59 | ||
60 | std::string str("hello"); | |
61 | sregex sre = bol >> +_w; | |
62 | ||
63 | // match_not_bol means that "bol" should not match at [begin,begin) | |
64 | if( regex_match( str.begin(), str.end(), sre, regex_constants::match_not_bol ) ) | |
65 | { | |
66 | // should never get here!!! | |
67 | } | |
68 | ||
69 | Click [link boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex here] to see a complete | |
70 | example program that shows how to use _regex_match_. And check the _regex_match_ reference to see a complete list | |
71 | of the available overloads. | |
72 | ||
73 | [h2 Searching for Matching Sub-Strings] | |
74 | ||
75 | Use _regex_search_ when you want to know if an input sequence contains a sub-sequence that a regex matches. | |
76 | _regex_search_ will try to match the regex at the beginning of the input sequence and scan forward in the | |
77 | sequence until it either finds a match or exhausts the sequence. | |
78 | ||
79 | In all other regards, _regex_search_ behaves like _regex_match_ ['(see above)]. In particular, it can operate | |
80 | on a bidirectional range such as `std::string`, C-style null-terminated strings or iterator ranges. The same | |
81 | care must be taken to ensure that the iterator type of your regex matches the iterator type of your input | |
82 | sequence. As with _regex_match_, you can optionally provide a _match_results_ struct to receive the results | |
83 | of the search, and a _match_flag_type_ bitmask to control how the match is evaluated. | |
84 | ||
85 | Click [link boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex here] | |
86 | to see a complete example program that shows how to use _regex_search_. And check the _regex_search_ reference to | |
87 | see a complete list of the available overloads. | |
88 | ||
89 | [endsect] |