# std::regex_match

From cppreference.com
< cpp‎ | regex

Defined in header `<regex>` |  |
template< class BidirIt, class Alloc, class CharT, class Traits > bool regex_match( BidirIt first, BidirIt last, std::match_results<BidirIt, Alloc>& m, const std::basic_regex<CharT, Traits>& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); | (1) | (since C++11)
template< class BidirIt, class CharT, class Traits > bool regex_match( BidirIt first, BidirIt last, const std::basic_regex<CharT, Traits>& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); | (2) | (since C++11)
template< class CharT, class Alloc, class Traits > bool regex_match( const CharT* str, std::match_results<const CharT*, Alloc>& m, const std::basic_regex<CharT, Traits>& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); | (3) | (since C++11)
template< class STraits, class SAlloc, class Alloc, class CharT, class Traits > bool regex_match( const std::basic_string<CharT, STraits, SAlloc>& s, std::match_results< typename std::basic_string<CharT, STraits, SAlloc>:: const_iterator, Alloc>& m, const std::basic_regex<CharT, Traits>& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); | (4) | (since C++11)
template< class CharT, class Traits > bool regex_match( const CharT* str, const std::basic_regex<CharT, Traits>& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); | (5) | (since C++11)
template< class STraits, class SAlloc, class CharT, class Traits > bool regex_match( const std::basic_string<CharT, STraits, SAlloc>& s, const std::basic_regex<CharT, Traits>& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); | (6) | (since C++11)
template< class STraits, class SAlloc, class Alloc, class CharT, class Traits > bool regex_match( const std::basic_string<CharT, STraits, SAlloc>&&, std::match_results< typename std::basic_string<CharT, STraits, SAlloc>:: const_iterator, Alloc>&, const std::basic_regex<CharT, Traits>&, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ) = delete; | (7) | (since C++11)

Determines if the regular expression `e` matches the entire target character sequence, which may be specified as std::string, a C-string, or an iterator pair.

1) Determines if there is a match between the regular expression `e` and the entire target character sequence `[first, last)`, taking into account the effect of `flags`. When determining if there is a match, only potential matches that match the entire character sequence are considered. Match results are returned in `m`.
2) Behaves as (1) above, omitting the match results.
3) Returns std::regex_match(str, str + std::char_traits<CharT>::length(str), m, e, flags).
4) Returns std::regex_match(s.begin(), s.end(), m, e, flags).
5) Returns std::regex_match(str, str + std::char_traits<CharT>::length(str), e, flags).
6) Returns std::regex_match(s.begin(), s.end(), e, flags).
7) The overload (4) is prohibited from accepting temporary strings, otherwise this function populates `match_results` `m` with string iterators that become invalid immediately.

Note that `regex_match` will only successfully match a regular expression to an entire character sequence, whereas std::regex_search will successfully match subsequences.

### Parameters

first, last | - | the target character range to apply the regex to, given as iterators
m | - | the match results
str | - | the target string, given as a null-terminated C-style string
s | - | the target string, given as a std::basic_string
e | - | the regular expression
flags | - | flags used to determine how the match will be performed
Type requirements
- `BidirIt` must meet the requirements of LegacyBidirectionalIterator.

### Return value

Returns true if a match exists, false otherwise. In either case, the object `m` is updated, as follows:

If the match does not exist:

m.ready() == true
m.empty() == true
m.size() == 0

If the match exists:

m.ready() | true
m.empty() | false
m.size() | number of marked subexpressions plus 1, that is, 1 + e.mark_count()
m.prefix().first | `first`
m.prefix().second | `first`
m.prefix().matched | false (the match prefix is empty)
m.suffix().first | `last`
m.suffix().second | `last`
m.suffix().matched | false (the match suffix is empty)
m[0].first | `first`
m[0].second | `last`
m[0].matched | true (the entire sequence is matched)
m[n].first | the start of the sequence that matched marked sub-expression n, or `last` if the subexpression did not participate in the match
m[n].second | the end of the sequence that matched marked sub-expression n, or `last` if the subexpression did not participate in the match
m[n].matched | true if sub-expression n participated in the match, false otherwise

### Notes

Because `regex_match` only considers full matches, the same regex may give different matches between `regex_match` and std::regex_search:

    std::regex re("Get|GetValue");
    std::cmatch m;
    std::regex_search("GetValue", m, re);  // returns true, and m[0] contains "Get"
    std::regex_match ("GetValue", m, re);  // returns true, and m[0] contains "GetValue"
    std::regex_search("GetValues", m, re); // returns true, and m[0] contains "Get"
    std::regex_match ("GetValues", m, re); // returns false

### Example

Run this code

    #include <iostream>
    #include <regex>
    #include <string>

    int main()
    {
        // Simple regular expression matching
        const std::string fnames[] = {"foo.txt", "bar.txt", "baz.dat", "zoidberg"};
        const std::regex txt_regex("[a-z]+\\.txt");

        for (const auto &fname : fnames)
            std::cout << fname << ": " << std::regex_match(fname, txt_regex) << '\n';

        // Extraction of a sub-match
        const std::regex base_regex("([a-z]+)\\.txt");
        std::smatch base_match;

        for (const auto &fname : fnames)
        {
            if (std::regex_match(fname, base_match, base_regex))
            {
                // The first sub_match is the whole string; the next
                // sub_match is the first parenthesized expression.
                if (base_match.size() == 2)
                {
                    std::ssub_match base_sub_match = base_match[1];
                    std::string base = base_sub_match.str();
                    std::cout << fname << " has a base of " << base << '\n';
                }
            }
        }

        // Extraction of several sub-matches
        const std::regex pieces_regex("([a-z]+)\\.([a-z]+)");
        std::smatch pieces_match;

        for (const auto &fname : fnames)
        {
            if (std::regex_match(fname, pieces_match, pieces_regex))
            {
                std::cout << fname << '\n';
                for (size_t i = 0; i < pieces_match.size(); ++i)
                {
                    std::ssub_match sub_match = pieces_match[i];
                    std::string piece = sub_match.str();
                    std::cout << "  submatch " << i << ": " << piece << '\n';
                }
            }
        }
    }

Output:

    foo.txt: 1
    bar.txt: 1
    baz.dat: 0
    zoidberg: 0
    foo.txt has a base of foo
    bar.txt has a base of bar
    foo.txt
      submatch 0: foo.txt
      submatch 1: foo
      submatch 2: txt
    bar.txt
      submatch 0: bar.txt
      submatch 1: bar
      submatch 2: txt
    baz.dat
      submatch 0: baz.dat
      submatch 1: baz
      submatch 2: dat

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR | Applied to | Behavior as published | Correct behavior
--- | --- | --- | ---
LWG 2329 | C++11 | `basic_string` rvalues were accepted, which was likely to result in dangling iterators | rejected via a deleted overload

### See also

basic_regex (C++11) | regular expression object (class template)
match_results (C++11) | identifies one regular expression match, including all sub-expression matches (class template)
regex_search (C++11) | attempts to match a regular expression to any part of a character sequence (function template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/regex/regex_match&oldid=149820"