# std::regex_iterator

From cppreference.com
< cpp‎ | regex

template< class BidirIt, class CharT = typename std::iterator_traits <BidirIt>::value_type, class Traits = std::regex_traits <CharT> > class regex_iterator |  | (since C++11)

`std::regex_iterator` is a read-only iterator that accesses the individual matches of a regular expression within the underlying character sequence. It meets the requirements of a LegacyForwardIterator, except that for dereferenceable values `a` and `b` with `a == b`, `*a` and `*b` will not be bound to the same object.

On construction, and on every increment, it calls std::regex_search and remembers the result (that is, saves a copy of the value std::match_results <BidirIt>). The first object may be read when the iterator is constructed or when the first dereferencing is done. Otherwise, dereferencing only returns a copy of the most recently obtained regex match.

The default-constructed `std::regex_iterator` is the end-of-sequence iterator. When a valid `std::regex_iterator` is incremented after reaching the last match (std::regex_search returns false), it becomes equal to the end-of-sequence iterator. Dereferencing or incrementing it further invokes undefined behavior.

A typical implementation of `std::regex_iterator` holds the begin and the end iterators for the underlying sequence (two instances of BidirIt), a pointer to the regular expression (const regex_type*), the match flags (std::regex_constants::match_flag_type), and the current match (std::match_results <BidirIt>).

### Type requirements

- `BidirIt` must meet the requirements of LegacyBidirectionalIterator.

### Specializations

Several specializations for common character sequence types are defined:

Defined in header `<regex>`
Type | Definition
`cregex_iterator` | regex_iterator<const char*>
`wcregex_iterator` | regex_iterator<const wchar_t*>
`sregex_iterator` | regex_iterator<std::string::const_iterator>
`wsregex_iterator` | regex_iterator<std::wstring::const_iterator>

### Member types

Member type | Definition
`value_type` | std::match_results <BidirIt>
`difference_type` | std::ptrdiff_t
`pointer` | const value_type*
`reference` | const value_type&
`iterator_category` | std::forward_iterator_tag
`regex_type` | basic_regex<CharT, Traits>

### Member functions

(constructor) | constructs a new `regex_iterator` (public member function)
(destructor) (implicitly declared) | destructs a `regex_iterator`, including the cached value (public member function)
operator= | assigns contents (public member function)
operator==operator!= | compares two `regex_iterator`s (public member function)
operator*operator-> | accesses the current match (public member function)
operator++operator++(int) | advances the iterator to the next match (public member function)

### Notes

It is the programmer's responsibility to ensure that the std::basic_regex object passed to the iterator's constructor outlives the iterator. Because the iterator stores a pointer to the regex, incrementing the iterator after the regex was destroyed accesses a dangling pointer.

If the part of the regular expression that matched is just an assertion (`^`, `$`, `\b`, `\B`), the match stored in the iterator is a zero-length match, that is, match[0].first == match[0].second.

### Example

Run this code

    #include <regex>
    #include <iterator>
    #include <iostream>
    #include <string>

    int main()
    {
        const std::string s = "Quick brown fox.";

        std::regex words_regex("[^\\s]+");
        auto words_begin =
            std::sregex_iterator(s.begin(), s.end(), words_regex);
        auto words_end = std::sregex_iterator();

        std::cout << "Found "
                  << std::distance(words_begin, words_end)
                  << " words:\n";

        for (std::sregex_iterator i = words_begin; i != words_end; ++i) {
            std::smatch match = *i;
            std::string match_str = match.str();
            std::cout << match_str << '\n';
        }
    }

Output:

    Found 3 words:
    Quick
    brown
    fox.

### See also

match_results (C++11) | identifies one regular expression match, including all sub-expression matches (class template)
regex_search (C++11) | check if a regular expression occurs anywhere within a string (function template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/regex/regex_iterator&oldid=103642"