View source for cpp/regex

{{title|Regular expressions library}}
{{cpp/regex/navbar}}

{{dsc begin}}
{{dsc header | regex }}
{{dsc end}}

The regular expressions library provides a class that represents [[enwiki:Regular expression|regular expressions]], which are a kind of mini-language used to perform pattern matching within strings. Almost all operations with regexes can be characterized by operating on several of the following objects:

* '''Target sequence'''. The character sequence that is searched for a pattern. This may be a range specified by two iterators, a null-terminated character string or a {{lc|std::string}}.

* '''Pattern'''. This is the regular expression itself. It determines what constitutes a match. It is an object of type {{lc|std::basic_regex}}, constructed from a string with special syntax. See [[cpp/regex/syntax_option_type | syntax_option_type]] for the description of supported syntax variations.

* '''Matched array'''. The information about matches may be retrieved as an object of type {{lc|std::match_results}}.

* '''Replacement string'''. This is a string that determines how to replace the matches, see [[cpp/regex/match_flag_type | match_flag_type]] for the description of supported syntax variations. 

===Main classes===

These classes encapsulate a regular expression and the results of matching a regular expression within a target sequence of characters.

{{dsc begin}}
{{dsc inc | cpp/regex/dsc basic_regex }}
{{dsc inc | cpp/regex/dsc sub_match }}
{{dsc inc | cpp/regex/dsc match_results }}
{{dsc end}}

===Algorithms===

These functions are used to apply the regular expression encapsulated in a regex to a target sequence of characters.

{{dsc begin}}
{{dsc inc | cpp/regex/dsc regex_match }}
{{dsc inc | cpp/regex/dsc regex_search }}
{{dsc inc | cpp/regex/dsc regex_replace }}
{{dsc end}}

===Iterators===

The regex iterators are used to traverse the entire set of regular expression matches found within a sequence.

{{dsc begin}}
{{dsc inc | cpp/regex/dsc regex_iterator }}
{{dsc inc | cpp/regex/dsc regex_token_iterator }}
{{dsc end}}

===Exceptions===

This class defines the type of objects thrown as exceptions to report errors from the regular expressions library.

{{dsc begin}}
{{dsc inc | cpp/regex/dsc regex_error }}
{{dsc end}}

===Traits===

The regex traits class is used to encapsulate the localizable aspects of a regex.

{{dsc begin}}
{{dsc inc | cpp/regex/dsc regex_traits }}
{{dsc end}}

===Constants===

{{dsc begin}}
{{dsc namespace | std::regex_constants }}
{{dsc inc | cpp/regex/dsc syntax_option_type}}
{{dsc inc | cpp/regex/dsc match_flag_type}}
{{dsc inc | cpp/regex/dsc error_type}}
{{dsc end}}

===Example===
{{example
 | code=
#include <iostream>
#include <iterator>
#include <string>
#include <regex>

int main()
{
    std::string s = "Some people, when confronted with a problem, think "
        "\"I know, I'll use regular expressions.\" "
        "Now they have two problems.";

    std::regex self_regex("REGULAR EXPRESSIONS",
            std::regex_constants::ECMAScript {{!}} std::regex_constants::icase);
    if (std::regex_search(s, self_regex)) {
        std::cout << "Text contains the phrase 'regular expressions'\n";
    }

    std::regex word_regex("(\\S+)");
    auto words_begin = 
        std::sregex_iterator(s.begin(), s.end(), word_regex);
    auto words_end = std::sregex_iterator();

    std::cout << "Found "
              << std::distance(words_begin, words_end)
              << " words\n";

    const int N = 6;
    std::cout << "Words longer than " << N << " characters:\n";
    for (std::sregex_iterator i = words_begin; i != words_end; ++i) {
        std::smatch match = *i;
        std::string match_str = match.str();
        if (match_str.size() > N) {
            std::cout << "  " << match_str << '\n';
        }
    }

    std::regex long_word_regex("(\\w{7,})");
    std::string new_s = std::regex_replace(s, long_word_regex, "[$&]");
    std::cout << new_s << '\n';
}
 | output=
Text contains the phrase 'regular expressions'
Found 19 words
Words longer than 6 characters:
  people,
  confronted
  problem,
  regular
  expressions."
  problems.
Some people, when [confronted] with a [problem], think 
"I know, I'll use [regular] [expressions]." Now they have two [problems].
}}

[[ar:cpp/regex]]
[[de:cpp/regex]]
[[es:cpp/regex]]
[[fr:cpp/regex]]
[[it:cpp/regex]]
[[ja:cpp/regex]]
[[ko:cpp/regex]]
[[pt:cpp/regex]]
[[ru:cpp/regex]]
[[zh:cpp/regex]]