30 Regular expressions library [re]

30.10 Class template match_­results [re.results]

1
#
Class template match_­results denotes a collection of character sequences representing the result of a regular expression match.
Storage for the collection is allocated and freed as necessary by the member functions of class template match_­results.
2
#
The class template match_­results meets the requirements of an allocator-aware container and of a sequence container ([container.requirements.general], [sequence.reqmts]) except that only copy assignment, move assignment, and operations defined for const-qualified sequence containers are supported and that the semantics of comparison functions are different from those required for a container.
3
#
A default-constructed match_­results object has no fully established result state.
A match result is ready when, as a consequence of a completed regular expression match modifying such an object, its result state becomes fully established.
The effects of calling most member functions from a match_­results object that is not ready are undefined.
4
#
The sub_­match object stored at index 0 represents sub-expression 0, i.e., the whole match.
In this case the sub_­match member matched is always true.
The sub_­match object stored at index n denotes what matched the marked sub-expression n within the matched expression.
If the sub-expression n participated in a regular expression match then the sub_­match member matched evaluates to true, and members first and second denote the range of characters [first, second) which formed that match.
Otherwise matched is false, and members first and second point to the end of the sequence that was searched.
[Note
:
The sub_­match objects representing different sub-expressions that did not participate in a regular expression match need not be distinct.
— end note
]
namespace std {
  template<class BidirectionalIterator,
           class Allocator = allocator<sub_match<BidirectionalIterator>>>
    class match_results {
    public:
      using value_type      = sub_match<BidirectionalIterator>;
      using const_reference = const value_type&;
      using reference       = value_type&;
      using const_iterator  = implementation-defined;
      using iterator        = const_iterator;
      using difference_type =
              typename iterator_traits<BidirectionalIterator>::difference_type;
      using size_type       = typename allocator_traits<Allocator>::size_type;
      using allocator_type  = Allocator;
      using char_type       =
              typename iterator_traits<BidirectionalIterator>::value_type;
      using string_type     = basic_string<char_type>;

      // [re.results.const], construct/copy/destroy
      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();

      // [re.results.state], state
      bool ready() const;

      // [re.results.size], size
      size_type size() const;
      size_type max_size() const;
      [[nodiscard]] bool empty() const;

      // [re.results.acc], element access
      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;

      // [re.results.form], format
      template<class OutputIter>
        OutputIter
          format(OutputIter out,
                 const char_type* fmt_first, const char_type* fmt_last,
                 regex_constants::match_flag_type flags = regex_constants::format_default) const;
      template<class OutputIter, class ST, class SA>
        OutputIter
          format(OutputIter 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;

      // [re.results.all], allocator
      allocator_type get_allocator() const;

      // [re.results.swap], swap
      void swap(match_results& that);
    };
}

30.10.1 Constructors [re.results.const]

🔗
explicit match_results(const Allocator& a);
1
#
Postconditions: ready() returns false.
size() returns 0.
🔗
match_results(match_results&& m) noexcept;
2
#
Effects: The stored Allocator value is move constructed from m.get_­allocator().
3
#
Postconditions: As specified in Table 140.
🔗
match_results& operator=(const match_results& m);
4
#
Postconditions: As specified in Table 140.
🔗
match_results& operator=(match_results&& m);
5
#
Postconditions: As specified in Table 140.
Table 140: match_­results assignment operator effects   [tab:re.results.const]
Element
Value
ready()
m.ready()
size()
m.size()
str(n)
m.str(n) for all integers n < m.size()
prefix()
m.prefix()
suffix()
m.suffix()
(*this)[n]
m[n] for all integers n < m.size()
length(n)
m.length(n) for all integers n < m.size()
position(n)
m.position(n) for all integers n < m.size()

30.10.2 State [re.results.state]

🔗
bool ready() const;
1
#
Returns: true if *this has a fully established result state, otherwise false.

30.10.3 Size [re.results.size]

🔗
size_type size() const;
1
#
Returns: One plus the number of marked sub-expressions in the regular expression that was matched if *this represents the result of a successful match.
Otherwise returns 0.
[Note
:
The state of a match_­results object can be modified only by passing that object to regex_­match or regex_­search.
Subclauses [re.alg.match] and [re.alg.search] specify the effects of those algorithms on their match_­results arguments.
— end note
]
🔗
size_type max_size() const;
2
#
Returns: The maximum number of sub_­match elements that can be stored in *this.
🔗
[[nodiscard]] bool empty() const;
3
#
Returns: size() == 0.

30.10.4 Element access [re.results.acc]

🔗
difference_type length(size_type sub = 0) const;
1
#
Preconditions: ready() == true.
2
#
Returns: (*this)[sub].length().
🔗
difference_type position(size_type sub = 0) const;
3
#
Preconditions: ready() == true.
4
#
Returns: The distance from the start of the target sequence to (*this)[sub].first.
🔗
string_type str(size_type sub = 0) const;
5
#
Preconditions: ready() == true.
6
#
Returns: string_­type((*this)[sub]).
🔗
const_reference operator[](size_type n) const;
7
#
Preconditions: ready() == true.
8
#
Returns: A reference to the sub_­match object representing the character sequence that matched marked sub-expression n.
If n == 0 then returns a reference to a sub_­match object representing the character sequence that matched the whole regular expression.
If n >= size() then returns a sub_­match object representing an unmatched sub-expression.
🔗
const_reference prefix() const;
9
#
Preconditions: ready() == true.
10
#
Returns: A reference to the sub_­match object representing the character sequence from the start of the string being matched/searched to the start of the match found.
🔗
const_reference suffix() const;
11
#
Preconditions: ready() == true.
12
#
Returns: A reference to the sub_­match object representing the character sequence from the end of the match found to the end of the string being matched/searched.
🔗
const_iterator begin() const; const_iterator cbegin() const;
13
#
Returns: A starting iterator that enumerates over all the sub-expressions stored in *this.
🔗
const_iterator end() const; const_iterator cend() const;
14
#
Returns: A terminating iterator that enumerates over all the sub-expressions stored in *this.

30.10.5 Formatting [re.results.form]

🔗
template<class OutputIter> OutputIter format( OutputIter out, const char_type* fmt_first, const char_type* fmt_last, regex_constants::match_flag_type flags = regex_constants::format_default) const;
1
#
Preconditions: ready() == true and OutputIter meets the requirements for a Cpp17OutputIterator ([output.iterators]).
2
#
Effects: Copies the character sequence [fmt_­first, fmt_­last) to OutputIter out.
Replaces each format specifier or escape sequence in the copied range with either the character(s) it represents or the sequence of characters within *this to which it refers.
The bitmasks specified in flags determine which format specifiers and escape sequences are recognized.
3
#
Returns: out.
🔗
template<class OutputIter, class ST, class SA> OutputIter format( OutputIter out, const basic_string<char_type, ST, SA>& fmt, regex_constants::match_flag_type flags = regex_constants::format_default) const;
4
#
Effects: Equivalent to: 
return format(out, fmt.data(), fmt.data() + fmt.size(), flags);
🔗
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;
5
#
Preconditions: ready() == true.
6
#
Effects: Constructs an empty string result of type basic_­string<char_­type, ST, SA> and calls: 
format(back_inserter(result), fmt, flags);
7
#
Returns: result.
🔗
string_type format( const char_type* fmt, regex_constants::match_flag_type flags = regex_constants::format_default) const;
8
#
Preconditions: ready() == true.
9
#
Effects: Constructs an empty string result of type string_­type and calls: 
format(back_inserter(result), fmt, fmt + char_traits<char_type>::length(fmt), flags);
10
#
Returns: result.

30.10.6 Allocator [re.results.all]

🔗
allocator_type get_allocator() const;
1
#
Returns: A copy of the Allocator that was passed to the object's constructor or, if that allocator has been replaced, a copy of the most recent replacement.

30.10.7 Swap [re.results.swap]

🔗
void swap(match_results& that);
1
#
Effects: Swaps the contents of the two sequences.
2
#
Postconditions: *this contains the sequence of matched sub-expressions that were in that, that contains the sequence of matched sub-expressions that were in *this.
3
#
Complexity: Constant time.
🔗
template<class BidirectionalIterator, class Allocator> void swap(match_results<BidirectionalIterator, Allocator>& m1, match_results<BidirectionalIterator, Allocator>& m2);
4
#
Effects: As if by m1.swap(m2).

30.10.8 Non-member functions [re.results.nonmember]

🔗
template<class BidirectionalIterator, class Allocator> bool operator==(const match_results<BidirectionalIterator, Allocator>& m1, const match_results<BidirectionalIterator, Allocator>& m2);
1
#
Returns: true if neither match result is ready, false if one match result is ready and the other is not.
If both match results are ready, returns true only if:
  • (1.1)
    m1.empty() && m2.empty(), or
  • (1.2)
    !m1.empty() && !m2.empty(), and the following conditions are satisfied:
    • (1.2.1)
      m1.prefix() == m2.prefix(),
    • (1.2.2)
      m1.size() == m2.size() && equal(m1.begin(), m1.end(), m2.begin()), and
    • (1.2.3)
      m1.suffix() == m2.suffix().
[Note
:
The algorithm equal is defined in [algorithms].
— end note
]