30 Regular expressions library [re]

30.8 Class template basic_­regex [re.regex]

1
#
For a char-like type charT, specializations of class template basic_­regex represent regular expressions constructed from character sequences of charT characters.
In the rest of [re.regex], charT denotes a given char-like type.
Storage for a regular expression is allocated and freed as necessary by the member functions of class basic_­regex.
2
#
Objects of type specialization of basic_­regex are responsible for converting the sequence of charT objects to an internal representation.
It is not specified what form this representation takes, nor how it is accessed by algorithms that operate on regular expressions.
[Note
:
Implementations will typically declare some function templates as friends of basic_­regex to achieve this.
— end note
]
3
#
The functions described in this Clause report errors by throwing exceptions of type regex_­error.
namespace std {
  template<class charT, class traits = regex_traits<charT>>
    class basic_regex {
    public:
      // types
      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;

      // [re.synopt], constants
      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;

      // [re.regex.construct], 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
      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], const operations
      unsigned mark_count() const;
      flag_type flags() const;

      // [re.regex.locale], locale
      locale_type imbue(locale_type loc);
      locale_type getloc() const;

      // [re.regex.swap], swap
      void 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>;
}

30.8.1 Constructors [re.regex.construct]

🔗
basic_regex();
1
#
Postconditions: *this does not match any character sequence.
🔗
explicit basic_regex(const charT* p, flag_type f = regex_constants::ECMAScript);
2
#
Preconditions: [p, p + char_­traits<charT>​::​length(p)) is a valid range.
3
#
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.
4
#
Postconditions: flags() returns f.
mark_­count() returns the number of marked sub-expressions within the expression.
5
#
Throws: regex_­error if [p, p + char_­traits<charT>​::​length(p)) is not a valid regular expression.
🔗
basic_regex(const charT* p, size_t len, flag_type f = regex_constants::ECMAScript);
6
#
Preconditions: [p, p + len) is a valid range.
7
#
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.
8
#
Postconditions: flags() returns f.
mark_­count() returns the number of marked sub-expressions within the expression.
9
#
Throws: regex_­error if [p, p + len) is not a valid regular expression.
🔗
basic_regex(const basic_regex& e);
10
#
Postconditions: flags() and mark_­count() return e.flags() and e.mark_­count(), respectively.
🔗
basic_regex(basic_regex&& e) noexcept;
11
#
Postconditions: flags() and mark_­count() return the values that e.flags() and e.mark_­count(), respectively, had before construction.
🔗
template<class ST, class SA> explicit basic_regex(const basic_string<charT, ST, SA>& s, flag_type f = regex_constants::ECMAScript);
12
#
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.
13
#
Postconditions: flags() returns f.
mark_­count() returns the number of marked sub-expressions within the expression.
14
#
Throws: regex_­error if s is not a valid regular expression.
🔗
template<class ForwardIterator> basic_regex(ForwardIterator first, ForwardIterator last, flag_type f = regex_constants::ECMAScript);
15
#
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.
16
#
Postconditions: flags() returns f.
mark_­count() returns the number of marked sub-expressions within the expression.
17
#
Throws: regex_­error if the sequence [first, last) is not a valid regular expression.
🔗
basic_regex(initializer_list<charT> il, flag_type f = regex_constants::ECMAScript);
18
#
Effects: Same as basic_­regex(il.begin(), il.end(), f).

30.8.2 Assignment [re.regex.assign]

🔗
basic_regex& operator=(const basic_regex& e);
1
#
Postconditions: flags() and mark_­count() return e.flags() and e.mark_­count(), respectively.
🔗
basic_regex& operator=(basic_regex&& e) noexcept;
2
#
Postconditions: flags() and mark_­count() return the values that e.flags() and e.mark_­count(), respectively, had before assignment.
e is in a valid state with unspecified value.
🔗
basic_regex& operator=(const charT* p);
3
#
Effects: Equivalent to: return assign(p);
🔗
basic_regex& operator=(initializer_list<charT> il);
4
#
Effects: Equivalent to: return assign(il.begin(), il.end());
🔗
template<class ST, class SA> basic_regex& operator=(const basic_string<charT, ST, SA>& s);
5
#
Effects: Equivalent to: return assign(s);
🔗
basic_regex& assign(const basic_regex& e);
6
#
Effects: Equivalent to: return *this = e;
🔗
basic_regex& assign(basic_regex&& e) noexcept;
7
#
Effects: Equivalent to: return *this = std​::​move(e);
🔗
basic_regex& assign(const charT* p, flag_type f = regex_constants::ECMAScript);
8
#
Effects: Equivalent to: return assign(string_­type(p), f);
🔗
basic_regex& assign(const charT* p, size_t len, flag_type f = regex_constants::ECMAScript);
9
#
Effects: Equivalent to: return assign(string_­type(p, len), f);
🔗
template<class ST, class SA> basic_regex& assign(const basic_string<charT, ST, SA>& s, flag_type f = regex_constants::ECMAScript);
10
#
Returns: *this.
11
#
Effects: Assigns the regular expression contained in the string s, interpreted according the flags specified in f.
If an exception is thrown, *this is unchanged.
12
#
Postconditions: If no exception is thrown, flags() returns f and mark_­count() returns the number of marked sub-expressions within the expression.
13
#
Throws: regex_­error if s is not a valid regular expression.
🔗
template<class InputIterator> basic_regex& assign(InputIterator first, InputIterator last, flag_type f = regex_constants::ECMAScript);
14
#
Effects: Equivalent to: return assign(string_­type(first, last), f);
🔗
basic_regex& assign(initializer_list<charT> il, flag_type f = regex_constants::ECMAScript);
15
#
Effects: Equivalent to: return assign(il.begin(), il.end(), f);

30.8.3 Constant operations [re.regex.operations]

🔗
unsigned mark_count() const;
1
#
Effects: Returns the number of marked sub-expressions within the regular expression.
🔗
flag_type flags() const;
2
#
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.

30.8.4 Locale [re.regex.locale]

🔗
locale_type imbue(locale_type loc);
1
#
Effects: Returns the result of traits_­inst.imbue(loc) where traits_­inst is a (default-initialized) instance of the template type argument traits stored within the object.
After a call to imbue the basic_­regex object does not match any character sequence.
🔗
locale_type getloc() const;
2
#
Effects: Returns the result of traits_­inst.getloc() where traits_­inst is a (default-initialized) instance of the template parameter traits stored within the object.

30.8.5 Swap [re.regex.swap]

🔗
void swap(basic_regex& e);
1
#
Effects: Swaps the contents of the two regular expressions.
2
#
Postconditions: *this contains the regular expression that was in e, e contains the regular expression that was in *this.
3
#
Complexity: Constant time.

30.8.6 Non-member functions [re.regex.nonmemb]

🔗
template<class charT, class traits> void swap(basic_regex<charT, traits>& lhs, basic_regex<charT, traits>& rhs);
1
#
Effects: Calls lhs.swap(rhs).