This documentation is archived and is not being maintained.

Regex.Match Method (String)

Updated: October 2008

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)

'Declaration
Public Function Match ( _
	input As String _
) As Match
'Usage
Dim instance As Regex 
Dim input As String 
Dim returnValue As Match 

returnValue = instance.Match(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 Nothing.

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 successful, 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 NextMatch method. You can also retrieve all matches in a single method call by calling the Regex.Matches(String) method.

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

Imports System.Text.RegularExpressions

Module Example
   Public Sub Main()
      Dim text As String = "One car red car blue car" 
      Dim pattern As String = "(\w+)\s+(car)" 

      ' Instantiate the regular expression object. 
      Dim r As Regex = new Regex(pattern, RegexOptions.IgnoreCase)

      ' Match the regular expression pattern against a text string. 
      Dim m As Match = r.Match(text)
      Dim matchcount as Integer = 0
      Do While m.Success
         matchCount += 1
         Console.WriteLine("Match" & (matchCount))
         Dim i As Integer 
         For i = 1 to 2
            Dim g as Group = m.Groups(i)
            Console.WriteLine("Group" & i & "='" & g.ToString() & "'")
            Dim cc As CaptureCollection = g.Captures
            Dim j As Integer  
            For j = 0 to cc.Count - 1
      	      Dim c As Capture = cc(j)
               Console.WriteLine("Capture" & j & "='" & c.ToString() _
                  & "', Position=" & c.Index)
            Next  
         Next 
         m = m.NextMatch()
      Loop 
   End Sub 
End Module 
' 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

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Date

History

Reason

October 2008

Added a Remarks section.

Customer feedback.

Show: