74 lines
7.0 KiB
Plaintext
74 lines
7.0 KiB
Plaintext
[/
|
|
/ 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]
|