< cpp‎ | regex

    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 ForwardIterator, 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>).


[edit] Type requirements

BidirIt must meet the requirements of BidirectionalIterator.

[edit] 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>

[edit] 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>

[edit] Member functions

constructs a new regex_iterator
(public member function) [edit]
(implicitly declared)
destructs a regex_iterator, including the cached value
(public member function) [edit]
assigns contents
(public member function) [edit]
compares two regex_iterators
(public member function) [edit]
accesses the current match
(public member function) [edit]
advances the iterator to the next match
(public member function) [edit]

[edit] 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.

[edit] Example

#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';


Found 3 words:

[edit] See also

identifies one regular expression match, including all sub-expression matches
(class template) [edit]
check if a regular expression occurs anywhere within a string
(function template)