Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

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 1.1. 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:

  1. What iterator type will you use to traverse your data?
  2. What do you want to do to your data?

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 1.2. 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.

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 1.3. Tasks and Tools


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

[Tip] Tip

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


PrevUpHomeNext