Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::regex_iterator(3)	      C++ Standard Libary	std::regex_iterator(3)

NAME
       std::regex_iterator - std::regex_iterator

Synopsis
	  Defined in header <regex>
	  template<

	      class BidirIt,
	      class	    CharT	  =	   typename	   std::itera-
       tor_traits<BidirIt>::value_type,	 (since	C++11)
	      class Traits = std::regex_traits<CharT>

	  > class regex_iterator

	  std::regex_iterator is a read-only iterator that accesses the	 indi-
       vidual matches of
	  a  regular  expression  within the underlying	character sequence. It
       meets the
	  requirements of a LegacyForwardIterator, except  that	 for  derefer-
       enceable	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 std::match_results<BidirIt>
       value). 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 de-
       fined:

	  Defined in header <regex>
	  Type			Definition
	  std::cregex_iterator	std::regex_iterator<const char*>
	  std::wcregex_iterator	std::regex_iterator<const wchar_t*>
	  std::sregex_iterator	 std::regex_iterator<std::string::const_itera-
       tor>
	  std::wsregex_iterator	std::regex_iterator<std::wstring::const_itera-
       tor>

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
	  iterator_concept (C++20) std::input_iterator_tag
	  regex_type		   std::basic_regex<CharT, Traits>

Member functions
	  constructor		constructs a new regex_iterator
				(public	member function)
	  destructor		 destructs  a  regex_iterator,	including  the
       cached value
	  (implicitly declared)	(public	member function)
	  operator=		assigns	contents
				(public	member function)
	  operator==		compares two regex_iterators
	  operator!=		(public	member function)
	  (removed in C++20)
	  operator*		accesses the current match
	  operator->		(public	member function)
	  operator++		advances the iterator to the next match
	  operator++(int)	(public	member function)

Notes
	  It is	the programmer's responsibility	to ensure  that	 the  std::ba-
       sic_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	asser-
       tion (^,	$, \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 <iostream>
	#include <iterator>
	#include <regex>
	#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.

	  Defect reports

	  The following	behavior-changing defect reports were applied retroac-
       tively to
	  previously published C++ standards.

	     DR	    Applied to	       Behavior	as  published		  Cor-
       rect behavior
	  LWG  3698  C++20	regex_iterator was a forward_iterator made in-
       put_iterator^[1]
	  (P2770R0)	       while being a stashing iterator

	   1.  iterator_category was  unchanged	 by  the  resolution,  because
       changing	it to
	      std::input_iterator_tag might break too much existing code.

See also
	  match_results	identifies one regular expression match, including all
       sub-expression
	  (C++11)	matches
			(class template)
	  regex_search	 attempts to match a regular expression	to any part of
       a character
	  (C++11)	sequence
			(function template)

http://cppreference.com		  2024.06.10		std::regex_iterator(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::regex_iterator&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help