This documentation is archived and is not being maintained.

Match.Groups Property

Updated: February 2009

Gets a collection of groups matched by the regular expression.

Namespace:  System.Text.RegularExpressions
Assembly:  System (in System.dll)

public virtual GroupCollection Groups { get; }

Property Value

Type: System.Text.RegularExpressions.GroupCollection
The character groups matched by the pattern.

A regular expression pattern can include subexpressions, which are defined by enclosing a portion of the regular expression pattern in parentheses. Every such subexpression forms a group. For example, the regular expression pattern (\d{3})-(\d{3}-\d{4}), which matches North American telephone numbers, has two subexpressions. The first consists of the area code, which composes the first three digits of the telephone number. This group is captured by the first portion of the regular expression, (\d{3}).The second consists of the individual telephone number, which composes the last seven digits of the telephone number. This group is captured by the second portion of the regular expression, (\d{3}-\d{4}). These two groups can then be retrieved from the GroupCollection object that is returned by the Groups property, as the following example shows.

using System;
using System.Text.RegularExpressions;

public class Example
   public static void Main()
      string pattern = @"(\d{3})-(\d{3}-\d{4})";
      string input = "212-555-6666 906-932-1111 415-222-3333 425-888-9999";
      MatchCollection matches = Regex.Matches(input, pattern);

      foreach (Match match in matches)
         Console.WriteLine("Area Code:        {0}", match.Groups[1].Value);
         Console.WriteLine("Telephone number: {0}", match.Groups[2].Value);
// The example displays the following output: 
//       Area Code:        212 
//       Telephone number: 555-6666 
//       Area Code:        906 
//       Telephone number: 932-1111 
//       Area Code:        415 
//       Telephone number: 222-3333 
//       Area Code:        425 
//       Telephone number: 888-9999

The GroupCollection object returned by the Match.Groups property always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the Group.Success property of the single Group object in the collection is set to false and the Group object's Value property is set to String.Empty. If the regular expression engine can find a match, the first element of the GroupCollection object returned by the Groups property contains a string that matches the entire regular expression pattern.

The following example attempts to match a regular expression pattern against a sample string. The example uses the Groups property to store information retrieved by the match for display to the console.

using System;
using System.Text.RegularExpressions;

class Example 
   static void Main() 
      string text = "One car red car blue car";
      string pat = @"(\w+)\s+(car)";

      // Instantiate the regular expression object.
      Regex r = new Regex(pat, RegexOptions.IgnoreCase);

      // Match the regular expression pattern against a text string.
      Match m = r.Match(text);
      int matchCount = 0;
      while (m.Success) 
         Console.WriteLine("Match"+ (++matchCount));
         for (int i = 1; i <= 2; i++) 
            Group g = m.Groups[i];
            Console.WriteLine("Group"+i+"='" + g + "'");
            CaptureCollection cc = g.Captures;
            for (int j = 0; j < cc.Count; j++) 
               Capture c = cc[j];
               System.Console.WriteLine("Capture"+j+"='" + c + "', Position="+c.Index);
         m = m.NextMatch();
// This example displays the following output: 
//       Match1 
//       Group1='One' 
//       Capture0='One', Position=0 
//       Group2='car' 
//       Capture0='car', Position=4 
//       Match2 
//       Group1='red' 
//       Capture0='red', Position=8 
//       Group2='car' 
//       Capture0='car', Position=12 
//       Match3 
//       Group1='blue' 
//       Capture0='blue', Position=16 
//       Group2='car' 
//       Capture0='car', Position=21

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0




February 2009

Expanded the Remarks section.

Customer feedback.