# 标准库头文件 <regex>

< cpp‎ | header

此头文件是正则表达式库的一部分。

### 包含
<compare> (C++20) | 三路比较运算符支持
<initializer_list> (C++11) | std::initializer_list 类模板
### 类
basic_regex (C++11) | 正则表达式对象 (类模板)
sub_match (C++11) | 标识子表达式所匹配的字符序列 (类模板)
match_results (C++11) | 标识一个正则表达式匹配，包含所有子表达式匹配 (类模板)
regex_iterator (C++11) | 迭代一个字符序列中的所有正则表达式匹配 (类模板)
regex_token_iterator (C++11) | 迭代给定字符串中的所有正则表达式匹配中的指定子表达式，或迭代未匹配的子字符串 (类模板)
regex_error (C++11) | 报告正则表达式库生成的错误 (类)
regex_traits (C++11) | 提供正则表达式库所需的关于字符类型的元信息 (类模板)
##### regex 常量类型
定义于命名空间 `std::regex_constants`
syntax_option_type (C++11) | 控制正则表达式行为的通用选项 (typedef)
match_flag_type (C++11) | 特定于匹配的选项 (typedef)
error_type (C++11) | 描述不同类型的匹配错误 (typedef)
### 函数
##### 算法
regex_match (C++11) | 尝试匹配一个正则表达式到整个字符序列 (函数模板)
regex_search (C++11) | 尝试匹配一个正则表达式到字符序列的任何部分 (函数模板)
regex_replace (C++11) | 以格式化的替换文本来替换正则表达式匹配的出现位置 (函数模板)
##### 非成员操作
std::swap(std::basic_regex) (C++11) | 特化 std::swap 算法 (函数模板)
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20) | 比较一个 `sub_match` 与另一 `sub_match` 、字符串或字符 (函数模板)
operator<< | 输出匹配的字符子序列 (函数模板)
operator==operator!= (C++20 中移除) | 以字典序比较两个匹配结果的值 (函数模板)
std::swap(std::match_results) (C++11) | 特化 `std::swap` 算法 (函数模板)
##### 范围访问
begin cbegin (C++11)(C++14) | 返回指向容器或数组起始的迭代器 (函数模板)
end cend (C++11)(C++14) | 返回指向容器或数组结尾的迭代器 (函数模板)
rbegin crbegin (C++14) | 返回指向一个容器或数组的逆向迭代器 (函数模板)
rend crend (C++14) | 返回容器或数组的逆向尾迭代器 (函数模板)
size ssize (C++17)(C++20) | 返回容器或数组的大小 (函数模板)
empty (C++17) | 检查容器是否为空 (函数模板)
data (C++17) | 获得指向底层数组的指针 (函数模板)

### 概要

    #include <compare>
    #include <initializer_list>

    namespace std {
      // regex 常量
      namespace regex_constants {
        using syntax_option_type = /*T1*/;
        using match_flag_type = /*T2*/;
        using error_type = /*T3*/;
      }

      // 类 regex_error
      class regex_error;

      // 类模板 regex_traits
      template<class CharT> struct regex_traits;

      // 类模板 basic_regex
      template<class CharT, class Traits = regex_traits<CharT>> class basic_regex;

      using regex  = basic_regex<char>;
      using wregex = basic_regex<wchar_t>;

      // basic_regex 交换
      template<class CharT, class Traits>
        void swap(basic_regex<CharT, Traits>& e1, basic_regex<CharT, Traits>& e2);

      // 类模板 sub_match
      template<class BiIt>
        class sub_match;

      using csub_match  = sub_match<const char*>;
      using wcsub_match = sub_match<const wchar_t*>;
      using ssub_match  = sub_match<string::const_iterator>;
      using wssub_match = sub_match<wstring::const_iterator>;

      // sub_match 非成员运算符
      template<class BiIt>
        bool operator==(const sub_match<BiIt>& lhs, const sub_match<BiIt>& rhs);
      template<class BiIt>
        auto operator<=>(const sub_match<BiIt>& lhs, const sub_match<BiIt>& rhs);

      template<class BiIt, class ST, class SA>
        bool operator==(
          const sub_match<BiIt>& lhs,
          const basic_string<typename iterator_traits<BiIt>::value_type, ST, SA>& rhs);
      template<class BiIt, class ST, class SA>
        auto operator<=>(
          const sub_match<BiIt>& lhs,
          const basic_string<typename iterator_traits<BiIt>::value_type, ST, SA>& rhs);

      template<class BiIt>
        bool operator==(const sub_match<BiIt>& lhs,
                        const typename iterator_traits<BiIt>::value_type* rhs);
      template<class BiIt>
        auto operator<=>(const sub_match<BiIt>& lhs,
                         const typename iterator_traits<BiIt>::value_type* rhs);

      template<class BiIt>
        bool operator==(const sub_match<BiIt>& lhs,
                        const typename iterator_traits<BiIt>::value_type& rhs);
      template<class BiIt>
        auto operator<=>(const sub_match<BiIt>& lhs,
                         const typename iterator_traits<BiIt>::value_type& rhs);

      template<class CharT, class ST, class BiIt>
        basic_ostream<CharT, ST>&
          operator<<(basic_ostream<CharT, ST>& os, const sub_match<BiIt>& m);

      // 类模板 match_results
      template<class BiIt,
               class Allocator = allocator<sub_match<BiIt>>>
        class match_results;

      using cmatch  = match_results<const char*>;
      using wcmatch = match_results<const wchar_t*>;
      using smatch  = match_results<string::const_iterator>;
      using wsmatch = match_results<wstring::const_iterator>;

      // match_results 比较
      template<class BiIt, class Allocator>
        bool operator==(const match_results<BiIt, Allocator>& m1,
                        const match_results<BiIt, Allocator>& m2);

      // match_results 交换
      template<class BiIt, class Allocator>
        void swap(match_results<BiIt, Allocator>& m1, match_results<BiIt, Allocator>& m2);

      // 函数模板 regex_match
      template<class BiIt, class Allocator, class CharT, class Traits>
        bool regex_match(BiIt first, BiIt last,
                         match_results<BiIt, Allocator>& m,
                         const basic_regex<CharT, Traits>& e,
                         regex_constants::match_flag_type flags =
                           regex_constants::match_default);
      template<class BiIt, class CharT, class Traits>
        bool regex_match(BiIt first, BiIt last,
                         const basic_regex<CharT, Traits>& e,
                         regex_constants::match_flag_type flags =
                           regex_constants::match_default);
      template<class CharT, class Allocator, class Traits>
        bool regex_match(const CharT* str, match_results<const CharT*, Allocator>& m,
                         const basic_regex<CharT, Traits>& e,
                         regex_constants::match_flag_type flags =
                           regex_constants::match_default);
      template<class ST, class SA, class Allocator, class CharT, class Traits>
        bool regex_match(const basic_string<CharT, ST, SA>& s,
                         match_results<typename basic_string<CharT, ST, SA>::const_iterator,
                                       Allocator>& m,
                         const basic_regex<CharT, Traits>& e,
                         regex_constants::match_flag_type flags =
                           regex_constants::match_default);
      template<class ST, class SA, class Allocator, class CharT, class Traits>
        bool regex_match(const basic_string<CharT, ST, SA>&&,
                         match_results<typename basic_string<CharT, ST, SA>::const_iterator,
                                       Allocator>&,
                         const basic_regex<CharT, Traits>&,
                         regex_constants::match_flag_type =
                           regex_constants::match_default) = delete;
      template<class CharT, class Traits>
        bool regex_match(const CharT* str,
                         const basic_regex<CharT, Traits>& e,
                         regex_constants::match_flag_type flags =
                           regex_constants::match_default);
      template<class ST, class SA, class CharT, class Traits>
        bool regex_match(const basic_string<CharT, ST, SA>& s,
                         const basic_regex<CharT, Traits>& e,
                         regex_constants::match_flag_type flags =
                           regex_constants::match_default);

      // 函数模板 regex_search
      template<class BiIt, class Allocator, class CharT, class Traits>
        bool regex_search(BiIt first, BiIt last,
                          match_results<BiIt, Allocator>& m,
                          const basic_regex<CharT, Traits>& e,
                          regex_constants::match_flag_type flags =
                            regex_constants::match_default);
      template<class BiIt, class CharT, class Traits>
        bool regex_search(BiItfirst, BiIt last,
                          const basic_regex<CharT, Traits>& e,
                          regex_constants::match_flag_type flags =
                            regex_constants::match_default);
      template<class CharT, class Allocator, class Traits>
        bool regex_search(const CharT* str,
                          match_results<const CharT*, Allocator>& m,
                          const basic_regex<CharT, Traits>& e,
                          regex_constants::match_flag_type flags =
                            regex_constants::match_default);
      template<class CharT, class Traits>
        bool regex_search(const CharT* str,
                          const basic_regex<CharT, Traits>& e,
                          regex_constants::match_flag_type flags =
                            regex_constants::match_default);
      template<class ST, class SA, class CharT, class Traits>
        bool regex_search(const basic_string<CharT, ST, SA>& s,
                          const basic_regex<CharT, Traits>& e,
                          regex_constants::match_flag_type flags =
                            regex_constants::match_default);
      template<class ST, class SA, class Allocator, class CharT, class Traits>
        bool regex_search(const basic_string<CharT, ST, SA>& s,
                          match_results<typename basic_string<CharT, ST, SA>::const_iterator,
                                        Allocator>& m,
                          const basic_regex<CharT, Traits>& e,
                          regex_constants::match_flag_type flags =
                            regex_constants::match_default);
      template<class ST, class SA, class Allocator, class CharT, class Traits>
        bool regex_search(const basic_string<CharT, ST, SA>&&,
                          match_results<typename basic_string<CharT, ST, SA>::const_iterator,
                                        Allocator>&,
                          const basic_regex<CharT, Traits>&,
                          regex_constants::match_flag_type
                            = regex_constants::match_default) = delete;

      // 函数模板 regex_replace
      template<class OutputIt, class BiIt,
                class Traits, class CharT, class ST, class SA>
        OutputIt
          regex_replace(OutputIt out,
                        BiIt first, BiIt last,
                        const basic_regex<CharT, Traits>& e,
                        const basic_string<CharT, ST, SA>& fmt,
                        regex_constants::match_flag_type flags =
                          regex_constants::match_default);
      template<class OutputIt, class BiIt, class Traits, class CharT>
        OutputIt
          regex_replace(OutputIt out,
                        BiIt first, BiIt last,
                        const basic_regex<CharT, Traits>& e,
                        const CharT* fmt,
                        regex_constants::match_flag_type flags =
                          regex_constants::match_default);
      template<class Traits, class CharT, class ST, class SA, class FST, class FSA>
        basic_string<CharT, ST, SA>
          regex_replace(const basic_string<CharT, ST, SA>& s,
                        const basic_regex<CharT, Traits>& e,
                        const basic_string<CharT, FST, FSA>& fmt,
                        regex_constants::match_flag_type flags =
                          regex_constants::match_default);
      template<class Traits, class CharT, class ST, class SA>
        basic_string<CharT, ST, SA>
          regex_replace(const basic_string<CharT, ST, SA>& s,
                        const basic_regex<CharT, Traits>& e,
                        const CharT* fmt,
                        regex_constants::match_flag_type flags =
                          regex_constants::match_default);
      template<class Traits, class CharT, class ST, class SA>
        basic_string<CharT>
          regex_replace(const CharT* s,
                        const basic_regex<CharT, Traits>& e,
                        const basic_string<CharT, ST, SA>& fmt,
                        regex_constants::match_flag_type flags =
                          regex_constants::match_default);
      template<class Traits, class CharT>
        basic_string<CharT>
          regex_replace(const CharT* s,
                        const basic_regex<CharT, Traits>& e,
                        const CharT* fmt,
                        regex_constants::match_flag_type flags =
                          regex_constants::match_default);

      // 类模板 regex_iterator
      template<class BiIt,
                class CharT = typename iterator_traits<BiIt>::value_type,
                class Traits = regex_traits<CharT>>
        class regex_iterator;

      using cregex_iterator  = regex_iterator<const char*>;
      using wcregex_iterator = regex_iterator<const wchar_t*>;
      using sregex_iterator  = regex_iterator<string::const_iterator>;
      using wsregex_iterator = regex_iterator<wstring::const_iterator>;

      // 类模板 regex_token_iterator
      template<class BiIt,
                class CharT = typename iterator_traits<BiIt>::value_type,
                class Traits = regex_traits<CharT>>
        class regex_token_iterator;

      using cregex_token_iterator  = regex_token_iterator<const char*>;
      using wcregex_token_iterator = regex_token_iterator<const wchar_t*>;
      using sregex_token_iterator  = regex_token_iterator<string::const_iterator>;
      using wsregex_token_iterator = regex_token_iterator<wstring::const_iterator>;

      namespace pmr {
        template<class BiIt>
          using match_results =
            std::match_results<BiIt, polymorphic_allocator<sub_match<BiIt>>>;

        using cmatch  = match_results<const char*>;
        using wcmatch = match_results<const wchar_t*>;
        using smatch  = match_results<string::const_iterator>;
        using wsmatch = match_results<wstring::const_iterator>;
      }
    }

#### 位掩码类型 std::regex_constants::syntax_option_type

    namespace std::regex_constants {
      using syntax_option_type = /*T1*/;
      inline constexpr syntax_option_type icase = /* 未指明 */;
      inline constexpr syntax_option_type nosubs = /* 未指明 */;
      inline constexpr syntax_option_type optimize = /* 未指明 */;
      inline constexpr syntax_option_type collate = /* 未指明 */;
      inline constexpr syntax_option_type ECMAScript = /* 未指明 */;
      inline constexpr syntax_option_type basic = /* 未指明 */;
      inline constexpr syntax_option_type extended = /* 未指明 */;
      inline constexpr syntax_option_type awk = /* 未指明 */;
      inline constexpr syntax_option_type grep = /* 未指明 */;
      inline constexpr syntax_option_type egrep = /* 未指明 */;
      inline constexpr syntax_option_type multiline = /* 未指明 */;
    }

#### 位掩码类型 std::regex_constants::match_flag_type

    namespace std::regex_constants {
      using match_flag_type = /*T2*/;
      inline constexpr match_flag_type match_default = {};
      inline constexpr match_flag_type match_not_bol = /* 未指明 */;
      inline constexpr match_flag_type match_not_eol = /* 未指明 */;
      inline constexpr match_flag_type match_not_bow = /* 未指明 */;
      inline constexpr match_flag_type match_not_eow = /* 未指明 */;
      inline constexpr match_flag_type match_any = /* 未指明 */;
      inline constexpr match_flag_type match_not_null = /* 未指明 */;
      inline constexpr match_flag_type match_continuous = /* 未指明 */;
      inline constexpr match_flag_type match_prev_avail = /* 未指明 */;
      inline constexpr match_flag_type format_default = {};
      inline constexpr match_flag_type format_sed = /* 未指明 */;
      inline constexpr match_flag_type format_no_copy = /* 未指明 */;
      inline constexpr match_flag_type format_first_only = /* 未指明 */;
    }

#### 被枚举类型 std::regex_constants::error_type

    namespace std::regex_constants {
      using error_type = /*T3*/;
      inline constexpr error_type error_collate = /* 未指明 */;
      inline constexpr error_type error_ctype = /* 未指明 */;
      inline constexpr error_type error_escape = /* 未指明 */;
      inline constexpr error_type error_backref = /* 未指明 */;
      inline constexpr error_type error_brack = /* 未指明 */;
      inline constexpr error_type error_paren = /* 未指明 */;
      inline constexpr error_type error_brace = /* 未指明 */;
      inline constexpr error_type error_badbrace = /* 未指明 */;
      inline constexpr error_type error_range = /* 未指明 */;
      inline constexpr error_type error_space = /* 未指明 */;
      inline constexpr error_type error_badrepeat = /* 未指明 */;
      inline constexpr error_type error_complexity = /* 未指明 */;
      inline constexpr error_type error_stack = /* 未指明 */;
    }

#### 类 std::regex_error

    namespace std {
      class regex_error : public runtime_error {
      public:
        explicit regex_error(regex_constants::error_type ecode);
        regex_constants::error_type code() const;
      };
    }

#### 类模板 std::regex_traits

    namespace std {
      template<class CharT>
        struct regex_traits {
          using char_type       = CharT;
          using string_type     = basic_string<char_type>;
          using locale_type     = locale;
          using char_class_type = /* 位掩码类型 */;

          regex_traits();
          static size_t length(const char_type* p);
          CharT translate(CharT c) const;
          CharT translate_nocase(CharT c) const;
          template<class ForwardIt>
            string_type transform(ForwardIt first, ForwardIt last) const;
          template<class ForwardIt>
            string_type transform_primary(ForwardIt first, ForwardIt last) const;
          template<class ForwardIt>
            string_type lookup_collatename(ForwardIt first, ForwardIt last) const;
          template<class ForwardIt>
            char_class_type lookup_classname(ForwardIt first, ForwardIt last,
                                             bool icase = false) const;
          bool isctype(CharT c, char_class_type f) const;
          int value(CharT ch, int radix) const;
          locale_type imbue(locale_type l);
          locale_type getloc() const;
        };
    }

#### 类模板 std::basic_regex

    namespace std {
      template<class CharT, class Traits = regex_traits<CharT>>
        class basic_regex {
        public:
          // 类型
          using value_type  =          CharT;
          using Traits_type =          Traits;
          using string_type = typename Traits::string_type;
          using flag_type   =          regex_constants::syntax_option_type;
          using locale_type = typename Traits::locale_type;

          // 常量
          static constexpr flag_type icase = regex_constants::icase;
          static constexpr flag_type nosubs = regex_constants::nosubs;
          static constexpr flag_type optimize = regex_constants::optimize;
          static constexpr flag_type collate = regex_constants::collate;
          static constexpr flag_type ECMAScript = regex_constants::ECMAScript;
          static constexpr flag_type basic = regex_constants::basic;
          static constexpr flag_type extended = regex_constants::extended;
          static constexpr flag_type awk = regex_constants::awk;
          static constexpr flag_type grep = regex_constants::grep;
          static constexpr flag_type egrep = regex_constants::egrep;
          static constexpr flag_type multiline = regex_constants::multiline;

          // 构造/复制/销毁
          basic_regex();
          explicit basic_regex(const CharT* p, flag_type f = regex_constants::ECMAScript);
          basic_regex(const CharT* p, size_t len, flag_type f = regex_constants::ECMAScript);
          basic_regex(const basic_regex&);
          basic_regex(basic_regex&&) noexcept;
          template<class ST, class SA>
            explicit basic_regex(const basic_string<CharT, ST, SA>& s,
                                 flag_type f = regex_constants::ECMAScript);
          template<class ForwardIt>
            basic_regex(ForwardIt first, ForwardIt last,
                        flag_type f = regex_constants::ECMAScript);
          basic_regex(initializer_list<CharT> il, flag_type f = regex_constants::ECMAScript);

          ~basic_regex();

          // 赋值
          basic_regex& operator=(const basic_regex& e);
          basic_regex& operator=(basic_regex&& e) noexcept;
          basic_regex& operator=(const CharT* p);
          basic_regex& operator=(initializer_list<CharT> il);
          template<class ST, class SA>
            basic_regex& operator=(const basic_string<CharT, ST, SA>& s);

          basic_regex& assign(const basic_regex& e);
          basic_regex& assign(basic_regex&& e) noexcept;
          basic_regex& assign(const CharT* p, flag_type f = regex_constants::ECMAScript);
          basic_regex& assign(const CharT* p, size_t len,
                              flag_type f = regex_constants::ECMAScript);
          template<class ST, class SA>
            basic_regex& assign(const basic_string<CharT, ST, SA>& s,
                                flag_type f = regex_constants::ECMAScript);
          template<class InputIt>
            basic_regex& assign(InputIt first, InputIt last,
                                flag_type f = regex_constants::ECMAScript);
          basic_regex& assign(initializer_list<CharT>,
                              flag_type f = regex_constants::ECMAScript);

          // const 操作
          unsigned mark_count() const;
          flag_type flags() const;

          // 本地环境
          locale_type imbue(locale_type loc);
          locale_type getloc() const;

          // 交换
          void swap(basic_regex&);
        };

      template<class ForwardIt>
        basic_regex(ForwardIt, ForwardIt,
                    regex_constants::syntax_option_type = regex_constants::ECMAScript)
          -> basic_regex<typename iterator_traits<ForwardIt>::value_type>;
    }

#### 类模板 std::sub_match

    namespace std {
      template<class BiIt>
        class sub_match : public pair<BiIt, BiIt> {
        public:
          using value_type      = typename iterator_traits<BiIt>::value_type;
          using difference_type = typename iterator_traits<BiIt>::difference_type;
          using iterator        = BiIt;
          using string_type     = basic_string<value_type>;

          bool matched;

          constexpr sub_match();

          difference_type length() const;
          operator string_type() const;
          string_type str() const;

          int compare(const sub_match& s) const;
          int compare(const string_type& s) const;
          int compare(const value_type* s) const;
        };
    }

#### 类模板 std::match_results

    namespace std {
      template<class BiIt,
               class Allocator = allocator<sub_match<BiIt>>>
        class match_results {
        public:
          using value_type      = sub_match<BiIt>;
          using const_reference = const value_type&;
          using reference       = value_type&;
          using const_iterator  = /* 由实现定义 */;
          using iterator        = const_iterator;
          using difference_type = typename iterator_traits<BiIt>::difference_type;
          using size_type       = typename allocator_traits<Allocator>::size_type;
          using allocator_type  = Allocator;
          using char_type       = typename iterator_traits<BiIt>::value_type;
          using string_type     = basic_string<char_type>;

          // 构造/复制/销毁
          match_results() : match_results(Allocator()) {}
          explicit match_results(const Allocator&);
          match_results(const match_results& m);
          match_results(match_results&& m) noexcept;
          match_results& operator=(const match_results& m);
          match_results& operator=(match_results&& m);
          ~match_results();

          // 状态
          bool ready() const;

          // 大小
          size_type size() const;
          size_type max_size() const;
          [[nodiscard]] bool empty() const;

          // 元素访问
          difference_type length(size_type sub = 0) const;
          difference_type position(size_type sub = 0) const;
          string_type str(size_type sub = 0) const;
          const_reference operator[](size_type n) const;

          const_reference prefix() const;
          const_reference suffix() const;
          const_iterator begin() const;
          const_iterator end() const;
          const_iterator cbegin() const;
          const_iterator cend() const;

          // 格式
          template<class OutputIt>
            OutputIt
              format(OutputIt out,
                     const char_type* fmt_first, const char_type* fmt_last,
                     regex_constants::match_flag_type flags =
                       regex_constants::format_default) const;
          template<class OutputIt, class ST, class SA>
            OutputIt
              format(OutputIt out,
                     const basic_string<char_type, ST, SA>& fmt,
                     regex_constants::match_flag_type flags =
                       regex_constants::format_default) const;
          template<class ST, class SA>
            basic_string<char_type, ST, SA>
              format(const basic_string<char_type, ST, SA>& fmt,
                     regex_constants::match_flag_type flags =
                       regex_constants::format_default) const;
          string_type
            format(const char_type* fmt,
                   regex_constants::match_flag_type flags =
                     regex_constants::format_default) const;

          // 分配器
          allocator_type get_allocator() const;

          // 交换
          void swap(match_results& that);
        };
    }