Regular Expression Classes 

The following sections describe the .NET Framework regular expression classes.

Regex

The Regex class represents an immutable (read-only) regular expression. It also contains static methods that allow use of other regular expression classes without explicitly creating instances of the other classes.

The following code example creates an instance of the Regex class and defines a simple regular expression when the object is initialized. Note the use of an additional backslash as an escape character that designates the backslash in the \s matching character class as a literal character.

    ' Declare object variable of type Regex.
    Dim r As Regex 
    ' Create a Regex object and define its regular expression.
    r = New Regex("\s2000")
    // Declare object variable of type Regex.
    Regex r; 
    // Create a Regex object and define its regular expression.
    r = new Regex("\\s2000"); 

Match

The Match class represents the results of a regular expression matching operation. The following example uses the Match method of the Regex class to return an object of type Match in order to find the first match in the input string. The example uses the Match.Success property of the Match class to indicate whether a match was found.

    ' cCreate a new Regex object.
    Dim r As New Regex("abc") 
    ' Find a single match in the input string.
    Dim m As Match = r.Match("123abc456") 
    If m.Success Then
        ' Print out the character position where a match was found. 
        ' (Character position 3 in this case.)
        Console.WriteLine("Found match at position " & m.Index.ToString())
    End If
    // Create a new Regex object.
    Regex r = new Regex("abc"); 
    // Find a single match in the string.
    Match m = r.Match("123abc456"); 
    if (m.Success) 
    {
        // Print out the character position where a match was found. 
        // (Character position 3 in this case.)
        Console.WriteLine("Found match at position " + m.Index);
    }

MatchCollection

The MatchCollection class represents a sequence of successful non-overlapping matches. The collection is immutable (read-only) and has no public constructor. Instances of MatchCollection are returned by the Regex.Matches method.

The following example uses the Matches method of the Regex class to fill a MatchCollection with all the matches found in the input string. The example copies the collection to a string array that holds each match and an integer array that indicates the position of each match.

    Dim mc As MatchCollection
    Dim results(20) As String
    Dim matchposition(20) As Integer

    ' Create a new Regex object and define the regular expression.
    Dim r As New Regex("abc")
    ' Use the Matches method to find all matches in the input string.
    mc = r.Matches("123abc4abcd")
    ' Loop through the match collection to retrieve all 
    ' matches and positions.
    Dim i As Integer
    For i = 0 To mc.Count - 1
        ' Add the match string to the string array.
        results(i) = mc(i).Value
        ' Record the character position where the match was found.
        matchposition(i) = mc(i).Index
    Next i
    MatchCollection mc;
    String[] results = new String[20];
    int[] matchposition = new int[20];
    
    // Create a new Regex object and define the regular expression.
    Regex r = new Regex("abc"); 
    // Use the Matches method to find all matches in the input string.
    mc = r.Matches("123abc4abcd");
    // Loop through the match collection to retrieve all 
    // matches and positions.
    for (int i = 0; i < mc.Count; i++) 
    {
        // Add the match string to the string array.   
        results[i] = mc[i].Value;
        // Record the character position where the match was found.
        matchposition[i] = mc[i].Index;   
    }

GroupCollection

The GroupCollection class represents a collection of captured groups and returns the set of captured groups in a single match. The collection is immutable (read-only) and has no public constructor. Instances of GroupCollection are returned in the collection that the Match.Groups property returns.

The following console application example finds and prints the number of groups captured by a regular expression. For an example of how to extract the individual captures in each member of a group collection, see the Capture Collection example in the following section.

    Imports System
    Imports System.Text.RegularExpressions

    Public Class RegexTest
        Public Shared Sub RunTest()
            ' Define groups "abc", "ab", and "b".
            Dim r As New Regex("(a(b))c") 
            Dim m As Match = r.Match("abdabc")
            Console.WriteLine("Number of groups found = " _
            & m.Groups.Count.ToString())
        End Sub    
    
        Public Shared Sub Main()
            RunTest()
        End Sub
    End Class
    using System;
    using System.Text.RegularExpressions;

    public class RegexTest 
    {
        public static void RunTest() 
        {
            // Define groups "abc", "ab", and "b".
            Regex r = new Regex("(a(b))c"); 
            Match m = r.Match("abdabc");
            Console.WriteLine("Number of groups found = " + m.Groups.Count);
        }
        public static void Main() 
        {
            RunTest();
        }
    }

This example produces the following output.

    Number of groups found = 3
    Number of groups found = 3

CaptureCollection

The CaptureCollection class represents a sequence of captured substrings and returns the set of captures done by a single capturing group. A capturing group can capture more than one string in a single match because of quantifiers. The Captures property, an object of the CaptureCollection class, is provided as a member of the Match and Group classes to facilitate access to the set of captured substrings.

For instance, if you use the regular expression ((a(b))c)+ (where the + quantifier specifies one or more matches) to capture matches from the string "abcabcabc", the CaptureCollection for each matching Group of substrings will contain three members.

The following console application example uses the regular expression (Abc)+ to find one or more matches in the string "XYZAbcAbcAbcXYZAbcAb". The example illustrates the use of the Captures property to return multiple groups of captured substrings.

    Imports System
    Imports System.Text.RegularExpressions

    Public Class RegexTest
        Public Shared Sub RunTest()
            Dim counter As Integer
            Dim m As Match
            Dim cc As CaptureCollection
            Dim gc As GroupCollection
            ' Look for groupings of "Abc".
            Dim r As New Regex("(Abc)+") 
            ' Define the string to search.
            m = r.Match("XYZAbcAbcAbcXYZAbcAb")
            gc = m.Groups
            
            ' Print the number of groups.
            Console.WriteLine("Captured groups = " & gc.Count.ToString())
            
            ' Loop through each group.
            Dim i, ii As Integer
            For i = 0 To gc.Count - 1
                cc = gc(i).Captures
                counter = cc.Count
                
                ' Print number of captures in this group.
                Console.WriteLine("Captures count = " & counter.ToString())
                
                ' Loop through each capture in group.            
                For ii = 0 To counter - 1
                    ' Print capture and position.
                    Console.WriteLine(cc(ii).ToString() _
                        & "   Starts at character " & cc(ii).Index.ToString())
                Next ii
            Next i
        End Sub
    
        Public Shared Sub Main()
            RunTest()
         End Sub
    End Class
    using System;
    using System.Text.RegularExpressions;

    public class RegexTest 
        {
        public static void RunTest() 
        {
            int counter;
            Match m;
            CaptureCollection cc;
            GroupCollection gc;

            // Look for groupings of "Abc".
            Regex r = new Regex("(Abc)+"); 
            // Define the string to search.
            m = r.Match("XYZAbcAbcAbcXYZAbcAb"); 
            gc = m.Groups;

            // Print the number of groups.
            Console.WriteLine("Captured groups = " + gc.Count.ToString());

            // Loop through each group.
            for (int i=0; i < gc.Count; i++) 
            {
                cc = gc[i].Captures;
                counter = cc.Count;
                
                // Print number of captures in this group.
                Console.WriteLine("Captures count = " + counter.ToString());
                
                // Loop through each capture in group.
                for (int ii = 0; ii < counter; ii++) 
                {
                    // Print capture and position.
                    Console.WriteLine(cc[ii] + "   Starts at character " + 
                        cc[ii].Index);
                }
            }
        }

        public static void Main() {
            RunTest();
        }
    }

This example returns the following output.

    Captured groups = 2
    Captures count = 1
    AbcAbcAbc   Starts at character 3
    Captures count = 3
    Abc   Starts at character 3
    Abc   Starts at character 6
    Abc   Starts at character 9
    Captured groups = 2
    Captures count = 1
    AbcAbcAbc   Starts at character 3
    Captures count = 3
    Abc   Starts at character 3
    Abc   Starts at character 6
    Abc   Starts at character 9

Group

The Group class represents the results from a single capturing group. Because Group can capture zero, one, or more strings in a single match (using quantifiers), it contains a collection of Capture objects. Because Group inherits from Capture, the last substring captured can be accessed directly (the Group instance itself is equivalent to the last item of the collection returned by the Captures property).

Instances of Group are returned by indexing the GroupCollection object returned by the Groups property. The indexer can be a group number or the name of a capture group if the "(?<groupname>)" grouping construct is used. For example, in C# code you can use Match.Groups[groupnum] or Match.Groups["groupname"], or in Visual Basic code you can use Match.Groups(groupnum) or Match.Groups("groupname").

The following code example uses nested grouping constructs to capture substrings into groups.

    Dim matchposition(20) As Integer
    Dim results(20) As String
    ' Define substrings abc, ab, b.
    Dim r As New Regex("(a(b))c") 
    Dim m As Match = r.Match("abdabc")
    Dim i As Integer = 0
    While Not (m.Groups(i).Value = "")    
       ' Copy groups to string array.
       results(i) = m.Groups(i).Value     
       ' Record character position. 
       matchposition(i) = m.Groups(i).Index 
        i = i + 1
    End While
    int[] matchposition = new int[20];
    String[] results = new String[20];
    // Define substrings abc, ab, b.
    Regex r = new Regex("(a(b))c"); 
    Match m = r.Match("abdabc");
    for (int i = 0; m.Groups[i].Value != ""; i++) 
    {
        // Copy groups to string array.
        results[i]=m.Groups[i].Value; 
        // Record character position.
        matchposition[i] = m.Groups[i].Index; 
    }

This example returns the following output.

    results(0) = "abc"   matchposition(0) = 3
    results(1) = "ab"    matchposition(1) = 3
    results(2) = "b"     matchposition(2) = 4
    results[0] = "abc"   matchposition[0] = 3
    results[1] = "ab"    matchposition[1] = 3
    results[2] = "b"     matchposition[2] = 4

The following code example uses named grouping constructs to capture substrings from a string containing data in a "DATANAME:VALUE" format that the regular expression splits at the colon (:).

    Dim r As New Regex("^(?<name>\w+):(?<value>\w+)")
    Dim m As Match = r.Match("Section1:119900")
    Regex r = new Regex("^(?<name>\\w+):(?<value>\\w+)");
    Match m = r.Match("Section1:119900");

This regular expression returns the following output.

    m.Groups("name").Value = "Section1"
    m.Groups("value").Value = "119900"
    m.Groups["name"].Value = "Section1"
    m.Groups["value"].Value = "119900"

Capture

The Capture class contains the results from a single subexpression capture.

The following example loops through a Group collection, extracts the Capture collection from each member of Group, and assigns the variables posn and length to the character position in the original string where each string was found and the length of each string, respectively.

    Dim r As Regex
    Dim m As Match
    Dim cc As CaptureCollection
    Dim posn, length As Integer

    r = New Regex("(abc)+")
    m = r.Match("bcabcabc")
    Dim i, j As Integer
    i = 0
    While m.Groups(i).Value <> ""
        ' Grab the Collection for Group(i).
        cc = m.Groups(i).Captures
        For j = 0 To cc.Count - 1
            ' Position of Capture object.
            posn = cc(j).Index
            ' Length of Capture object.
            length = cc(j).Length
        Next j
        i += 1
    End While
    Regex r;
    Match m;
    CaptureCollection cc;
    int posn, length;

    r = new Regex("(abc)+");
    m = r.Match("bcabcabc");
    for (int i=0; m.Groups[i].Value != ""; i++) 
    {
        // Capture the Collection for Group(i).
        cc = m.Groups[i].Captures; 
        for (int j = 0; j < cc.Count; j++) 
        {
            // Position of Capture object.
            posn = cc[j].Index; 
            // Length of Capture object.
            length = cc[j].Length; 
        }
    }

See Also

Reference

System.Text.RegularExpressions

Other Resources

.NET Framework Regular Expressions