std::regex_match

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

文字處理庫

本地化庫

正則表示式庫 (C++11)

格式化庫 (C++20)

空終止序列工具

位元組字串

多位元組字串

寬字串

原生數值轉換

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

文字編碼標識

text_encoding (C++26)

 

正則表示式庫

類

basic_regex (C++11)

sub_match (C++11)

match_results (C++11)

演算法

regex_match (C++11)

regex_search (C++11)

regex_replace (C++11)

迭代器

regex_iterator (C++11)

regex_token_iterator (C++11)

異常

regex_error (C++11)

特性

regex_traits (C++11)

常量

syntax_option_type (C++11)

match_flag_type (C++11)

error_type (C++11)

正則表示式語法

修改後的 ECMAScript-262 (C++11)

 

在標頭檔案 <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)	(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)	(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)	(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)	(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)	(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)	(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)	(C++11 起)

確定正則表示式 e 是否匹配整個目標字元序列。詳細匹配結果儲存在 m 中（如果存在）。

1,2) 目標字元序列由範圍 [first, last) 表示。

如果 BidirIt 不滿足 LegacyBidirectionalIterator 的要求，則行為未定義。	(直至 C++23)
如果 BidirIt 不符合 bidirectional_iterator 模型，則行為未定義。	(C++23 起)

3,4) 目標字元序列由範圍 [str, str + std::char_traits<CharT>::length(str)) 表示。

5,6) 目標字元序列由字串 s 表示。

7) 目標字元序列不能由 std::string 右值表示。

如果不存在匹配，則涉及 m（如果存在）的以下表達式應產生指定值

表示式	值
m.ready()	true
m.size()	​0​
m.empty()	true

如果存在匹配，給定 (​0, m.size()) 中的任何整數為 n，則涉及 m 的以下表達式應為下面列出的每個過載產生指定值

表示式	值
	過載 (1)	過載 (3)	過載 (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
m.suffix().first	last	std::char_traits<CharT>::     length(str) + str	s.end()
m.suffix().second
m.suffix().matched	false
m[0].first	first	str	s.begin()
m[0].second	last	std::char_traits<CharT>::     length(str) + str	s.end()
m[0].matched	true
m[n].first	如果 標記子表示式 n 未參與匹配，則為 last 否則為匹配子表示式 n 的序列開頭
m[n].second	如果 標記子表示式 n 未參與匹配，則為 last 否則為匹配子表示式 n 的序列末尾
m[n].matched	如果 標記子表示式 n 未參與匹配，則為 false 否則為 true

引數

first, last	-	目標字元範圍
str	-	目標空終止 C 風格字串
s	-	目標 std::basic_string
m	-	匹配結果
e	-	正則表示式
flags	-	用於確定匹配方式的標誌

返回值

如果整個目標序列匹配 e，則返回 true，否則返回 false。

注意

因為 regex_match 只考慮完全匹配，所以相同的正則表示式在 regex_match 和 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

示例

執行此程式碼

#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';
            }
        }
}

輸出

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

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 2205	C++11	後置條件中 n 可能為零	只能為正
LWG 2273	C++11	不清楚是否考慮部分匹配	只考慮完全匹配
LWG 2329	C++11	過載 (5) 接受 basic_string 右值， 可能導致懸空迭代器	透過刪除的過載 (7) 拒絕

另見

basic_regex (C++11)	正則表示式物件 (類模板)
match_results (C++11)	標識一個正則表示式匹配，包括所有子表示式匹配 (類模板)
regex_search (C++11)	嘗試將正則表示式與字元序列的任何部分匹配 (函式模板)