| Localization library | |||||||||||||||||||||||||
| Regular expressions library(C++11) | |||||||||||||||||||||||||
| Formatting library(C++20) | |||||||||||||||||||||||||
| Null-terminated sequence utilities | |||||||||||||||||||||||||
| Byte strings | |||||||||||||||||||||||||
| Multibyte strings | |||||||||||||||||||||||||
| Wide strings | |||||||||||||||||||||||||
| Primitive numeric conversions | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Text encoding identifications | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| 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, | (1) | (since C++11) |
template<class BidirIt,class CharT,class Traits> bool regex_match( BidirIt first, BidirIt last, | (2) | (since C++11) |
template<class CharT,class Alloc,class Traits> bool regex_match(const CharT* str, | (3) | (since C++11) |
template<class CharT,class Traits> bool regex_match(const CharT* str,conststd::basic_regex<CharT, Traits>& e, | (4) | (since C++11) |
template<class STraits,class SAlloc,class Alloc, class CharT,class Traits> | (5) | (since C++11) |
template<class STraits,class SAlloc,class CharT,class Traits> bool regex_match(conststd::basic_string<CharT, STraits, SAlloc>& s, | (6) | (since C++11) |
template<class STraits,class SAlloc,class Alloc, class CharT,class Traits> | (7) | (since C++11) |
Determines if the regular expressione matches the entire target character sequence. The detailed match result is stored inm (if present).
[first, last).If | (until C++23) |
If | (since C++23) |
[str, str+std::char_traits<CharT>::length(str)).If the match does not exist, the following expressions involvingm (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()) asn, the following expressions involvingm 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 |
| ||
| m[n].second |
| ||
| m[n].matched |
| ||
Contents |
| first, last | - | the target character range |
| str | - | the target null-terminated C-style string |
| s | - | the targetstd::basic_string |
| m | - | the match results |
| e | - | the regular expression |
| flags | - | flags used to determine how the match will be performed |
Returnstrue if the entire target sequence matchese,false otherwise.
Becauseregex_match only considers full matches, the same regex may give different matches betweenregex_match andstd::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
#include <cstddef>#include <iostream>#include <regex>#include <string> int main(){// Simple regular expression matchingconststd::string fnames[]={"foo.txt","bar.txt","baz.dat","zoidberg"};conststd::regex txt_regex("[a-z]+\\.txt"); for(constauto& fname: fnames)std::cout<< fname<<": "<< std::regex_match(fname, txt_regex)<<'\n'; // Extraction of a sub-matchconststd::regex base_regex("([a-z]+)\\.txt");std::smatch base_match; for(constauto& 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-matchesconststd::regex pieces_regex("([a-z]+)\\.([a-z]+)");std::smatch pieces_match; for(constauto& 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: 1bar.txt: 1baz.dat: 0zoidberg: 0foo.txt has a base of foobar.txt has a base of barfoo.txt submatch 0: foo.txt submatch 1: foo submatch 2: txtbar.txt submatch 0: bar.txt submatch 1: bar submatch 2: txtbaz.dat submatch 0: baz.dat submatch 1: baz submatch 2: dat
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) acceptedbasic_string rvalues,which could result in dangling iterators | rejected via deleted overload(7) |
(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] |
