Match Class
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Represents the results from a single regular expression match.
System.Text.RegularExpressions::Capture
System.Text.RegularExpressions::Group
System.Text.RegularExpressions::Match
Assembly: System (in System.dll)
The Match type exposes the following members.
| 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 was found. (Inherited from Capture.) |
| Length | The length of the captured substring. (Inherited from Capture.) |
| 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 the Object is reclaimed by garbage collection. (Inherited from Object.) |
| GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
| GetType | Gets the Type of the current instance. (Inherited from Object.) |
| MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
| 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 beyond the last matched character). |
| Result | Returns the expansion of the specified replacement pattern. |
| ToString | Gets the captured substring from the input string. (Inherited from Capture.) |
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 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.
Example 2
The following example calls the Match(String, String) and NextMatch methods to retrieve one match at a time.