Regex::Match Method (String^)

.NET Framework (current version)

Searches the specified input string for the first occurrence of the regular expression specified in the Regex constructor.

Namespace: System.Text.RegularExpressions
Assembly: System (in System.dll)

Syntax

C++

public:
Match^ Match(
	String^ input
)

Parameters

input: Type: System::String^
The string to search for a match.

Return Value

Type: System.Text.RegularExpressions::Match^

An object that contains information about the match.

Exceptions

Exception	Condition
ArgumentNullException	input is null.
RegexMatchTimeoutException	A time-out occurred. For more information about time-outs, see the Remarks section.

The Match(String^) method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see Regular Expression Language - Quick Reference.

You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned Match object's Success property. If a match is found, the returned Match object's Value property contains the substring from input that matches the regular expression pattern. If no match is found, its value is String::Empty.

This method returns the first substring in input that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned Match object's Match::NextMatch method. You can also retrieve all matches in a single method call by calling the Regex::Matches(String^) method.

The RegexMatchTimeoutException exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the Regex::Regex(String^, RegexOptions, TimeSpan) constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the Regex object is created. If no time-out is defined in the Regex constructor call or in the application domain's properties, or if the time-out value is Regex::InfiniteMatchTimeout, no exception is thrown.

Examples

The following example finds regular expression pattern matches in a string, then lists the matched groups, captures, and capture positions.

C++

#using <System.dll>

using namespace System;
using namespace System::Text::RegularExpressions;
void main()
{

   String^ text = "One car red car blue car";
   String^ pat = "(\\w+)\\s+(car)";

   // Compile the regular expression.
   Regex^ r = gcnew Regex( pat,RegexOptions::IgnoreCase );

   // Match the regular expression pattern against a text string.
   Match^ m = r->Match(text);
   int matchCount = 0;
   while ( m->Success )
   {
      Console::WriteLine( "Match{0}", ++matchCount );
      for ( int i = 1; i <= 2; i++ )
      {
         Group^ g = m->Groups[ i ];
         Console::WriteLine( "Group{0}='{1}'", i, g );
         CaptureCollection^ cc = g->Captures;
         for ( int j = 0; j < cc->Count; j++ )
         {
            Capture^ c = cc[ j ];
            System::Console::WriteLine( "Capture{0}='{1}', Position={2}", j, c, c->Index );
         }
      }
      m = m->NextMatch();
   }
}  
// This example displays the following output:
//       Match1
//       Group1='One'
//       Capture0='One', Position=0
//       Group2='car'
//       Capture0='car', Position=4
//       Match2
//       Group1='red'
//       Capture0='red', Position=8
//       Group2='car'
//       Capture0='car', Position=12
//       Match3
//       Group1='blue'
//       Capture0='blue', Position=16
//       Group2='car'
//       Capture0='car', Position=21

The regular expression pattern (\w+)\s+(car) matches occurrences of the word "car" along with the word that precedes it. It is interpreted as shown in the following table.

Pattern	Description
(\w+)	Match one or more word characters. This is the first capturing group.
\s+	Match one or more white-space characters.
(car)	Match the literal string "car". This is the second capturing group.

Version Information

Universal Windows Platform
Available since 8
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1