Regular Expression Result Match Class Properties Methods Remarks Applies to See also MatchCollection Class Properties Methods Extension Methods Remarks Applies to Examples Source/Reference
Regular Expression Result
The results of the regular expression engine of .NET framework can be accessed by Capture Class, CaptureCollection Class, Group Class, GroupCollection Class, Match Class, MatchCollection Class.
Both Match Class and MatchCollection Class are used to represent the object return by the Match Method and Matches Method of Regex Class respectively.
Match Class
Represents the results from a single regular expression match.
[System.Serializable]
public class Match : System.Text.RegularExpressions.Group
Properties
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 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 represented 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)
Methods
Equals(Object)
Determines whether the specified object is equal to the current object.
(Inherited from Object)
GetHashCode()
Serves as the default hash function.
(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 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()
Retrieves the captured substring from the input string by calling the Value property.
(Inherited from Capture)
Remarks
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.
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.
[System.Serializable]
public class MatchCollection : System.Collections.ICollection
Properties
Count
Gets the number of matches.
IsReadOnly
Gets a value that indicates whether the collection is read only.
IsSynchronized
Gets a value indicating whether access to the collection is synchronized (thread-safe).
Item[Int32]
Gets an individual member of the collection.
SyncRoot
Gets an object that can be used to synchronize access to the collection.
Methods
CopyTo(Array, Int32)
Copies all the elements of the collection to the given array starting at the given index.
Equals(Object)
Determines whether the specified object is equal to the current object.
(Inherited from Object)
GetEnumerator()
Provides an enumerator that iterates through the collection.
GetHashCode()
Serves as the default hash function.
(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)
ToString()
Returns a string that represents the current object.
(Inherited from Object)
Extension Methods
Cast<TResult>(IEnumerable)
Casts the elements of an IEnumerable to the specified type.
OfType<TResult>(IEnumerable)
Filters the elements of an IEnumerable based on a specified type.
AsParallel(IEnumerable)
Enables parallelization of a query.
AsQueryable(IEnumerable)
Converts an IEnumerable to an IQueryable.
Remarks
The collection is immutable (read-only) and has no public constructor. The Regex.Matches method returns a MatchCollection object.
The collection contains zero or more System.Text.RegularExpressions.Match objects. If the match is successful, the collection is populated with one System.Text.RegularExpressions.Match object for each match found in the input string. If the match is unsuccessful, the collection contains no System.Text.RegularExpressions.Match objects, and its
Count property equals zero.
When applying a regular expression pattern to a particular input string, the regular expression engine uses either of two techniques to build the MatchCollection object:
Direct evaluation. The MatchCollection object is populated all at once, with all matches resulting from a particular call to the Regex.Matches method. This technique is used when the collection's Count property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit.
Lazy evaluation. The MatchCollection object is populated as needed on a match-by-match basis. It is equivalent to the regular expression engine calling the Regex.Match method repeatedly and adding each match to the collection. This technique is used when the collection is accessed through its GetEnumerator method, or when it is accessed using the foreach statement (in C#) or the For Each...Next statement (in Visual Basic).
To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as foreach in C# and For Each…Next in Visual Basic) instead of retrieving the enumerator that is returned by the GetEnumerator method.