32 Regular expressions library [re]

32.11 Regular expression iterators [re.iter]

32.11.1 Class template regex_iterator [re.regiter] General [re.regiter.general]

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 iterator_concept = input_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; bool operator==(default_sentinel_t) const { return *this == regex_iterator(); } 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 }; }
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 1: 
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]