Export (0) Print
Expand All

Regex::Match Method (String)

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

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

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.

ExceptionCondition
ArgumentNullException

input is nullptr.

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.

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

#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.

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0, 1.1

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

XNA Framework

Supported in: 3.0, 2.0, 1.0

Portable Class Library

Supported in: Portable Class Library

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8
Show:
© 2015 Microsoft