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

NAME
     std::regex_match - std::regex_match

Synopsis
	Defined in header <regex>
	template< class BidirIt,

		  class Alloc, class CharT, class Traits >
	bool regex_match( BidirIt first, BidirIt last,
			  std::match_results<BidirIt,  Alloc>&	m,	     (1)
     (since C++11)
			  const std::basic_regex<CharT, Traits>& e,
			  std::regex_constants::match_flag_type flags =

			      std::regex_constants::match_default );
	template< class BidirIt,

		  class CharT, class Traits >
	bool regex_match( BidirIt first, BidirIt  last, 		     (2)
     (since C++11)
			  const std::basic_regex<CharT, Traits>& e,
			  std::regex_constants::match_flag_type flags =

			      std::regex_constants::match_default );
	template< class CharT, class Alloc, class Traits >

	bool regex_match( const CharT* str,
			  std::match_results<const  CharT*,  Alloc>& m,      (3)
     (since C++11)
			  const std::basic_regex<CharT, Traits>& e,
			  std::regex_constants::match_flag_type flags =

			      std::regex_constants::match_default );
	template< class STraits, class SAlloc,

		  class Alloc, class CharT, class Traits >
	bool regex_match( const std::basic_string<CharT, STraits, SAlloc>&
	s,
			  std::match_results<
			      typename std::basic_string<CharT,  STraits,    (4)
     (since C++11)
	SAlloc>::
				  const_iterator,
			      Alloc>& m,
			  const std::basic_regex<CharT, Traits>& e,
			  std::regex_constants::match_flag_type flags =

			      std::regex_constants::match_default );
	template< class CharT, class Traits >

	bool regex_match( const CharT* str,
			  const  std::basic_regex<CharT,  Traits>& e,	     (5)
     (since C++11)
			  std::regex_constants::match_flag_type flags =

			      std::regex_constants::match_default );
	template< class STraits, class SAlloc,

		  class CharT, class Traits >
	bool regex_match( const std::basic_string<CharT, STraits, SAlloc>&
	s,								     (6)
     (since C++11)
			  const std::basic_regex<CharT, Traits>& e,
			  std::regex_constants::match_flag_type flags =

			      std::regex_constants::match_default );
	template< class STraits, class SAlloc,

		  class Alloc, class CharT, class Traits >
	bool regex_match( const std::basic_string<CharT, STraits,
	SAlloc>&&,
			  std::match_results<
			      typename std::basic_string<CharT, STraits,
	SAlloc>::							     (7)
     (since C++11)
				  const_iterator,
			      Alloc>&,
			  const std::basic_regex<CharT, Traits>&,
			  std::regex_constants::match_flag_type flags =

			      std::regex_constants::match_default ) =
	delete;

	Determines if the regular expression e matches the entire target charac-
     ter sequence,
	which may be specified as std::string, a C-string, or an iterator pair.

	1) Determines if there is a match between the regular expression  e  and
     the entire
	target	character sequence [first, last), taking into account the effect
     of flags.
	When determining if there is a match, only potential matches that  match
     the entire
	character sequence are considered. Match results are returned in m.
	2) Behaves as (1) above, omitting the match results.
	3)	    Returns	     std::regex_match(str,	   str	       +
     std::char_traits<CharT>::length(str), m, e,
	flags).
	4) Returns std::regex_match(s.begin(), s.end(), m, e, flags).
	5)	   Returns	   std::regex_match(str,	  str	       +
     std::char_traits<CharT>::length(str), e,
	flags).
	6) Returns std::regex_match(s.begin(), s.end(), e, flags).
	7) The overload (4) is prohibited from accepting temporary strings, oth-
     erwise this
	function populates match_results m with string iterators that become in-
     valid
	immediately.

	Note  that regex_match will only successfully match a regular expression
     to an entire
	character sequence, whereas std::regex_search  will  successfully  match
     subsequences.

Parameters
	first, last - the target character range to apply the regex to, given as
     iterators
	m	    - the match results
	str	     -	the  target  string,  given as a null-terminated C-style
     string
	s	    - the target string, given as a std::basic_string
	e	    - the regular expression
	flags	    - flags used to determine how the match will be performed

Type requirements
	-
	BidirIt must meet the requirements of LegacyBidirectionalIterator.

Return value
	Returns true if a match exists, false otherwise. In either case, the ob-
     ject m is
	updated, as follows:

	If the match does not exist:

	m.ready() == true
	m.empty() == true
	m.size() == 0

	If the match exists:

	m.ready()	   true
	m.empty()	   false
	m.size()	   number of marked subexpressions plus 1, that is, 1 +
			   e.mark_count()
	m.prefix().first   first
	m.prefix().second  first
	m.prefix().matched false (the match prefix is empty)
	m.suffix().first   last
	m.suffix().second  last
	m.suffix().matched false (the match suffix is empty)
	m[0].first	   first
	m[0].second	   last
	m[0].matched	   true (the entire sequence is matched)
	m[n].first	   the start of the sequence that matched marked sub-ex-
     pression n,
			   or last if the subexpression did not  participate  in
     the match
	m[n].second	    the  end of the sequence that matched marked sub-ex-
     pression n, or
			   last if the subexpression did not participate in  the
     match
	m[n].matched	    true  if sub-expression n participated in the match,
     false
			   otherwise

Notes
	Because regex_match only considers full matches, the same regex may give
     different
	matches between regex_match and std::regex_search:

      std::regex re("Get|GetValue");
      std::cmatch m;
      std::regex_search("GetValue", m, re);  // returns true, and m[0]	contains
     "Get"
      std::regex_match	("GetValue", m, re);  // returns true, and m[0] contains
     "GetValue"
      std::regex_search("GetValues", m, re); // returns true, and m[0]	contains
     "Get"
      std::regex_match ("GetValues", m, re); // returns false

Example
     // Run this code

      #include <cstddef>
      #include <iostream>
      #include <regex>
      #include <string>

      int main()
      {
	  // Simple regular expression matching
	  const  std::string fnames[] = {"foo.txt", "bar.txt", "baz.dat", "zoid-
     berg"};
	  const std::regex txt_regex("[a-z]+\\.txt");

	  for (const auto& fname : fnames)
	      std::cout << fname << ": " <<  std::regex_match(fname,  txt_regex)
     << '\n';

	  // Extraction of a sub-match
	  const std::regex base_regex("([a-z]+)\\.txt");
	  std::smatch base_match;

	  for (const auto& fname : fnames)
	      if (std::regex_match(fname, base_match, base_regex))
		  // The first sub_match is the whole string; the next
		  // sub_match is the first parenthesized expression.
		  if (base_match.size() == 2)
		  {
		      std::ssub_match base_sub_match = base_match[1];
		      std::string base = base_sub_match.str();
		      std::cout << fname << " has a base of " << base << '\n';
		  }

	  // Extraction of several sub-matches
	  const std::regex pieces_regex("([a-z]+)\\.([a-z]+)");
	  std::smatch pieces_match;

	  for (const auto& fname : fnames)
	      if (std::regex_match(fname, pieces_match, pieces_regex))
	      {
		  std::cout << fname << '\n';
		  for (std::size_t i = 0; i < pieces_match.size(); ++i)
		  {
		      std::ssub_match sub_match = pieces_match[i];
		      std::string piece = sub_match.str();
		      std::cout << "  submatch " << i << ": " << piece << '\n';
		  }
	      }
      }

Output:
      foo.txt: 1
      bar.txt: 1
      baz.dat: 0
      zoidberg: 0
      foo.txt has a base of foo
      bar.txt has a base of bar
      foo.txt
	submatch 0: foo.txt
	submatch 1: foo
	submatch 2: txt
      bar.txt
	submatch 0: bar.txt
	submatch 1: bar
	submatch 2: txt
      baz.dat
	submatch 0: baz.dat
	submatch 1: baz
	submatch 2: dat

	Defect reports

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

	   DR	 Applied to	      Behavior as published		 Correct
     behavior
			    basic_string rvalues were accepted,  which	rejected
     via a deleted
	LWG 2329 C++11	    was likely to result in dangling	      overload
			    iterators

See also
	basic_regex   regular expression object
	(C++11)       (class template)
	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_match(3)
home | help