boost_1_45_0/libs/xpressive/doc/quick_start.qbk

[/
 / Copyright (c) 2008 Eric Niebler
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section Quick Start]

You don't need to know much to start being productive with xpressive. Let's begin with
the nickel tour of the types and algorithms xpressive provides.

[table xpressive's Tool-Box
    [[Tool]                             [Description]]
    [[_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_.]]
    [[_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.]]
    [[_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.]]
    [[_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.]]
    [[_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.]]
    [[_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.]]
    [[_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.]]
    [[_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.]]
]

Now that you know a bit about the tools xpressive provides, you can pick the right tool for you
by answering the following two questions:

# What ['iterator] type will you use to traverse your data?
# What do you want to ['do] to your data?

[h2 Know Your Iterator Type]

Most of the classes in xpressive are templates that are parameterized on the iterator type.
xpressive defines some common typedefs to make the job of choosing the right types easier.
You can use the table below to find the right types based on the type of your iterator.

[table xpressive Typedefs vs. Iterator Types
    [[]                         [std::string::const_iterator]       [char const *]              [std::wstring::const_iterator]      [wchar_t const *]]
    [[_basic_regex_]            [`sregex`]                          [`cregex`]                  [`wsregex`]                         [`wcregex`]]
    [[_match_results_]          [`smatch`]                          [`cmatch`]                  [`wsmatch`]                         [`wcmatch`]]
    [[_regex_compiler_]         [`sregex_compiler`]                 [`cregex_compiler`]         [`wsregex_compiler`]                [`wcregex_compiler`]]
    [[_regex_iterator_]         [`sregex_iterator`]                 [`cregex_iterator`]         [`wsregex_iterator`]                [`wcregex_iterator`]]
    [[_regex_token_iterator_]   [`sregex_token_iterator`]           [`cregex_token_iterator`]   [`wsregex_token_iterator`]          [`wcregex_token_iterator`]]
]

You should notice the systematic naming convention. Many of these types are used together, so the
naming convention helps you to use them consistently. For instance, if you have a `sregex`, you
should also be using a `smatch`.

If you are not using one of those four iterator types, then you can use the templates directly and
specify your iterator type.

[h2 Know Your Task]

Do you want to find a pattern once? Many times? Search and replace? xpressive has tools for all
that and more. Below is a quick reference:

[table Tasks and Tools
    [[To do this ...]                                                                                                                                                                       [Use this ...]]
    [[__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]]
    [[__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]]
    [[__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]]
    [[__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]]
    [[__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]]
    [[__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]]
]

These algorithms and classes are described in excruciating detail in the Reference section.

[tip Try clicking on a task in the table above to see a complete example
program that uses xpressive to solve that particular task.]

[endsect]