function template
<regex>

std::regex_match

C-strings (1)
template <class charT, class traits>
  bool regex_match (const charT* s, const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
strings (2)
template <class ST, class SA, char charT, class traits>
  bool regex_match (const basic_string<charT,ST,SA>& s,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
ranges (3)
template <class BidirectionalIterator, class charT, class traits>
  bool regex_match (BidirectionalIterator first, BidirectionalIterator last,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
with match_results (4,5,6)
template <class charT, class Alloc, class traits>
  bool regex_match (const charT* s, match_results<const charT*, Alloc>& m,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
template <class ST, class SA, class Alloc, class charT, class traits>
  bool regex_match (const basic_string<charT,ST,SA>& s,
          match_results<typename basic_string<charT,ST,SA>::const_iterator,Alloc>& m,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
template <class BidirectionalIterator, class Alloc, class charT, class traits>
  bool regex_match (BidirectionalIterator first, BidirectionalIterator last,
          match_results<BidirectionalIterator, Alloc>& m,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
C-strings (1)
template <class charT, class traits>
  bool regex_match (const charT* s, const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
strings (2)
template <class ST, class SA, char charT, class traits>
  bool regex_match (const basic_string<charT,ST,SA>& s,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
ranges (3)
template <class BidirectionalIterator, class charT, class traits>
  bool regex_match (BidirectionalIterator first, BidirectionalIterator last,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
with match_results (4,5,6)
template <class charT, class Alloc, class traits>
  bool regex_match (const charT* s, match_results<const charT*, Alloc>& m,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
template <class ST, class SA, class Alloc, class charT, class traits>
  bool regex_match (const basic_string<charT,ST,SA>& s,
          match_results<typename basic_string<charT,ST,SA>::const_iterator,Alloc>& m,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
template <class BidirectionalIterator, class Alloc, class charT, class traits>
  bool regex_match (BidirectionalIterator first, BidirectionalIterator last,
          match_results<BidirectionalIterator, Alloc>& m,
          const basic_regex<charT,traits>& rgx,
          regex_constants::match_flag_type flags = regex_constants::match_default);
moving string (deleted) (7)
template <class ST, class SA, class Alloc, class charT, class traits>
  bool regex_match (const basic_string<charT,ST,SA>&&,
          match_results<typename basic_string<charT,ST,SA>::const_iterator,Alloc>&,
          const basic_regex<charT,traits>&,
          regex_constants::match_flag_type=regex_constants::match_default) = delete;
Match sequence
Returns whether the target sequence matches the regular expression rgx. The target sequence is either s or the character sequence between first and last, depending on the version used.

The versions 4, 5 and 6, are identical to 1, 2 and 3 respectively , except that they take an object of a match_results type as argument, which is filled with information about the match results.

Deleting the signature with a moving string (7) prevents the construction with a temporary string object.

An optional parameter, flags, allows to specify options on how to match the expression.

The entire target sequence must match the regular expression for this function to return true (i.e., without any additional characters before or after the match). For a function that returns true when the match is only part of the sequence, see regex_search.

Parameters

s
A string with the target sequence (the subject) against which the regex expression is matched.
rgx
A basic_regex object (the pattern) to match.
flags
Flags used to control how rgx is matched.
One or more of these constants can be combined (using the bitwise OR operator, |) to form a valid bitmask value of type regex_constants::match_flag_type:
flag*effects on matchnotes
match_defaultDefaultDefault matching behavior.
This constant has a value of zero**.
match_not_bolNot Beginning-Of-LineThe first character is not considered a beginning of line ("^" does not match).
match_not_eolNot End-Of-LineThe last character is not considered an end of line ("$" does not match).
match_not_bowNot Beginning-Of-WordThe escape sequence "\b" does not match as a beginning-of-word.
match_not_eowNot End-Of-WordThe escape sequence "\b" does not match as an end-of-word.
match_anyAny matchAny match is acceptable if more than one match is possible.
match_not_nullNot nullEmpty sequences do not match.
match_continuousContinuousThe expression must match a sub-sequence that begins at the first character.
Sub-sequences must begin at the first character to match.
match_prev_availPrevious AvailableOne or more characters exist before the first one. (match_not_bol and match_not_bow are ignored)
format_defaultDefaultSame as match_default.
This constant has a value of zero**.
format_sedNoneIgnored by this function.
See regex_constants for more info.
format_no_copy
format_first_only
* These bitmask flag names are available under the std::regex_constants namespace (see regex_constants for more details).
** Constants with a value of zero are ignored if some other flag is set.
match_flag_type is a type available under the std::regex_constants namespace.
first, last
Bidirectional iterators to the initial and final positions in the range of characters used as target sequence for the match. The range used is [first,last), which includes all the characters between first and last, including the character pointed by first but not the character pointed by last.
The function template type can be any type of bidirectional iterator to characters.
m
Object of a match_results type (such as cmatch or smatch) that is filled by this function with information about the match results and any submatches found.
The type of the match_results object shall be instantiated with the appropriate iterator type to iterate through the characters in the character sequence s (or between begin and end).

Return value

true if rgx is matched against the target sequence. false otherwise.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// regex_match example
#include <iostream>
#include <string>
#include <regex>

int main ()
{

  if (std::regex_match ("subject", std::regex("(sub)(.*)") ))
    std::cout << "string literal matched\n";

  const char cstr[] = "subject";
  std::string s ("subject");
  std::regex e ("(sub)(.*)");

  if (std::regex_match (s,e))
    std::cout << "string object matched\n";

  if ( std::regex_match ( s.begin(), s.end(), e ) )
    std::cout << "range matched\n";

  std::cmatch cm;    // same as std::match_results<const char*> cm;
  std::regex_match (cstr,cm,e);
  std::cout << "string literal with " << cm.size() << " matches\n";

  std::smatch sm;    // same as std::match_results<string::const_iterator> sm;
  std::regex_match (s,sm,e);
  std::cout << "string object with " << sm.size() << " matches\n";

  std::regex_match ( s.cbegin(), s.cend(), sm, e);
  std::cout << "range with " << sm.size() << " matches\n";

  // using explicit flags:
  std::regex_match ( cstr, cm, e, std::regex_constants::match_default );

  std::cout << "the matches were: ";
  for (unsigned i=0; i<cm.size(); ++i) {
    std::cout << "[" << cm[i] << "] ";
  }

  std::cout << std::endl;

  return 0;
}


Output:
string literal matched
string object matched
range matched
string literal with 3 matches
string object with 3 matches
range with 3 matches
the matches were: [subject] [sub] [ject]

See also