Match Class
Represents the results from a single regular expression match.
Assembly: System (in System.dll)
System.Text.RegularExpressions::Capture
System.Text.RegularExpressions::Group
System.Text.RegularExpressions::Match
| Name | Description | |
|---|---|---|
 | Captures | Gets a collection of all the captures matched by the capturing group, in innermost-leftmost-first order (or innermost-rightmost-first order if the regular expression is modified with the RegexOptions::RightToLeft option). The collection may have zero or more items.(Inherited from Group.) |
 | Empty | Gets the empty group. All failed matches return this empty match. |
| Groups | Gets a collection of groups matched by the regular expression. |
| Index | The position in the original string where the first character of the captured substring is found.(Inherited from Capture.) |
| Length | Gets the length of the captured substring.(Inherited from Capture.) |
| Name | Returns the name of the capturing group representing by the current instance.(Inherited from Group.) |
| Success | Gets a value indicating whether the match is successful.(Inherited from Group.) |
| Value | Gets the captured substring from the input string.(Inherited from Capture.) |
| Name | Description | |
|---|---|---|
 | Equals(Object^) | Determines whether the specified object is equal to the current object.(Inherited from Object.) |
 | Finalize() | Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.) |
| GetHashCode() | Serves as the default hash function. (Inherited from Object.) |
| GetType() | |
| MemberwiseClone() | |
| NextMatch() | Returns a new Match object with the results for the next match, starting at the position at which the last match ended (at the character after the last matched character). |
| Result(String^) | Returns the expansion of the specified replacement pattern. |
| Synchronized(Match^) | Returns a Match instance equivalent to the one supplied that is suitable to share between multiple threads. |
| ToString() |
The Match object is immutable and has no public constructor. 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.
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 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. You can access the captured groups in a match in the following ways:
You can iterate the members of the GroupCollection object by using a foreach (C#) or For Each (Visual Basic) construct.
You can use the GroupCollection::Item[Int32] property to retrieve groups by the number of the capturing group. Note that you can determine which numbered groups are present in a regular expression by calling the instance Regex::GetGroupNumbers method.
You can use the GroupCollection::Item[String^] property to retrieve groups by the name of the capturing group. Note that you can determine which named groups are present in a regular expression by calling the instance Regex::GetGroupNames() method.
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.
Example 2
The following example calls the Match(String^, String^) and NextMatch methods to retrieve one match at a time.
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
Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.