31 Regular expressions library [re]

31.8 Class template basic_regex [re.regex]

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.

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 ]

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.regex.const], constants
      static constexpr regex_constants::syntax_option_type
        icase = regex_constants::icase;
      static constexpr regex_constants::syntax_option_type
        nosubs = regex_constants::nosubs;
      static constexpr regex_constants::syntax_option_type
        optimize = regex_constants::optimize;
      static constexpr regex_constants::syntax_option_type
        collate = regex_constants::collate;
      static constexpr regex_constants::syntax_option_type
        ECMAScript = regex_constants::ECMAScript;
      static constexpr regex_constants::syntax_option_type
        basic = regex_constants::basic;
      static constexpr regex_constants::syntax_option_type
        extended = regex_constants::extended;
      static constexpr regex_constants::syntax_option_type
        awk = regex_constants::awk;
      static constexpr regex_constants::syntax_option_type
        grep = regex_constants::grep;
      static constexpr regex_constants::syntax_option_type
        egrep = regex_constants::egrep;
      static constexpr regex_constants::syntax_option_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>& p,
                             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>, flag_type = regex_constants::ECMAScript);

      ~basic_regex();

      basic_regex& operator=(const basic_regex&);
      basic_regex& operator=(basic_regex&&) noexcept;
      basic_regex& operator=(const charT* ptr);
      basic_regex& operator=(initializer_list<charT> il);
      template <class ST, class SA>
        basic_regex& operator=(const basic_string<charT, ST, SA>& p);

      // [re.regex.assign], assign
      basic_regex& assign(const basic_regex& that);
      basic_regex& assign(basic_regex&& that) noexcept;
      basic_regex& assign(const charT* ptr, flag_type f = regex_constants::ECMAScript);
      basic_regex& assign(const charT* p, size_t len, flag_type f);
      template <class string_traits, class A>
        basic_regex& assign(const basic_string<charT, string_traits, A>& 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 = 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>;
}

31.8.1 basic_regex constants [re.regex.const]

static constexpr regex_constants::syntax_option_type icase = regex_constants::icase;
static constexpr regex_constants::syntax_option_type nosubs = regex_constants::nosubs;
static constexpr regex_constants::syntax_option_type optimize = regex_constants::optimize;
static constexpr regex_constants::syntax_option_type collate = regex_constants::collate;
static constexpr regex_constants::syntax_option_type ECMAScript = regex_constants::ECMAScript;
static constexpr regex_constants::syntax_option_type basic = regex_constants::basic;
static constexpr regex_constants::syntax_option_type extended = regex_constants::extended;
static constexpr regex_constants::syntax_option_type awk = regex_constants::awk;
static constexpr regex_constants::syntax_option_type grep = regex_constants::grep;
static constexpr regex_constants::syntax_option_type egrep = regex_constants::egrep;
static constexpr regex_constants::syntax_option_type multiline = regex_constants::multiline;

The static constant members are provided as synonyms for the constants declared in namespace regex_constants.

31.8.2 basic_regex constructors [re.regex.construct]

basic_regex();

Effects: Constructs an object of class basic_regex that does not match any character sequence.

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

Requires: p shall not be a null pointer.

Throws: regex_error if p is not a valid regular expression.

Effects: Constructs an object of class basic_regex; the object's internal finite state machine is constructed from the regular expression contained in the array of charT of length char_traits<charT>::length(p) whose first element is designated by p, and interpreted according to the flags f.

Postconditions: flags() returns f. mark_count() returns the number of marked sub-expressions within the expression.

basic_regex(const charT* p, size_t len, flag_type f);

Requires: p shall not be a null pointer.

Throws: regex_error if p is not a valid regular expression.

Effects: Constructs an object of class basic_regex; 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.

Postconditions: flags() returns f. mark_count() returns the number of marked sub-expressions within the expression.

basic_regex(const basic_regex& e);

Effects: Constructs an object of class basic_regex as a copy of the object e.

Postconditions: flags() and mark_count() return e.flags() and e.mark_count(), respectively.

basic_regex(basic_regex&& e) noexcept;

Effects: Move constructs an object of class basic_regex from e.

Postconditions: flags() and mark_count() return the values that e.flags() and e.mark_count(), respectively, had before construction. e is in a valid state with unspecified value.

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

Throws: regex_error if s is not a valid regular expression.

Effects: Constructs an object of class basic_regex; 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.

Postconditions: flags() returns f. mark_count() returns the number of marked sub-expressions within the expression.

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

Throws: regex_error if the sequence [first, last) is not a valid regular expression.

Effects: Constructs an object of class basic_regex; 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.

Postconditions: flags() returns f. mark_count() returns the number of marked sub-expressions within the expression.

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

Effects: Same as basic_regex(il.begin(), il.end(), f).

31.8.3 basic_regex assign [re.regex.assign]

basic_regex& operator=(const basic_regex& e);

Effects: Copies e into *this and returns *this.

Postconditions: flags() and mark_count() return e.flags() and e.mark_count(), respectively.

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

Effects: Move assigns from e into *this and returns *this.

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* ptr);

Requires: ptr shall not be a null pointer.

Effects: Returns assign(ptr).

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

Effects: Returns assign(il.begin(), il.end()).

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

Effects: Returns assign(p).

basic_regex& assign(const basic_regex& that);

Effects: Equivalent to *this = that.

Returns: *this.

basic_regex& assign(basic_regex&& that) noexcept;

Effects: Equivalent to *this = std::move(that).

Returns: *this.

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

Returns: assign(string_type(ptr), f).

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

Returns: assign(string_type(ptr, len), f).

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

Throws: regex_error if s is not a valid regular expression.

Returns: *this.

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.

Postconditions: If no exception is thrown, flags() returns f and mark_count() returns the number of marked sub-expressions within the expression.

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

Requires: The type InputIterator shall satisfy the requirements for an Input Iterator.

Returns: assign(string_type(first, last), f).

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

Effects: Same as assign(il.begin(), il.end(), f).

Returns: *this.

31.8.4 basic_regex constant operations [re.regex.operations]

unsigned mark_count() const;

Effects: Returns the number of marked sub-expressions within the regular expression.

flag_type flags() const;

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.

31.8.5 basic_regex locale [re.regex.locale]

locale_type imbue(locale_type loc);

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;

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.

31.8.6 basic_regex swap [re.regex.swap]

void swap(basic_regex& e);

Effects: Swaps the contents of the two regular expressions.

Postconditions: *this contains the regular expression that was in e, e contains the regular expression that was in *this.

Complexity: Constant time.

31.8.7 basic_regex non-member functions [re.regex.nonmemb]

31.8.7.1 basic_regex non-member swap [re.regex.nmswap]

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

Effects: Calls lhs.swap(rhs).

31 Regular expressions library [re]

31.8 Class template basic_­regex [re.regex]

31.8.1 basic_­regex constants [re.regex.const]

31.8.2 basic_­regex constructors [re.regex.construct]

31.8.3 basic_­regex assign [re.regex.assign]

31.8.4 basic_­regex constant operations [re.regex.operations]

31.8.5 basic_­regex locale [re.regex.locale]

31.8.6 basic_­regex swap [re.regex.swap]

31.8.7 basic_­regex non-member functions [re.regex.nonmemb]

31.8.7.1 basic_­regex non-member swap [re.regex.nmswap]

31.8 Class template basic_regex [re.regex]

31.8.1 basic_regex constants [re.regex.const]

31.8.2 basic_regex constructors [re.regex.construct]

31.8.3 basic_regex assign [re.regex.assign]

31.8.4 basic_regex constant operations [re.regex.operations]

31.8.5 basic_regex locale [re.regex.locale]

31.8.6 basic_regex swap [re.regex.swap]

31.8.7 basic_regex non-member functions [re.regex.nonmemb]

31.8.7.1 basic_regex non-member swap [re.regex.nmswap]