Regular Expression Object Model

This topic describes the object model used in working with .NET regular expressions. It contains the following sections:

The Regular Expression Engine

The regular expression engine in .NET is represented by the Regex class. The regular expression engine is responsible for parsing and compiling a regular expression, and for performing operations that match the regular expression pattern with an input string. The engine is the central component in the .NET regular expression object model.

You can use the regular expression engine in either of two ways:

By calling the static methods of the Regex class. The method parameters include the input string and the regular expression pattern. The regular expression engine caches regular expressions that are used in static method calls, so repeated calls to static regular expression methods that use the same regular expression offer relatively good performance.
By instantiating a Regex object, by passing a regular expression to the class constructor. In this case, the Regex object is immutable (read-only) and represents a regular expression engine that is tightly coupled with a single regular expression. Because regular expressions used by Regex instances are not cached, you should not instantiate a Regex object multiple times with the same regular expression.

You can call the methods of the Regex class to perform the following operations:

Determine whether a string matches a regular expression pattern.
Extract a single match or the first match.
Extract all matches.
Replace a matched substring.
Split a single string into an array of strings.

These operations are described in the following sections.

Matching a Regular Expression Pattern

The Regex.IsMatch method returns true if the string matches the pattern, or false if it does not. The IsMatch method is often used to validate string input.

Extracting a Single Match or the First Match

The Regex.Match method returns a Match object that contains information about the first substring that matches a regular expression pattern. If the Match.Success property returns true, indicating that a match was found, you can retrieve information about subsequent matches by calling the Match.NextMatch method. These method calls can continue until the Match.Success property returns false. For example, the following code uses the Regex.Match(String, String) method to find the first occurrence of a duplicated word in a string. It then calls the Match.NextMatch method to find any additional occurrences.

Extracting All Matches

The Regex.Matches method returns a MatchCollection object that contains information about all matches that the regular expression engine found in the input string.

Replacing a Matched Substring

The Regex.Replace method replaces each substring that matches the regular expression pattern with a specified string or regular expression pattern, and returns the entire input string with replacements.

Splitting a Single String into an Array of Strings

The Regex.Split method splits the input string at the positions defined by a regular expression match.

The MatchCollection and Match Objects

Regex methods return two objects that are part of the regular expression object model: the MatchCollection object, and the Match object.

The Match Collection

The Regex.Matches method returns a MatchCollection object that contains Match objects that represent all the matches that the regular expression engine found, in the order in which they occur in the input string. If there are no matches, the method returns a MatchCollection object with no members. The MatchCollection.Item[Int32] property lets you access individual members of the collection by index, from zero to one less than the value of the MatchCollection.Count property. Item[Int32] is the collection's indexer (in C#) and default property (in Visual Basic).

By default, the call to the Regex.Matches method uses lazy evaluation to populate the MatchCollection object. Access to properties that require a fully populated collection, such as the MatchCollection.Count and MatchCollection.Item[Int32] properties, may involve a performance penalty. As a result, we recommend that you access the collection by using the IEnumerator object that is returned by the MatchCollection.GetEnumerator method. Individual languages provide constructs, such as For Each in Visual Basic and foreach in C#, that wrap the collection's IEnumerator interface.

The Match

The Match class represents the result of a single regular expression match. You can access Match objects in two ways:

By retrieving them from the MatchCollection object that is returned by the Regex.Matches method. To retrieve individual Match objects, iterate the collection by using a foreach (in C#) or For Each...Next (in Visual Basic) construct, or use the MatchCollection.Item[Int32] property to retrieve a specific Match object either by index or by name. You can also retrieve individual Match objects from the collection by iterating the collection by index, from zero to one less that the number of objects in the collection. However, this method does not take advantage of lazy evaluation, because it accesses the MatchCollection.Count property.
By calling the Regex.Match method, which returns a Match object that represents the first match in a string or a portion of a string. You can determine whether the match has been found by retrieving the value of the Match.Success property. To retrieve Match objects that represent subsequent matches, call the Match.NextMatch method repeatedly, until the Success property of the returned Match object is false.

Two properties of the Match class return collection objects:

The Match.Groups property returns a GroupCollection object that contains information about the substrings that match capturing groups in the regular expression pattern.
The Match.Captures property returns a CaptureCollection object that is of limited use. The collection is not populated for a Match object whose Success property is false. Otherwise, it contains a single Capture object that has the same information as the Match object.

Two additional properties of the Match class provide information about the match. The Match.Value property returns the substring in the input string that matches the regular expression pattern. The Match.Index property returns the zero-based starting position of the matched string in the input string.

The Match class also has two pattern-matching methods:

The Match.NextMatch method finds the match after the match represented by the current Match object, and returns a Match object that represents that match.
The Match.Result method performs a specified replacement operation on the matched string and returns the result.

The replacement pattern $$ $& indicates that the matched substring should be replaced by a dollar sign ($) symbol (the $$ pattern), a space, and the value of the match (the $& pattern).

The Group Collection

The Match.Groups property returns a GroupCollection object that contains Group objects that represent captured groups in a single match. The first Group object in the collection (at index 0) represents the entire match. Each object that follows represents the results of a single capturing group.

You can retrieve individual Group objects in the collection by using the GroupCollection.Item[String] property. You can retrieve unnamed groups by their ordinal position in the collection, and retrieve named groups either by name or by ordinal position. Unnamed captures appear first in the collection, and are indexed from left to right in the order in which they appear in the regular expression pattern. Named captures are indexed after unnamed captures, from left to right in the order in which they appear in the regular expression pattern. To determine what numbered groups are available in the collection returned for a particular regular expression matching method, you can call the instance Regex.GetGroupNumbers method. To determine what named groups are available in the collection, you can call the instance Regex.GetGroupNames method. Both methods are particularly useful in general-purpose routines that analyze the matches found by any regular expression.

The GroupCollection.Item[String] property is the indexer of the collection in C# and the collection object's default property in Visual Basic. This means that individual Group objects can be accessed by index (or by name, in the case of named groups)

The Captured Group

The Group class represents the result from a single capturing group. Group objects that represent the capturing groups defined in a regular expression are returned by the Item[String] property of the GroupCollection object returned by the Match.Groups property. The Item[String] property is the indexer (in C#) and the default property (in Visual Basic) of the Group class. You can also retrieve individual members by iterating the collection using the foreach or For Each construct. For an example, see the previous section.

The properties of the Group class provide information about the captured group: The Group.Value property contains the captured substring, the Group.Index property indicates the starting position of the captured group in the input text, the Group.Length property contains the length of the captured text, and the Group.Success property indicates whether a substring matched the pattern defined by the capturing group.

Applying quantifiers to a group (for more information, see Quantifiers) modifies the relationship of one capture per capturing group in two ways:

If the * or *? quantifier (which specifies zero or more matches) is applied to a group, a capturing group may not have a match in the input string. When there is no captured text, the properties of the Group object are set as shown in the following table.

Group property	Value
Success	false
Value	String.Empty
Length	0

Quantifiers can match multiple occurrences of a pattern that is defined by a capturing group. In this case, the Value and Length properties of a Group object contain information only about the last captured substring. For example, the following regular expression matches a single sentence that ends in a period. It uses two grouping constructs: The first captures individual words along with a white-space character; the second captures individual words. As the output from the example shows, although the regular expression succeeds in capturing an entire sentence, the second capturing group captures only the last word.

The Capture Collection

The Group object contains information only about the last capture. However, the entire set of captures made by a capturing group is still available from the CaptureCollection object that is returned by the Group.Captures property. Each member of the collection is a Capture object that represents a capture made by that capturing group, in the order in which they were captured (and, therefore, in the order in which the captured strings were matched from left to right in the input string). You can retrieve individual Capture objects from the collection in either of two ways:

By iterating through the collection using a construct such as foreach (in C#) or For Each (in Visual Basic).
By using the CaptureCollection.Item[Int32] property to retrieve a specific object by index. The Item[Int32] property is the CaptureCollection object's default property (in Visual Basic) or indexer (in C#).

If a quantifier is not applied to a capturing group, the CaptureCollection object contains a single Capture object that is of little interest, because it provides information about the same match as its Group object. If a quantifier is applied to a capturing group, the CaptureCollection object contains all captures made by the capturing group, and the last member of the collection represents the same capture as the Group object.

The Individual Capture

The Capture class contains the results from a single subexpression capture. The Capture.Value property contains the matched text, and the Capture.Index property indicates the zero-based position in the input string at which the matched substring begins.

Scanning of Valid Email Format

Examples of Scanning of Valid Email Format.

ASP.NET Code Input:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
       <title>Sample Page</title>
       <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
       <script runat="server">
           Sub Page_Load()
               Dim xstring As String = "dahhhvid.johgnes@prghjjosehware.com"
               Dim xmatchstr As String = ""
               lbl01.Text = xmatchstr
           End Sub
           Function showresult(xstring,xpattern)
               Dim xmatch As Match
               Dim xcaptures As CaptureCollection
               Dim ycaptures As CaptureCollection
               Dim xgroups As GroupCollection
               Dim xmatchstr As String = ""
               Dim xint As Integer
               Dim yint As Integer
               Dim zint As Integer
               xmatchstr = xmatchstr & "<br />Result of Regex.Match(string,""" & Replace(xpattern,"<","&lt;") & """): """
               xmatch = Regex.Match(xstring,xpattern)
               xmatchstr = xmatchstr & xmatch.value & """<br />"
               xcaptures = xmatch.Captures
               xmatchstr = xmatchstr & "->Result of CaptureCollection.Count: """
               xmatchstr = xmatchstr & xcaptures.Count & """<br />"
               For xint = 0 to xcaptures.Count - 1
                   xmatchstr = xmatchstr & "->->Result of CaptureCollection("& xint & ").Value, Index, Length: """
                   xmatchstr = xmatchstr & xcaptures(xint).Value & ", " & xcaptures(xint).Index & ", " & xcaptures(xint).Length & """<br />"
                   xgroups = xmatch.Groups
                   xmatchstr = xmatchstr & "->Result of GroupCollection.Count: """
                   xmatchstr = xmatchstr & xgroups.Count & """<br />"
                   For yint = 0 to xgroups.Count - 1
                       xmatchstr = xmatchstr & "->->Result of GroupCollection("& yint & ").Value, Index, Length: """
                       xmatchstr = xmatchstr & xgroups(yint).Value & ", " & xgroups(yint).Index & ", " & xgroups(yint).Length & """<br />"
                       ycaptures = xgroups(yint).Captures
                       xmatchstr = xmatchstr & "->->->Result of CaptureCollection.Count: """
                       xmatchstr = xmatchstr & ycaptures.Count & """<br />"
                       For zint = 0 to ycaptures.Count - 1
                           xmatchstr = xmatchstr & "->->->->Result of CaptureCollection("& zint & ").Value, Index, Length: """
                           xmatchstr = xmatchstr & ycaptures(zint).Value & ", " & ycaptures(zint).Index & ", " & ycaptures(zint).Length & """<br />"
                       Next
                   Next
               Next
               Return xmatchstr
           End Function
       </script>
    </head>
    <body>
       <% Response.Write ("<h1>This is a Sample Page of Scanning of of Valid Email Format</h1>") %>
       <p>
           <%-- Set on Page_Load --%>
           <asp:Label id="lbl01" runat="server" />
       </p>
    </body>
</html>

HTML Web Page Embedded Output: