Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/regex/regex match"

From cppreference.com
< cpp‎ | regex
m (links to regex grammar)
m (Wording fix.)
 
(17 intermediate revisions by 11 users not shown)
Line 2: Line 2:
 
{{cpp/regex/navbar}}
 
{{cpp/regex/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | regex}}
+
{{dcl header|regex}}
−
{{dcl | num=1 | since=c++11 | 1=
+
{{dcl|num=1|since=c++11|1=
−
template< class BidirIt,  
+
template< class BidirIt, class Alloc, class CharT, class Traits >
−
          class Alloc, class CharT, class Traits >
+
 
bool regex_match( BidirIt first, BidirIt last,
 
bool regex_match( BidirIt first, BidirIt last,
−
                   std::match_results<BidirIt,Alloc>& m,
+
                   std::match_results<BidirIt, Alloc>& m,
−
                   const std::basic_regex<CharT,Traits>& e,
+
                   const std::basic_regex<CharT, Traits>& e,
−
                   std::regex_constants::match_flag_type flags =  
+
                   std::regex_constants::match_flag_type flags =
 
                       std::regex_constants::match_default );
 
                       std::regex_constants::match_default );
 
}}
 
}}
−
{{dcl | num=2 | since=c++11 | 1=
+
{{dcl|num=2|since=c++11|1=
−
template< class BidirIt,  
+
template< class BidirIt, class CharT, class Traits >
−
          class CharT, class Traits >
+
 
bool regex_match( BidirIt first, BidirIt last,
 
bool regex_match( BidirIt first, BidirIt last,
−
                   const std::basic_regex<CharT,Traits>& e,
+
                   const std::basic_regex<CharT, Traits>& e,
−
                   std::regex_constants::match_flag_type flags =  
+
                   std::regex_constants::match_flag_type flags =
 
                       std::regex_constants::match_default );
 
                       std::regex_constants::match_default );
 
}}
 
}}
−
{{dcl | num=3 | since=c++11 | 1=
+
{{dcl|num=3|since=c++11|1=
 
template< class CharT, class Alloc, class Traits >
 
template< class CharT, class Alloc, class Traits >
 
bool regex_match( const CharT* str,
 
bool regex_match( const CharT* str,
−
                   std::match_results<const CharT*,Alloc>& m,
+
                   std::match_results<const CharT*, Alloc>& m,
−
                   const std::basic_regex<CharT,Traits>& e,
+
                   const std::basic_regex<CharT, Traits>& e,
−
                   std::regex_constants::match_flag_type flags =  
+
                   std::regex_constants::match_flag_type flags =
 
                       std::regex_constants::match_default );
 
                       std::regex_constants::match_default );
 
}}
 
}}
−
{{dcl | num=4 | since=c++11 | 1=
+
{{dcl|num=4|since=c++11|1=
−
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 );
+
−
}}
+
−
{{dcl | num=5 | since=c++11 | 1=
+
 
template< class CharT, class Traits >
 
template< class CharT, class Traits >
−
bool regex_match( const CharT* str,
+
bool regex_match( const CharT* str, const std::basic_regex<CharT, Traits>& e,
−
                  const std::basic_regex<CharT,Traits>& e,
+
                   std::regex_constants::match_flag_type flags =
−
                   std::regex_constants::match_flag_type flags =  
+
 
                       std::regex_constants::match_default );
 
                       std::regex_constants::match_default );
 
}}
 
}}
−
{{dcl | num=6 | since=c++11 | 1=
+
{{dcl|num=5|since=c++11|1=
−
template< class STraits, class SAlloc,  
+
template< class STraits, class SAlloc, class Alloc,
 
           class CharT, class Traits >
 
           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 );
 +
}}
 +
{{dcl|num=6|since=c++11|1=
 +
template< class STraits, class SAlloc, class CharT, class Traits >
 
bool regex_match( const std::basic_string<CharT, STraits, SAlloc>& s,
 
bool regex_match( const std::basic_string<CharT, STraits, SAlloc>& s,
−
                   const std::basic_regex<CharT,Traits>& e,
+
                   const std::basic_regex<CharT, Traits>& e,
−
                   std::regex_constants::match_flag_type flags =  
+
                   std::regex_constants::match_flag_type flags =
 
                       std::regex_constants::match_default );
 
                       std::regex_constants::match_default );
 
}}
 
}}
−
{{dcl | num=7 | since=c++14 | 1=
+
{{dcl|num=7|since=c++11|1=
−
template< class STraits, class SAlloc,  
+
template< class STraits, class SAlloc, class Alloc,
−
          class Alloc, class CharT, class Traits >
+
          class CharT, class Traits >
−
bool regex_match( const std::basic_string<CharT,STraits,SAlloc>&&,
+
bool regex_match
−
                  std::match_results<
+
    ( const std::basic_string<CharT, STraits, SAlloc>&&,
−
                      typename std::basic_string<CharT,STraits,SAlloc>::const_iterator,
+
      std::match_results
−
                      Alloc
+
          <typename std::basic_string<CharT, STraits, SAlloc>::const_iterator,
−
                  >&,
+
          Alloc>&,
−
                  const std::basic_regex<CharT,Traits>&,
+
      const std::basic_regex<CharT, Traits>&,
−
                  std::regex_constants::match_flag_type flags =  
+
      std::regex_constants::match_flag_type flags =
−
                      std::regex_constants::match_default ) = delete;
+
          std::regex_constants::match_default ) = delete;
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
Determines if the regular expression {{tt|el}} matches the given target.  
+
Determines if the regular expression {{c|e}} matches the entire target character sequence. The detailed match result is stored in {{c|m}} (if present).
  
−
@1@ Determines if there is a match between the regular expression {{tt|e}} and the entire target character sequence {{tt|[first,last)}}, taking into account the effect of {{tt|flags}}. Match results are returned in {{tt|m}}.
+
@1,2@ The target character sequence is represented by the range {{range|first|last}}.
−
 
+
{{rev begin}}
−
@2@ Behaves as (1) above, omitting the match results.
+
{{rev|until=c++23|
−
 
+
If {{tt|BidirIt}} does not satisfy the requirements of {{named req|BidirectionalIterator}}, the behavior is undefined.
−
@3@ Returns {{c|std::regex_match(str, str + std::char_traits<charT>::length(str), m, e, flags)}}.
+
}}
 +
{{rev|since=c++23|
 +
If {{tt|BidirIt}} does not model {{lconcept|bidirectional_iterator}}, the behavior is undefined.
 +
}}
 +
{{rev end}}
  
−
@4@ Returns {{c|std::regex_match(s.begin(), s.end(), m, e, flags)}}.
+
@3,4@ The target character sequence is represented by the range {{range|str|str + std::char_traits<CharT>::length(str)}}.
  
−
@5@ Returns {{c|std::regex_match(str, str + std::char_traits<charT>::length(str), e, flags)}}.
+
@5,6@ The target character sequence is represented by the string {{c|s}}.
  
−
@6@ Returns {{c|std::regex_match(s.begin(), s.end(), e, flags)}}.
+
@7@ The target character sequence cannot be represented by a {{lc|std::string}} rvalue.
  
−
@7@ The overload 4 is prohibited from accepting temporary strings, otherwise this function populates match_results m with string iterators that become invalid immediately.
+
If the match does not exist, the following expressions involving {{c|m}} (if exists) should yield the specified values:
 +
{|class="wikitable" style="text-align: center;"
 +
!{{nbsp}}Expression{{nbsp}}
 +
!{{nbsp}}Value{{nbsp}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/ready}}{{c/core|()}}}}
 +
|{{c|true}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/size}}{{c/core|()}}}}
 +
|{{c|0}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/empty}}{{c/core|()}}}}
 +
|{{c|true}}
 +
|}
  
−
Note that {{tt|regex_match}} will only successfully match a regular expression to an ''entire'' character sequence, whereas {{lc|std::regex_search}} will successfully match subsequences.
+
If the match exists, given any integer in {{open range|​0|m.size()}} as {{c|n}}, the following expressions involving {{c|m}} should yield the specified values for each overload listed below:
 +
{|class="wikitable" style="text-align: center;"
 +
!rowspan=2|{{nbsp|6}}Expression{{nbsp|6}}
 +
!colspan=3|Value
 +
|-
 +
!{{nbsp|11}}Overload {{v|1}}{{nbsp|11}}
 +
!{{nbsp|11}}Overload {{v|3}}{{nbsp|11}}
 +
!{{nbsp|11}}Overload {{v|5}}{{nbsp|11}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/ready}}{{c/core|()}}}}
 +
|colspan=3|{{c|true}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/size}}{{c/core|()}}}}
 +
|colspan=3|{{box|{{c/core|1 + e.}}{{ltt|cpp/regex/basic_regex/mark_count}}{{c/core|()}}}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/empty}}{{c/core|()}}}}
 +
|colspan=3|{{c|false}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/prefix}}{{c/core|().first}}}}
 +
|rowspan=2|{{c|first}}
 +
|rowspan=2|{{c|str}}
 +
|rowspan=2|{{c|s.begin()}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/prefix}}{{c/core|().second}}}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/prefix}}{{c/core|().matched}}}}
 +
|colspan=3|{{nbsp|4}}{{c|false}}<ref>The match prefix is empty.</ref>
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/suffix}}{{c/core|().first}}}}
 +
|rowspan=2|{{c|last}}
 +
|rowspan=2|<span style="text-align: start;">{{c multi|std::char_traits<CharT>::|    length(str) + str}}</span>
 +
|rowspan=2|{{c|s.end()}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/suffix}}{{c/core|().second}}}}
 +
|-
 +
|{{box|{{c/core|m.}}{{ltt|cpp/regex/match_results/suffix}}{{c/core|().matched}}}}
 +
|colspan=3|{{nbsp|4}}{{c|false}}<ref>The match suffix is empty.</ref>
 +
|-
 +
|{{box|{{c/core|m}}{{ltt|cpp/regex/match_results/operator at|[0]}}{{c/core|.first}}}}
 +
|{{c|first}}
 +
|{{c|str}}
 +
|{{c|s.begin()}}
 +
|-
 +
|{{box|{{c/core|m}}{{ltt|cpp/regex/match_results/operator at|[0]}}{{c/core|.second}}}}
 +
|{{c|last}}
 +
|<span style="text-align: start;">{{c multi|std::char_traits<CharT>::|    length(str) + str}}</span>
 +
|{{c|s.end()}}
 +
|-
 +
|{{box|{{c/core|m}}{{ltt|cpp/regex/match_results/operator at|[0]}}{{c/core|.matched}}}}
 +
|colspan=3|{{nbsp|4}}{{c|true}}<ref>The entire sequence is matched.</ref>
 +
|-
 +
|{{box|{{c/core|m}}{{ltt|cpp/regex/match_results/operator at|[n]}}{{c/core|.first}}}}
 +
|colspan=3|
 +
* {{c|last}} if [[cpp/regex/ecmascript#Sub-expressions|marked sub-expression]] {{c|n}} did not participate in the match
 +
* the start of the sequence otherwise matching sub-expression {{c|n}} otherwise
 +
|-
 +
|{{box|{{c/core|m}}{{ltt|cpp/regex/match_results/operator at|[n]}}{{c/core|.second}}}}
 +
|colspan=3|
 +
* {{c|last}} if [[cpp/regex/ecmascript#Sub-expressions|marked sub-expression]] {{c|n}} did not participate in the match
 +
* the end of the sequence otherwise matching sub-expression {{c|n}} otherwise
 +
|-
 +
|{{box|{{c/core|m}}{{ltt|cpp/regex/match_results/operator at|[n]}}{{c/core|.matched}}}}
 +
|colspan=3|
 +
* {{c|false}} if [[cpp/regex/ecmascript#Sub-expressions|marked sub-expression]] {{c|n}} did not participate in the match
 +
* {{c|true}} otherwise
 +
|}
 +
<references/>
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | first, last | the target character range to apply the regex to, given as iterators}}
+
{{par|first, last|the target character range}}
−
{{par | m | the match results}}
+
{{par|str|the target null-terminated C-style string}}
−
{{par | str | the target string, given as a null-terminated C-style string}}
+
{{par|s|the target {{lc|std::basic_string}}}}
−
{{par | s | the target string, given as a {{lc|std::basic_string}} }}
+
{{par|m|the match results}}
−
{{par | e | the regular expression}}
+
{{par|e|the regular expression}}
−
{{par | flags | flags used to determine how the match will be performed}}
+
{{par|flags|flags used to determine how the match will be performed}}
−
{{par hreq}}
+
−
{{par req concept | BidirIt | BidirectionalIterator}}
+
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
Returns {{c|true}} if a match exists, {{c|false}} otherwise. In either case, the object {{tt|m}} is updated, as follows:
+
Returns {{c|true}} if the entire target sequence matches {{c|e}}, {{c|false}} otherwise.
  
−
If the match does not exist:
+
===Notes===
−
{{dsc begin}}
+
Because {{tt|regex_match}} only considers full matches, the same regex may give different matches between {{tt|regex_match}} and {{lc|std::regex_search}}:
−
{{dsc | {{c|1=m.ready() == true}} }}
+
{{source|1=
−
{{dsc | {{c|1=m.empty() == true}} }}
+
std::regex re("Get{{!}}GetValue");
−
{{dsc | {{c|1=m.size() == 0}} }}
+
std::cmatch m;
−
{{dsc end}}
+
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"
−
If the match exists:
+
std::regex_search("GetValues", m, re); // returns true, and m[0] contains "Get"
−
{{dsc begin}}
+
std::regex_match ("GetValues", m, re); // returns false
−
{{dsc | {{c|m.ready()}} | {{c|true}} }}
+
}}
−
{{dsc | {{c|m.empty()}} | {{c|false}} }}
+
−
{{dsc | {{c|m.size()}}  | [[cpp/regex/ecmascript#Sub-expressions|number of marked subexpressions]] plus 1, that is, {{c|1+e.mark_count()}}}}
+
−
{{dsc | {{c|m.prefix().first}} | {{tt|first}} }}
+
−
{{dsc | {{c|m.prefix().second}} | {{tt|first}} }}
+
−
{{dsc | {{c|m.prefix().matched}} | {{c|false}} (the match prefix is empty) }}
+
−
{{dsc | {{c|m.suffix().first}} | {{tt|last}}}}
+
−
{{dsc | {{c|m.suffix().second}} | {{tt|last}}}}
+
−
{{dsc | {{c|m.suffix().matched}} | {{c|false}} (the match suffix is empty) }}
+
−
{{dsc | {{c|m[0].first}} | {{tt|first}} }}
+
−
{{dsc | {{c|m[0].second}} | {{tt|last}} }}
+
−
{{dsc | {{c|m[0].matched}} | {{c|true}} (the entire sequence is matched)}}
+
−
{{dsc | {{c|1=m[n].first}} | the start of the sequence that matched [[cpp/regex/ecmascript#Sub-expressions|marked sub-expression]] n, or {{tt|last}} if the subexpression did not participate in the match}}
+
−
{{dsc | {{c|1=m[n].second}} | the end of the sequence that matched [[cpp/regex/ecmascript#Sub-expressions|marked sub-expression]] n, or {{tt|last}} if the subexpression did not participate in the match}}
+
−
{{dsc | {{c|1=m[n].matched}} | {{c|true}} if sub-expression n participated in the match, {{c|false}} otherwise}}
+
−
{{dsc end}}
+
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| code=
+
|code=
 +
#include <cstddef>
 
#include <iostream>
 
#include <iostream>
 +
#include <regex>
 
#include <string>
 
#include <string>
−
#include <regex>
 
  
 
int main()
 
int main()
 
{
 
{
 
     // Simple regular expression matching
 
     // Simple regular expression matching
−
     std::string fnames[] = {"foo.txt", "bar.txt", "baz.dat", "zoidberg"};
+
     const std::string fnames[] = {"foo.txt", "bar.txt", "baz.dat", "zoidberg"};
−
     std::regex txt_regex("[a-z]+\\.txt");
+
     const std::regex txt_regex("[a-z]+\\.txt");
−
 
+
   
−
     for (const auto &fname : fnames) {
+
     for (const auto& fname : fnames)
 
         std::cout << fname << ": " << std::regex_match(fname, txt_regex) << '\n';
 
         std::cout << fname << ": " << std::regex_match(fname, txt_regex) << '\n';
−
     } 
+
      
−
 
+
 
     // Extraction of a sub-match
 
     // Extraction of a sub-match
−
     std::regex base_regex("([a-z]+)\\.txt");
+
     const std::regex base_regex("([a-z]+)\\.txt");
 
     std::smatch base_match;
 
     std::smatch base_match;
−
 
+
   
−
     for (const auto &fname : fnames) {
+
     for (const auto& fname : fnames)
−
         if (std::regex_match(fname, base_match, base_regex)) {
+
         if (std::regex_match(fname, base_match, base_regex))
 
             // The first sub_match is the whole string; the next
 
             // The first sub_match is the whole string; the next
 
             // sub_match is the first parenthesized expression.
 
             // sub_match is the first parenthesized expression.
−
             if (base_match.size() == 2) {
+
             if (base_match.size() == 2)
 +
            {
 
                 std::ssub_match base_sub_match = base_match[1];
 
                 std::ssub_match base_sub_match = base_match[1];
 
                 std::string base = base_sub_match.str();
 
                 std::string base = base_sub_match.str();
 
                 std::cout << fname << " has a base of " << base << '\n';
 
                 std::cout << fname << " has a base of " << base << '\n';
 
             }
 
             }
−
        }
+
      
−
     }
+
−
 
+
 
     // Extraction of several sub-matches
 
     // Extraction of several sub-matches
−
     std::regex pieces_regex("([a-z]+)\\.([a-z]+)");
+
     const std::regex pieces_regex("([a-z]+)\\.([a-z]+)");
 
     std::smatch pieces_match;
 
     std::smatch pieces_match;
−
 
+
   
−
     for (const auto &fname : fnames) {
+
     for (const auto& fname : fnames)
−
         if (std::regex_match(fname, pieces_match, pieces_regex)) {
+
         if (std::regex_match(fname, pieces_match, pieces_regex))
 +
        {
 
             std::cout << fname << '\n';
 
             std::cout << fname << '\n';
−
             for (size_t i = 0; i < pieces_match.size(); ++i) {
+
             for (std::size_t i = 0; i < pieces_match.size(); ++i)
 +
            {
 
                 std::ssub_match sub_match = pieces_match[i];
 
                 std::ssub_match sub_match = pieces_match[i];
 
                 std::string piece = sub_match.str();
 
                 std::string piece = sub_match.str();
 
                 std::cout << "  submatch " << i << ": " << piece << '\n';
 
                 std::cout << "  submatch " << i << ": " << piece << '\n';
−
             }  
+
             }
−
         }  
+
         }
−
    } 
+
 
}
 
}
−
| output=
+
|output=
 
foo.txt: 1
 
foo.txt: 1
 
bar.txt: 1
 
bar.txt: 1
Line 196: Line 258:
 
   submatch 2: dat
 
   submatch 2: dat
 
}}
 
}}
 +
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=2205|std=C++11|before={{c|n}} could be zero in the postcondition|after=can only be positive}}
 +
{{dr list item|wg=lwg|dr=2273|std=C++11|before=it was unclear whether partial matches are considered|after=only considers full matches}}
 +
{{dr list item|wg=lwg|dr=2329|std=C++11|before=overload {{v|5}} accepted {{tt|basic_string}} rvalues,<br>which could result in dangling iterators|after=rejected via deleted overload {{v|7}}}}
 +
{{dr list end}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/regex/dsc basic_regex}}
+
{{dsc inc|cpp/regex/dsc basic_regex}}
−
{{dsc inc | cpp/regex/dsc match_results}}
+
{{dsc inc|cpp/regex/dsc match_results}}
−
{{dsc inc | cpp/regex/dsc regex_search}}
+
{{dsc inc|cpp/regex/dsc regex_search}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/regex/regex match]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/regex/regex match]]
+
−
[[fr:cpp/regex/regex match]]
+
−
[[it:cpp/regex/regex match]]
+
−
[[ja:cpp/regex/regex match]]
+
−
[[pt:cpp/regex/regex match]]
+
−
[[ru:cpp/regex/regex match]]
+
−
[[zh:cpp/regex/regex match]]
+

Latest revision as of 18:55, 14 November 2024

 
C++
 
Regular expressions library
Classes
(C++11)
(C++11)
(C++11)
Algorithms
regex_match
(C++11)
(C++11)
(C++11)
Iterators
(C++11)
(C++11)
Exceptions
(C++11)
Traits
(C++11)
Constants
(C++11)
(C++11)
(C++11)
Regex Grammar
(C++11)
 
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 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 );
 (4) (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 );
 (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. The detailed match result is stored in m (if present).

1,2) The target character sequence is represented by the range [first, last).

If BidirIt does not satisfy the requirements of LegacyBidirectionalIterator, the behavior is undefined.

(until C++23)

If BidirIt does not model bidirectional_iterator, the behavior is undefined.

(since C++23)
3,4) The target character sequence is represented by the range [str, str + std::char_traits<CharT>::length(str)).
5,6) The target character sequence is represented by the string s.
7) The target character sequence cannot be represented by a std::string rvalue.

If the match does not exist, the following expressions involving m (if exists) should yield the specified values:

 Expression   Value 
m.ready() true
m.size() ​0​
m.empty() true

If the match exists, given any integer in (​0, m.size()) as n, the following expressions involving m should yield the specified values for each overload listed below:

      Expression       Value
           Overload (1)                       Overload (3)                       Overload (5)           
m.ready() true
m.size() 1 + e.mark_count()
m.empty() false
m.prefix().first first str s.begin()
m.prefix().second
m.prefix().matched     false[1]
m.suffix().first last std::char_traits<CharT>::
    length(str) + str 		s.end()
m.suffix().second
m.suffix().matched     false[2]
m[0].first first str s.begin()
m[0].second last std::char_traits<CharT>::
    length(str) + str 		s.end()
m[0].matched     true[3]
m[n].first
  • last if marked sub-expression n did not participate in the match
  • the start of the sequence otherwise matching sub-expression n otherwise
m[n].second
  • last if marked sub-expression n did not participate in the match
  • the end of the sequence otherwise matching sub-expression n otherwise
m[n].matched
  1. ↑ The match prefix is empty.
  2. ↑ The match suffix is empty.
  3. ↑ The entire sequence is matched.

Contents

[edit] Parameters

first, last - the target character range
str - the target null-terminated C-style string
s - the target std::basic_string
m - the match results
e - the regular expression
flags - flags used to determine how the match will be performed

[edit] Return value

Returns true if the entire target sequence matches e, false otherwise.

[edit] 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

[edit] Example

Run this code
#include <cstddef>
#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 (std::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

[edit] 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 2205 C++11 n could be zero in the postcondition can only be positive
LWG 2273 C++11 it was unclear whether partial matches are considered only considers full matches
LWG 2329 C++11 overload (5) accepted basic_string rvalues,
which could result in dangling iterators 		rejected via deleted overload (7)

[edit] See also

(C++11)
 regular expression object
(class template) [edit]
(C++11)
 identifies one regular expression match, including all sub-expression matches
(class template) [edit]
(C++11)
 attempts to match a regular expression to any part of a character sequence
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/regex/regex_match&oldid=177664"