]>
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 Quick Start] | |
9 | ||
10 | You don't need to know much to start being productive with xpressive. Let's begin with | |
11 | the nickel tour of the types and algorithms xpressive provides. | |
12 | ||
13 | [table xpressive's Tool-Box | |
14 | [[Tool] [Description]] | |
15 | [[_basic_regex_] [Contains a compiled regular expression. _basic_regex_ is the most important type in xpressive. Everything you do with xpressive will begin with creating an object of type _basic_regex_.]] | |
16 | [[_match_results_, _sub_match_] [_match_results_ contains the results of a _regex_match_ or _regex_search_ operation. It acts like a vector of _sub_match_ objects. A _sub_match_ object contains a marked sub-expression (also known as a back-reference in Perl). It is basically just a pair of iterators representing the begin and end of the marked sub-expression.]] | |
17 | [[_regex_match_] [Checks to see if a string matches a regex. For _regex_match_ to succeed, the ['whole string] must match the regex, from beginning to end. If you give _regex_match_ a _match_results_, it will write into it any marked sub-expressions it finds.]] | |
18 | [[_regex_search_] [Searches a string to find a sub-string that matches the regex. _regex_search_ will try to find a match at every position in the string, starting at the beginning, and stopping when it finds a match or when the string is exhausted. As with _regex_match_, if you give _regex_search_ a _match_results_, it will write into it any marked sub-expressions it finds.]] | |
19 | [[_regex_replace_] [Given an input string, a regex, and a substitution string, _regex_replace_ builds a new string by replacing those parts of the input string that match the regex with the substitution string. The substitution string can contain references to marked sub-expressions.]] | |
20 | [[_regex_iterator_] [An STL-compatible iterator that makes it easy to find all the places in a string that match a regex. Dereferencing a _regex_iterator_ returns a _match_results_. Incrementing a _regex_iterator_ finds the next match.]] | |
21 | [[_regex_token_iterator_] [Like _regex_iterator_, except dereferencing a _regex_token_iterator_ returns a string. By default, it will return the whole sub-string that the regex matched, but it can be configured to return any or all of the marked sub-expressions one at a time, or even the parts of the string that ['didn't] match the regex.]] | |
22 | [[_regex_compiler_] [A factory for _basic_regex_ objects. It "compiles" a string into a regular expression. You will not usually have to deal directly with _regex_compiler_ because the _basic_regex_ class has a factory method that uses _regex_compiler_ internally. But if you need to do anything fancy like create a _basic_regex_ object with a different `std::locale`, you will need to use a _regex_compiler_ explicitly.]] | |
23 | ] | |
24 | ||
25 | Now that you know a bit about the tools xpressive provides, you can pick the right tool for you | |
26 | by answering the following two questions: | |
27 | ||
28 | # What ['iterator] type will you use to traverse your data? | |
29 | # What do you want to ['do] to your data? | |
30 | ||
31 | [h2 Know Your Iterator Type] | |
32 | ||
33 | Most of the classes in xpressive are templates that are parameterized on the iterator type. | |
34 | xpressive defines some common typedefs to make the job of choosing the right types easier. | |
35 | You can use the table below to find the right types based on the type of your iterator. | |
36 | ||
37 | [table xpressive Typedefs vs. Iterator Types | |
38 | [[] [std::string::const_iterator] [char const *] [std::wstring::const_iterator] [wchar_t const *]] | |
39 | [[_basic_regex_] [`sregex`] [`cregex`] [`wsregex`] [`wcregex`]] | |
40 | [[_match_results_] [`smatch`] [`cmatch`] [`wsmatch`] [`wcmatch`]] | |
41 | [[_regex_compiler_] [`sregex_compiler`] [`cregex_compiler`] [`wsregex_compiler`] [`wcregex_compiler`]] | |
42 | [[_regex_iterator_] [`sregex_iterator`] [`cregex_iterator`] [`wsregex_iterator`] [`wcregex_iterator`]] | |
43 | [[_regex_token_iterator_] [`sregex_token_iterator`] [`cregex_token_iterator`] [`wsregex_token_iterator`] [`wcregex_token_iterator`]] | |
44 | ] | |
45 | ||
46 | You should notice the systematic naming convention. Many of these types are used together, so the | |
47 | naming convention helps you to use them consistently. For instance, if you have a `sregex`, you | |
48 | should also be using a `smatch`. | |
49 | ||
50 | If you are not using one of those four iterator types, then you can use the templates directly and | |
51 | specify your iterator type. | |
52 | ||
53 | [h2 Know Your Task] | |
54 | ||
55 | Do you want to find a pattern once? Many times? Search and replace? xpressive has tools for all | |
56 | that and more. Below is a quick reference: | |
57 | ||
58 | [table Tasks and Tools | |
59 | [[To do this ...] [Use this ...]] | |
60 | [[__tip__ [link boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex See if a whole string matches a regex]] [The _regex_match_ algorithm]] | |
61 | [[__tip__ [link boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex See if a string contains a sub-string that matches a regex]] [The _regex_search_ algorithm]] | |
62 | [[__tip__ [link boost_xpressive.user_s_guide.examples.replace_all_sub_strings_that_match_a_regex Replace all sub-strings that match a regex]] [The _regex_replace_ algorithm]] | |
63 | [[__tip__ [link boost_xpressive.user_s_guide.examples.find_all_the_sub_strings_that_match_a_regex_and_step_through_them_one_at_a_time Find all the sub-strings that match a regex and step through them one at a time]] [The _regex_iterator_ class]] | |
64 | [[__tip__ [link boost_xpressive.user_s_guide.examples.split_a_string_into_tokens_that_each_match_a_regex Split a string into tokens that each match a regex]] [The _regex_token_iterator_ class]] | |
65 | [[__tip__ [link boost_xpressive.user_s_guide.examples.split_a_string_using_a_regex_as_a_delimiter Split a string using a regex as a delimiter]] [The _regex_token_iterator_ class]] | |
66 | ] | |
67 | ||
68 | These algorithms and classes are described in excruciating detail in the Reference section. | |
69 | ||
70 | [tip Try clicking on a task in the table above to see a complete example | |
71 | program that uses xpressive to solve that particular task.] | |
72 | ||
73 | [endsect] |