std::regex_iterator

 

C++

Language

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Regular expressions library

Classes

basic_regex (C++11)

sub_match (C++11)

match_results (C++11)

Algorithms

regex_match (C++11)

regex_search (C++11)

regex_replace (C++11)

Iterators

regex_iterator (C++11)

regex_token_iterator (C++11)

Exceptions

regex_error (C++11)

Traits

regex_traits (C++11)

Constants

syntax_option_type (C++11)

match_flag_type (C++11)

error_type (C++11)

 

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

std::regex_iterator is a read-only ForwardIterator that accesses the individual matches of a regular expression within the underlying character sequence.

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<BidirectionalIterator>). 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 BidirectionalIterator), a pointer to the regular expression (const regex_type*) and the match flags (std::regex_constants::match_flag_type), and the current match (std::match_results<BidirectionalIterator>).

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<BidirectionalIterator>
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=	replaces a regex_iterator (public member function)
operator== operator!=	compares two regex_iterators (public member function)
operator* operator->	obtains a reference to the current match accesses a member of the current match (public member function)
operator++ operator++(int)	advances the regex_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

#include <regex>
#include <iterator>
#include <iostream>
 
int main()
{
    const std::string text = "Quick brown fox.";
 
    std::regex re("[^\\s]+");
    auto beg = std::sregex_iterator(text.begin(), text.end(), re);
    auto end = std::sregex_iterator();
 
    std::cout << "The number of words is " << std::distance(beg, end) << '\n';
}

Output:

The number of words is 3

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)