| Home | Libraries | People | FAQ | More

### 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

To do this ... | Use this ...
--- | ---
See if a whole string matches a regex | The ``regex_match()`` algorithm
See if a string contains a sub-string that matches a regex | The ``regex_search()`` algorithm
Replace all sub-strings that match a regex | The ``regex_replace()`` algorithm
Find all the sub-strings that match a regex and step through them one at a time | The ``regex_iterator<>`` class
Split a string into tokens that each match a regex | The ``regex_token_iterator<>`` class
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.