std::regex_match

 

C++

编译器支持

独立和宿主

语言

标准库

标准库头文件

具名要求

特性测试宏 (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)	(since C++11) （始于 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) （始于 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) （始于 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) （始于 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) （始于 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) （始于 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) （始于 C++11）

确定正则表达式 e 是否匹配整个目标字符序列。详细的匹配结果存储在 m 中（如果存在）。

1,2) 目标字符序列由范围 [first, last) 表示。

如果 BidirIt 不满足 LegacyBidirectionalIterator 的要求，则行为未定义。	(until C++23) （直到 C++23）
如果 BidirIt 不符合 bidirectional_iterator 模型，则行为未定义。	(since C++23) （始于 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	last if 标记的子表达式 n 未参与匹配 否则，匹配子表达式 n 的序列的开始
m[n].second	last if 标记的子表达式 n 未参与匹配 否则，匹配子表达式 n 的序列的结束
m[n].matched	false if 标记的子表达式 n 未参与匹配 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++ 标准。

DR	应用于	已发布行为	正确行为
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)	尝试将正则表达式匹配到字符序列的任何部分 (函数模板)