cppdraft_translate/cppdraft/re/regex.md

[re.regex]

# 28 Text processing library [[text]](./#text)

## 28.6 Regular expressions library [[re]](re#regex)

### 28.6.7 Class template basic_regex [re.regex]

#### [28.6.7.1](#general) General [[re.regex.general]](re.regex.general)

[1](#general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10310)

For a char-like type charT, specializations of class
template basic_regex represent regular expressions constructed
from character sequences of charT characters[.](#general-1.sentence-1)

In the rest
of [re.regex], charT denotes a given char-like
type[.](#general-1.sentence-2)

Storage for a regular expression is allocated and freed as
necessary by the member functions of class basic_regex[.](#general-1.sentence-3)

[2](#general-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10318)

Objects of type specialization of basic_regex are responsible for
converting the sequence of charT objects to an internal
representation[.](#general-2.sentence-1)

It is not specified what form this representation
takes, nor how it is accessed by algorithms that operate on regular
expressions[.](#general-2.sentence-2)

[*Note [1](#general-note-1)*:

Implementations will typically declare
some function templates as friends of basic_regex to achieve
this[.](#general-2.sentence-3)

— *end note*]

[3](#general-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10330)

The functions described in [re.regex] report errors by throwing
exceptions of type regex_error[.](#general-3.sentence-1)

[🔗](#lib:basic_regex_)

namespace std {template<class charT, class traits = regex_traits<charT>>class basic_regex {public:// typesusing 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; // [[re.synopt]](re.synopt "28.6.4.2 Bitmask type syntax_­option_­type"), constantsstatic 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; // [[re.regex.construct]](#construct "28.6.7.2 Constructors"), construct/copy/destroy 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 ForwardIterator> basic_regex(ForwardIterator first, ForwardIterator last,
 flag_type f = regex_constants::ECMAScript);
 basic_regex(initializer_list<charT> il, flag_type f = regex_constants::ECMAScript); ~basic_regex(); // [[re.regex.assign]](#assign "28.6.7.3 Assignment"), assign 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 InputIterator> basic_regex& assign(InputIterator first, InputIterator last,
 flag_type f = regex_constants::ECMAScript);
 basic_regex& assign(initializer_list<charT>,
 flag_type f = regex_constants::ECMAScript); // [[re.regex.operations]](#operations "28.6.7.4 Constant operations"), const operationsunsigned mark_count() const;
 flag_type flags() const; // [[re.regex.locale]](#locale "28.6.7.5 Locale"), locale locale_type imbue(locale_type loc);
 locale_type getloc() const; // [[re.regex.swap]](#swap "28.6.7.6 Swap"), swapvoid swap(basic_regex&); }; template<class ForwardIterator> basic_regex(ForwardIterator, ForwardIterator,
 regex_constants::syntax_option_type = regex_constants::ECMAScript)-> basic_regex<typename iterator_traits<ForwardIterator>::value_type>;}

#### [28.6.7.2](#construct) Constructors [[re.regex.construct]](re.regex.construct)

[🔗](#lib:basic_regex,constructor)

`basic_regex();
`

[1](#construct-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10425)

*Postconditions*: *this does not match any character sequence[.](#construct-1.sentence-1)

[🔗](#lib:basic_regex,constructor_)

`explicit basic_regex(const charT* p, flag_type f = regex_constants::ECMAScript);
`

[2](#construct-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10436)

*Preconditions*: [p, p + char_traits<charT>​::​length(p)) is a valid range[.](#construct-2.sentence-1)

[3](#construct-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10440)

*Effects*: The object's internal finite state machine
is constructed from the regular expression contained in
the sequence of characters
[p, p + char_traits<charT>​::​​length(p)), and
interpreted according to the flags f[.](#construct-3.sentence-1)

[4](#construct-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10448)

*Postconditions*: flags() returns f[.](#construct-4.sentence-1)

mark_count() returns the number of marked sub-expressions
within the expression[.](#construct-4.sentence-2)

[5](#construct-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10454)

*Throws*: regex_error if
[p, p + char_traits<charT>​::​length(p)) is not a valid regular expression[.](#construct-5.sentence-1)

[🔗](#lib:basic_regex,constructor__)

`basic_regex(const charT* p, size_t len, flag_type f = regex_constants::ECMAScript);
`

[6](#construct-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10466)

*Preconditions*: [p, p + len) is a valid range[.](#construct-6.sentence-1)

[7](#construct-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10470)

*Effects*: The object's internal finite state machine
is constructed from the regular expression contained in
the sequence of characters [p, p + len), and
interpreted according the flags specified in f[.](#construct-7.sentence-1)

[8](#construct-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10477)

*Postconditions*: flags() returns f[.](#construct-8.sentence-1)

mark_count() returns the number of marked sub-expressions
within the expression[.](#construct-8.sentence-2)

[9](#construct-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10483)

*Throws*: regex_error if [p, p + len) is not a valid regular expression[.](#construct-9.sentence-1)

[🔗](#lib:basic_regex,constructor___)

`basic_regex(const basic_regex& e);
`

[10](#construct-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10494)

*Postconditions*: flags() and mark_count() returne.flags() and e.mark_count(), respectively[.](#construct-10.sentence-1)

[🔗](#lib:basic_regex,constructor____)

`basic_regex(basic_regex&& e) noexcept;
`

[11](#construct-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10506)

*Postconditions*: flags() and mark_count() return the values thate.flags() and e.mark_count(), respectively, had before construction[.](#construct-11.sentence-1)

[🔗](#lib:basic_regex,constructor_____)

`template<class ST, class SA>
  explicit basic_regex(const basic_string<charT, ST, SA>& s,
                       flag_type f = regex_constants::ECMAScript);
`

[12](#construct-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10520)

*Effects*: The object's internal finite state machine
is constructed from the regular expression contained in
the string s, and
interpreted according to the flags specified in f[.](#construct-12.sentence-1)

[13](#construct-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10527)

*Postconditions*: flags() returns f[.](#construct-13.sentence-1)

mark_count() returns the number of marked sub-expressions
within the expression[.](#construct-13.sentence-2)

[14](#construct-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10533)

*Throws*: regex_error if s is not a valid regular expression[.](#construct-14.sentence-1)

[🔗](#lib:basic_regex,constructor______)

`template<class ForwardIterator>
  basic_regex(ForwardIterator first, ForwardIterator last,
              flag_type f = regex_constants::ECMAScript);
`

[15](#construct-15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10546)

*Effects*: The object's internal finite state machine
is constructed from the regular expression contained in
the sequence of characters [first, last), and
interpreted according to the flags specified in f[.](#construct-15.sentence-1)

[16](#construct-16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10553)

*Postconditions*: flags() returns f[.](#construct-16.sentence-1)

mark_count() returns the number of marked sub-expressions
within the expression[.](#construct-16.sentence-2)

[17](#construct-17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10559)

*Throws*: regex_error if the sequence [first, last) is not a
valid regular expression[.](#construct-17.sentence-1)

[🔗](#lib:basic_regex,constructor_______)

`basic_regex(initializer_list<charT> il, flag_type f = regex_constants::ECMAScript);
`

[18](#construct-18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10571)

*Effects*: Same as basic_regex(il.begin(), il.end(), f)[.](#construct-18.sentence-1)

#### [28.6.7.3](#assign) Assignment [[re.regex.assign]](re.regex.assign)

[🔗](#lib:basic_regex,operator=)

`basic_regex& operator=(const basic_regex& e);
`

[1](#assign-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10584)

*Postconditions*: flags() and mark_count() returne.flags() and e.mark_count(), respectively[.](#assign-1.sentence-1)

[🔗](#lib:basic_regex,operator=_)

`basic_regex& operator=(basic_regex&& e) noexcept;
`

[2](#assign-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10596)

*Postconditions*: flags() and mark_count() return the values thate.flags() and e.mark_count(), respectively, had before assignment[.](#assign-2.sentence-1)

e is in a valid state with unspecified value[.](#assign-2.sentence-2)

[🔗](#lib:basic_regex,operator=__)

`basic_regex& operator=(const charT* p);
`

[3](#assign-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10609)

*Effects*: Equivalent to: return assign(p);

[🔗](#lib:basic_regex,operator=___)

`basic_regex& operator=(initializer_list<charT> il);
`

[4](#assign-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10620)

*Effects*: Equivalent to: return assign(il.begin(), il.end());

[🔗](#lib:basic_regex,operator=____)

`template<class ST, class SA>
  basic_regex& operator=(const basic_string<charT, ST, SA>& s);
`

[5](#assign-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10632)

*Effects*: Equivalent to: return assign(s);

[🔗](#lib:basic_regex,assign)

`basic_regex& assign(const basic_regex& e);
`

[6](#assign-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10643)

*Effects*: Equivalent to: return *this = e;

[🔗](#lib:basic_regex,assign_)

`basic_regex& assign(basic_regex&& e) noexcept;
`

[7](#assign-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10654)

*Effects*: Equivalent to: return *this = std​::​move(e);

[🔗](#lib:basic_regex,assign__)

`basic_regex& assign(const charT* p, flag_type f = regex_constants::ECMAScript);
`

[8](#assign-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10665)

*Effects*: Equivalent to: return assign(string_type(p), f);

[🔗](#lib:basic_regex,assign___)

`basic_regex& assign(const charT* p, size_t len, flag_type f = regex_constants::ECMAScript);
`

[9](#assign-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10676)

*Effects*: Equivalent to: return assign(string_type(p, len), f);

[🔗](#lib:basic_regex,assign____)

`template<class ST, class SA>
  basic_regex& assign(const basic_string<charT, ST, SA>& s,
                      flag_type f = regex_constants::ECMAScript);
`

[10](#assign-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10689)

*Effects*: Assigns the regular expression contained in the strings, interpreted according the flags specified in f[.](#assign-10.sentence-1)

If an exception is thrown, *this is unchanged[.](#assign-10.sentence-2)

[11](#assign-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10695)

*Postconditions*: If no exception is thrown,flags() returns f and mark_count() returns the number of marked sub-expressions within the expression[.](#assign-11.sentence-1)

[12](#assign-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10701)

*Returns*: *this[.](#assign-12.sentence-1)

[13](#assign-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10705)

*Throws*: regex_error if s is not a valid regular expression[.](#assign-13.sentence-1)

[🔗](#lib:basic_regex,assign_____)

`template<class InputIterator>
  basic_regex& assign(InputIterator first, InputIterator last,
                      flag_type f = regex_constants::ECMAScript);
`

[14](#assign-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10718)

*Effects*: Equivalent to: return assign(string_type(first, last), f);

[🔗](#lib:assign,basic_regex______)

`basic_regex& assign(initializer_list<charT> il,
                    flag_type f = regex_constants::ECMAScript);
`

[15](#assign-15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10730)

*Effects*: Equivalent to: return assign(il.begin(), il.end(), f);

#### [28.6.7.4](#operations) Constant operations [[re.regex.operations]](re.regex.operations)

[🔗](#lib:mark_count,basic_regex)

`unsigned mark_count() const;
`

[1](#operations-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10744)

*Effects*: Returns the number of marked sub-expressions within the
regular expression[.](#operations-1.sentence-1)

[🔗](#lib:flag_type,basic_regex)

`flag_type flags() const;
`

[2](#operations-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10756)

*Effects*: Returns a copy of the regular expression syntax flags that
were passed to the object's constructor or to the last call
to assign[.](#operations-2.sentence-1)

#### [28.6.7.5](#locale) Locale [[re.regex.locale]](re.regex.locale)

[🔗](#lib:imbue,basic_regex)

`locale_type imbue(locale_type loc);
`

[1](#locale-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10772)

*Effects*: Returns the result of traits_inst.imbue(loc) wheretraits_inst is a (default-initialized) instance of the template
type argument traits stored within the object[.](#locale-1.sentence-1)

After a call
to imbue the basic_regex object does not match any
character sequence[.](#locale-1.sentence-2)

[🔗](#lib:getloc,basic_regex)

`locale_type getloc() const;
`

[2](#locale-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10787)

*Effects*: Returns the result of traits_inst.getloc() wheretraits_inst is a (default-initialized) instance of the template
parameter traits stored within the object[.](#locale-2.sentence-1)

#### [28.6.7.6](#swap) Swap [[re.regex.swap]](re.regex.swap)

[🔗](#lib:swap,basic_regex_)

`void swap(basic_regex& e);
`

[1](#swap-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10803)

*Effects*: Swaps the contents of the two regular expressions[.](#swap-1.sentence-1)

[2](#swap-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10807)

*Postconditions*: *this contains the regular expression
that was in e, e contains the regular expression that
was in *this[.](#swap-2.sentence-1)

[3](#swap-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10813)

*Complexity*: Constant time[.](#swap-3.sentence-1)

#### [28.6.7.7](#nonmemb) Non-member functions [[re.regex.nonmemb]](re.regex.nonmemb)

[🔗](#lib:basic_regex,swap__)

`template<class charT, class traits>
  void swap(basic_regex<charT, traits>& lhs, basic_regex<charT, traits>& rhs);
`

[1](#nonmemb-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L10827)

*Effects*: Calls lhs.swap(rhs)[.](#nonmemb-1.sentence-1)