30 Regular expressions library [re]

30.12 Regular expression iterators [re.iter]

30.12.1 Class template regex_­iterator [re.regiter]

1
#
The class template regex_­iterator is an iterator adaptor.
It represents a new view of an existing iterator sequence, by enumerating all the occurrences of a regular expression within that sequence.
A regex_­iterator uses regex_­search to find successive regular expression matches within the sequence from which it was constructed.
After the iterator is constructed, and every time operator++ is used, the iterator finds and stores a value of match_­results<BidirectionalIterator>.
If the end of the sequence is reached (regex_­search returns false), the iterator becomes equal to the end-of-sequence iterator value.
The default constructor constructs an end-of-sequence iterator object, which is the only legitimate iterator to be used for the end condition.
The result of operator* on an end-of-sequence iterator is not defined.
For any other iterator value a const match_­results<BidirectionalIterator>& is returned.
The result of operator-> on an end-of-sequence iterator is not defined.
For any other iterator value a const match_­results<BidirectionalIterator>* is returned.
It is impossible to store things into regex_­iterators.
Two end-of-sequence iterators are always equal.
An end-of-sequence iterator is not equal to a non-end-of-sequence iterator.
Two non-end-of-sequence iterators are equal when they are constructed from the same arguments.
namespace std {
  template<class BidirectionalIterator,
            class charT = typename iterator_traits<BidirectionalIterator>::value_type,
            class traits = regex_traits<charT>>
    class regex_iterator {
    public:
      using regex_type        = basic_regex<charT, traits>;
      using iterator_category = forward_iterator_tag;
      using value_type        = match_results<BidirectionalIterator>;
      using difference_type   = ptrdiff_t;
      using pointer           = const value_type*;
      using reference         = const value_type&;

      regex_iterator();
      regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
                     const regex_type& re,
                     regex_constants::match_flag_type m = regex_constants::match_default);
      regex_iterator(BidirectionalIterator, BidirectionalIterator,
                     const regex_type&&,
                     regex_constants::match_flag_type = regex_constants::match_default) = delete;
      regex_iterator(const regex_iterator&);
      regex_iterator& operator=(const regex_iterator&);
      bool operator==(const regex_iterator&) const;
      const value_type& operator*() const;
      const value_type* operator->() const;
      regex_iterator& operator++();
      regex_iterator operator++(int);

    private:
      BidirectionalIterator                begin;               // exposition only
      BidirectionalIterator                end;                 // exposition only
      const regex_type*                    pregex;              // exposition only
      regex_constants::match_flag_type     flags;               // exposition only
      match_results<BidirectionalIterator> match;               // exposition only
    };
}
2
#
An object of type regex_­iterator that is not an end-of-sequence iterator holds a zero-length match if match[0].matched == true and match[0].first == match[0].second.
[Note
:
For example, this can occur when the part of the regular expression that matched consists only of an assertion (such as '^', '$', '\b', '\B').
— end note
]

30.12.1.1 Constructors [re.regiter.cnstr]

🔗
regex_iterator();
1
#
Effects: Constructs an end-of-sequence iterator.
🔗
regex_iterator(BidirectionalIterator a, BidirectionalIterator b, const regex_type& re, regex_constants::match_flag_type m = regex_constants::match_default);
2
#
Effects: Initializes begin and end to a and b, respectively, sets pregex to addressof(re), sets flags to m, then calls regex_­search(begin, end, match, *pregex, flags).
If this call returns false the constructor sets *this to the end-of-sequence iterator.

30.12.1.2 Comparisons [re.regiter.comp]

🔗
bool operator==(const regex_iterator& right) const;
1
#
Returns: true if *this and right are both end-of-sequence iterators or if the following conditions all hold:
  • (1.1)
    begin == right.begin,
  • (1.2)
    end == right.end,
  • (1.3)
    pregex == right.pregex,
  • (1.4)
    flags == right.flags, and
  • (1.5)
    match[0] == right.match[0];
otherwise false.

30.12.1.3 Indirection [re.regiter.deref]

🔗
const value_type& operator*() const;
1
#
Returns: match.
🔗
const value_type* operator->() const;
2
#
Returns: addressof(match).

30.12.1.4 Increment [re.regiter.incr]

🔗
regex_iterator& operator++();
1
#
Effects: Constructs a local variable start of type BidirectionalIterator and initializes it with the value of match[0].second.
2
#
If the iterator holds a zero-length match and start == end the operator sets *this to the end-of-sequence iterator and returns *this.
3
#
Otherwise, if the iterator holds a zero-length match, the operator calls: 
regex_search(start, end, match, *pregex,
             flags | regex_constants::match_not_null | regex_constants::match_continuous)
If the call returns true the operator returns *this.
Otherwise the operator increments start and continues as if the most recent match was not a zero-length match.
4
#
If the most recent match was not a zero-length match, the operator sets flags to flags | regex_­constants​::​match_­prev_­avail and calls regex_­search(start, end, match, *pregex, flags).
If the call returns false the iterator sets *this to the end-of-sequence iterator.
The iterator then returns *this.
5
#
In all cases in which the call to regex_­search returns true, match.prefix().first shall be equal to the previous value of match[0].second, and for each index i in the half-open range [0, match.size()) for which match[i].matched is true, match.position(i) shall return distance(begin, match[i].​first).
6
#
[Note
:
This means that match.position(i) gives the offset from the beginning of the target sequence, which is often not the same as the offset from the sequence passed in the call to regex_­search.
— end note
]
7
#
It is unspecified how the implementation makes these adjustments.
8
#
[Note
:
This means that a compiler may call an implementation-specific search function, in which case a program-defined specialization of regex_­search will not be called.
— end note
]
🔗
regex_iterator operator++(int);
9
#
Effects: As if by: 
regex_iterator tmp = *this;
++(*this);
return tmp;