28 Regular expressions library [re]

28.12 Regular expression iterators [re.iter]

28.12.1 Class template regex_iterator [re.regiter]

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 ]

28.12.1.1 regex_iterator constructors [re.regiter.cnstr]

regex_iterator();

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.

28.12.1.2 regex_iterator comparisons [re.regiter.comp]

bool operator==(const regex_iterator& right) const;

Returns: true if *this and right are both end-of-sequence iterators or if the following conditions all hold:

  • begin == right.begin,

  • end == right.end,

  • pregex == right.pregex,

  • flags == right.flags, and

  • match[0] == right.match[0];

otherwise false.

bool operator!=(const regex_iterator& right) const;

Returns: !(*this == right).

28.12.1.3 regex_iterator dereference [re.regiter.deref]

const value_type& operator*() const;

Returns: match.

const value_type* operator->() const;

Returns: &match.

28.12.1.4 regex_iterator increment [re.regiter.incr]

regex_iterator& operator++();

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.

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.

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;