Match Class
Updated: June 2011
Represents the results from a single regular expression match.
Assembly: System (in System.dll)
An instance of the Match class is returned by the Regex.Match method and represents the first pattern match in a string. Subsequent matches are represented by Match objects returned by the Match.NextMatch method. In addition, a MatchCollection object that consists of zero, one, or more Match objects is returned by the Regex.Matches method.
If the Regex.Matches method fails to match a regular expression pattern in an input string, it returns an empty MatchCollection object. You can then use a foreach construct in C# or a For Each construct in Visual Basic to iterate the collection.
If the Regex.Match method fails to match the regular expression pattern, it returns a Match object that is equal to Match.Empty. You can use the Success property to determine whether the match was successful. The following example provides an illustration.
' Search for a pattern that is not found in the input string. Dim pattern As String = "dog" Dim input As String = "The cat saw the other cats playing in the back yard." Dim match As Match = Regex.Match(input, pattern) If match.Success Then ' Report position as a one-based integer. Console.WriteLine("'{0}' was found at position {1} in '{2}'.", _ match.Value, match.Index + 1, input) Else Console.WriteLine("The pattern '{0}' was not found in '{1}'.", _ pattern, input) End If
If a pattern match is successful, the Value property contains the matched substring, the Index property indicates the zero-based starting position of the matched substring in the input string, and the Length property indicates the length of matched substring in the input string.
Because a single match can involve multiple capturing groups, Match has a Groups property that returns the GroupCollection. The GroupCollection has accessors that return each group. The Match instance itself is equivalent to the first object in the collection, at Match.Groups[0] (Match.Groups(0) in Visual Basic), which represents the entire match.
The following examples use the regular expression Console\.Write(Line)?. The regular expression is interpreted as follows:
Console\.Write | Match the string "Console.Write". Note that the "." character is escaped so that it is interpreted as a literal period rather than as a wildcard that matches any character. |
(Line)? | Match zero or one occurrence of the string "Line". |
Example 1
The following example calls the Regex.Matches(String, String) method to retrieve all pattern matches in an input string. It then iterates the Match objects in the returned MatchCollection object to display information about each match.
Imports System.Text.RegularExpressions Module Example Public Sub Main() Dim input As String = "Dim values() As Integer = { 1, 2, 3 }" & vbCrLf & _ "For ctr As Integer = values.GetLowerBound(1) To values.GetUpperBound(1)" & vbCrLf & _ " Console.Write(values(ctr))" & vbCrLf & _ " If ctr < values.GetUpperBound(1) Then Console.Write("", "")" & vbCrLf & _ "Next" & vbCrLf & _ "Console.WriteLine()" Dim pattern As String = "Console\.Write(Line)?" Dim matches As MatchCollection = Regex.Matches(input, pattern) For Each match As Match In matches Console.WriteLine("'{0}' found in the source code at position {1}.", _ match.Value, match.Index) Next End Sub End Module ' The example displays the following output: ' 'Console.Write' found in the source code at position 115. ' 'Console.Write' found in the source code at position 184. ' 'Console.WriteLine' found in the source code at position 211.
Example 2
The following example calls the Match(String, String) and NextMatch methods to retrieve one match at a time.
Imports System.Text.RegularExpressions Module Example Public Sub Main() Dim input As String = "Dim values() As Integer = { 1, 2, 3 }" & vbCrLf & _ "For ctr As Integer = values.GetLowerBound(1) To values.GetUpperBound(1)" & vbCrLf & _ " Console.Write(values(ctr))" & vbCrLf & _ " If ctr < values.GetUpperBound(1) Then Console.Write("", "")" & vbCrLf & _ "Next" & vbCrLf & _ "Console.WriteLine()" Dim pattern As String = "Console\.Write(Line)?" Dim match As Match = Regex.Match(input, pattern) Do While match.Success Console.WriteLine("'{0}' found in the source code at position {1}.", _ match.Value, match.Index) match = match.NextMatch() Loop End Sub End Module ' The example displays the following output: ' 'Console.Write' found in the source code at position 115. ' 'Console.Write' found in the source code at position 184. ' 'Console.WriteLine' found in the source code at position 211.
System.Text.RegularExpressions.Capture
System.Text.RegularExpressions.Group
System.Text.RegularExpressions.Match
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.