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:
typedef basic_regex<charT, traits> regex_type;
typedef match_results<BidirectionalIterator> value_type;
typedef std::ptrdiff_t difference_type;
typedef const value_type* pointer;
typedef const value_type& reference;
typedef std::forward_iterator_tag iterator_category;
regex_iterator();
regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
const regex_type& re,
regex_constants::match_flag_type m =
regex_constants::match_default);
regex_iterator(const regex_iterator&);
regex_iterator& operator=(const regex_iterator&);
bool operator==(const regex_iterator&) const;
bool operator!=(const regex_iterator&) const;
const value_type& operator*() const;
const value_type* operator->() const;
regex_iterator& operator++();
regex_iterator operator++(int);
private:
// these members are shown for exposition only:
BidirectionalIterator begin;
BidirectionalIterator end;
const regex_type* pregex;
regex_constants::match_flag_type flags;
match_results<BidirectionalIterator> match;
};
}
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 ]
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);
Effects: Initializes begin and end to a and b, respectively, sets pregex to &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.
bool operator==(const regex_iterator& right) const;
bool operator!=(const regex_iterator& right) const;
Returns: !(*this == right).
const value_type& operator*() const;
Returns: match.
const value_type* operator->() const;
Returns: &match.
Effects: Constructs a local variable start of type BidirectionalIterator and initializes it with the value of match[0].second.
If the iterator holds a zero-length match and start == end the operator sets *this to the end-of-sequence iterator and returns *this.
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.
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[i].position() shall return distance(begin, match[i].first).
[ Note: This means that match[i].position() 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 ]
It is unspecified how the implementation makes these adjustments.
[ Note: This means that a compiler may call an implementation-specific search function, in which case a user-defined specialization of regex_search will not be called. — end note ]
regex_iterator operator++(int);
Effects:
regex_iterator tmp = *this; ++(*this); return tmp;