12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273 |
- [/
- / 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]
|