Article
11/18/2011

Regex Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Represents an immutable regular expression.

Inheritance Hierarchy

System.Object
System.Text.RegularExpressions.Regex

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

Syntax

'Declaration
Public Class Regex

public class Regex

The Regex type exposes the following members.

Constructors

	Name	Description
	Regex()	Initializes a new instance of the Regex class.
	Regex(String)	Initializes and compiles a new instance of the Regex class for the specified regular expression.
	Regex(String, RegexOptions)	Initializes and compiles a new instance of the Regex class for the specified regular expression, with options that modify the pattern.

Top

Properties

	Name	Description
	CacheSize	Gets or sets the maximum number of entries in the current static cache of compiled regular expressions.
	Options	Returns the options passed into the Regex constructor.
	RightToLeft	Gets a value indicating whether the regular expression searches from right to left.

Top

Methods

	Name	Description
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Escape	Escapes a minimal set of characters (\, *, +, ?, \|, {, [, (,), ^, $,., #, and white space) by replacing them with their escape codes. This instructs the regular expression engine to interpret these characters literally rather than as metacharacters.
	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.)
	GetGroupNames	Returns an array of capturing group names for the regular expression.
	GetGroupNumbers	Returns an array of capturing group numbers that correspond to group names in an array.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	GroupNameFromNumber	Gets the group name that corresponds to the specified group number.
	GroupNumberFromName	Returns the group number that corresponds to the specified group name.
	InitializeReferences	Infrastructure. Used internally by the regular expression engine.
	IsMatch(String)	Indicates whether the regular expression specified in the Regex constructor finds a match in the input string.
	IsMatch(String, Int32)	Indicates whether the regular expression specified in the Regex constructor finds a match in the input string beginning at the specified starting position in the string.
	IsMatch(String, String)	Indicates whether the regular expression finds a match in the input string using the regular expression specified in the pattern parameter.
	IsMatch(String, String, RegexOptions)	Indicates whether the regular expression finds a match in the input string, using the regular expression specified in the pattern parameter and the matching options supplied in the options parameter.
	Match(String)	Searches the specified input string for the first occurrence of the regular expression specified in the Regex constructor.
	Match(String, Int32)	Searches the input string for the first occurrence of a regular expression with a specified input string starting position.
	Match(String, String)	Searches the specified input string for the first occurrence of the regular expression supplied in the pattern parameter.
	Match(String, Int32, Int32)	Searches the input string for the first occurrence of a regular expression with a specified input string starting position and input string length.
	Match(String, String, RegexOptions)	Searches the input string for the first occurrence of the regular expression supplied in a pattern parameter with matching options supplied in an options parameter.
	Matches(String)	Searches the specified input string for all occurrences of a regular expression.
	Matches(String, Int32)	Searches the specified input string for all occurrences of a regular expression, beginning at the specified starting position in the string.
	Matches(String, String)	Searches the specified input string for all occurrences of the regular expression specified in the pattern parameter.
	Matches(String, String, RegexOptions)	Searches the specified input string for all occurrences of the regular expression supplied in a pattern parameter with matching options supplied in an options parameter.
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	Replace(String, String)	Within a specified input string, replaces all strings that match a regular expression pattern with a specified replacement string.
	Replace(String, MatchEvaluator)	Within a specified input string, replaces all strings that match a specified regular expression with a string returned by a MatchEvaluator delegate.
	Replace(String, String, Int32)	Within a specified input string, replaces a specified maximum number of strings that match a regular expression pattern with a specified replacement string.
	Replace(String, String, String)	Within a specified input string, replaces all strings that match a specified regular expression with a specified replacement string.
	Replace(String, String, MatchEvaluator)	Within a specified input string, replaces all strings that match a specified regular expression with a string returned by a MatchEvaluator delegate.
	Replace(String, MatchEvaluator, Int32)	Within a specified input string, replaces a specified maximum number of strings that match a regular expression pattern with a string returned by a MatchEvaluator delegate.
	Replace(String, String, Int32, Int32)	Within a specified input substring, replaces a specified maximum number of strings that match a regular expression pattern with a specified replacement string.
	Replace(String, String, String, RegexOptions)	Within a specified input string, replaces all strings that match a specified regular expression with a specified replacement string. Specified options modify the matching operation.
	Replace(String, String, MatchEvaluator, RegexOptions)	Within a specified input string, replaces all strings that match a specified regular expression with a string returned by a MatchEvaluator delegate. Specified options modify the matching operation.
	Replace(String, MatchEvaluator, Int32, Int32)	Within a specified input substring, replaces a specified maximum number of strings that match a regular expression pattern with a string returned by a MatchEvaluator delegate.
	Split(String)	Splits the specified input string at the positions defined by a regular expression pattern specified in the Regex constructor.
	Split(String, Int32)	Splits the specified input string a specified maximum number of times at the positions defined by a regular expression specified in the Regex constructor.
	Split(String, String)	Splits the input string at the positions defined by a regular expression pattern.
	Split(String, Int32, Int32)	Splits the specified input string a specified maximum number of times at the positions defined by a regular expression specified in the Regex constructor. The search for the regular expression pattern starts at a specified character position in the input string.
	Split(String, String, RegexOptions)	Splits the input string at the positions defined by a specified regular expression pattern. Specified options modify the matching operation.
	ToString	Returns the regular expression pattern that was passed into the Regex constructor. (Overrides Object.ToString().)
	Unescape	Unescapes any escaped characters in the input string.
	UseOptionR	Infrastructure. Used internally by the regular expression engine.

Top

Fields

	Name	Description
	capsize	Infrastructure. Used internally by the regular expression engine.
	capslist	Infrastructure. Used internally by the regular expression engine.
	pattern	Infrastructure. Used internally by the regular expression engine.
	roptions	Infrastructure. Used internally by the regular expression engine.

Top

Remarks

The Regex class represents the .NET Framework's regular expression engine. It can be used to quickly parse large amounts of text to find specific character patterns; to validate text, to extract, edit, replace, or delete text substrings; or to add the extracted strings to a collection to generate a report.

To use regular expressions, you define the pattern that you want to identify in a text stream by using the syntax documented in Regular Expression Language Elements in the .NET Framework documentation. Next, you can optionally instantiate a Regex object. Finally, you perform some operation, such as replacing text that matches the regular expression pattern, or identifying a pattern match.

Regex vs. String Methods

The System.String class includes several search and comparison methods that you can use to perform pattern matching with text. For example, the String.Contains, String.EndsWith, and String.StartsWith methods determine whether a string instance contains a specified substring; and the String.IndexOf, String.IndexOfAny, String.LastIndexOf, and String.LastIndexOfAny methods return the starting position of a specified substring in a string. Use the methods of the System.String class when you are searching for a specific string. Use the Regex class when you are searching for a specific pattern in a string. For more information and examples, see Regular Expression Language - Quick Reference.

Static vs. Instance Methods

After you define a regular expression pattern, you can provide it to the regular expression engine in either of two ways.

By instantiating a Regex object that represents the regular expression. To do this, you pass the regular expression pattern to a Regex constructor. A Regex object is immutable; when you instantiate a Regex object with a regular expression, that object's regular expression cannot be changed.
By supplying both the regular expression and the text to search to a static (Shared in Visual Basic) Regex method. This enables you to use a regular expression without explicitly creating a Regex object.

All Regex pattern identification methods include both static and instance overloads.

The regular expression engine must compile a particular pattern before it can be used. Because Regex objects are immutable, this is a one-time procedure that occurs when a Regex class constructor is called, or when a static method is called. To eliminate the need to repeatedly compile a single regular expression, the regular expression engine caches the compiled regular expressions used in static method calls. As a result, regular expression pattern-matching methods offer comparable performance for static and instance methods.

However, the system of caching implemented by the regular expression engine can adversely affect performance in the following two cases:

When you use static method calls with a large number of regular expressions. By default, the regular expression engine caches the 15 most recently used static regular expressions. If your application uses more than 15 static regular expressions, some regular expressions must be recompiled. To prevent this recompilation, you can increase the Regex.CacheSize property to an appropriate value.

When your application instantiates new Regex objects with regular expressions that have previously been compiled. For example, the following code defines a regular expression to locate duplicated words in individual lines of a text stream. Although the example uses a single regular expression, it instantiates a new Regex object to process each line of text. This results in the recompilation of the regular expression with each iteration of the loop.

Dim inputs() As String = { "This this is a typo.", _
                           "They said that that man would come." }
Dim pattern As String = "\b(\w+)\s\1\b"

For Each input As String In inputs
   Dim rgx As New Regex(pattern, RegexOptions.IgnoreCase)
   Dim matches As MatchCollection = rgx.Matches(input)
   If matches.Count > 0 Then
      outputBlock.Text += String.Format("{0} ({1} matches):", input, matches.Count) & vbCrLf
      For Each match As Match In matches
         outputBlock.Text += "   " + match.Value & vbCrLf
      Next
   End If
Next

string[] inputs = { "This this is a typo.", 
                    "They said that that man would come." };
string pattern = @"\b(\w+)\s\1\b";
foreach (string input in inputs)
{
   Regex rgx = new Regex(pattern, RegexOptions.IgnoreCase);
   MatchCollection matches = rgx.Matches(input);
   if (matches.Count > 0)
   {
      outputBlock.Text += String.Format("{0} ({1} matches):", input, matches.Count) + "\n";
      foreach (Match match in matches)
         outputBlock.Text += "   " + match.Value + "\n";
   }
}

To prevent recompilation, the application should instantiate a single Regex object that is accessible to all code that requires it, as shown in the following rewritten example.

Dim inputs() As String = { "This this is a typo.", _
                           "They said that that man would come." }
Dim pattern As String = "\b(\w+)\s\1\b"
Dim rgx As New Regex(pattern, RegexOptions.IgnoreCase)
For Each input As String In inputs
   Dim matches As MatchCollection = rgx.Matches(input)
   If matches.Count > 0 Then
      outputBlock.Text += String.Format("{0} ({1} matches):", input, matches.Count) & vbCrLf
      For Each match As Match In matches
         outputBlock.Text &= "   " + match.Value & vbCrLf
      Next
   End If
Next

string[] inputs = { "This this is a typo.", 
                    "They said that that man would come." };
string pattern = @"\b(\w+)\s\1\b";
Regex rgx = new Regex(pattern, RegexOptions.IgnoreCase);

foreach (string input in inputs)
{
   MatchCollection matches = rgx.Matches(input);
   if (matches.Count > 0)
   {
      outputBlock.Text += String.Format("{0} ({1} matches):", input, matches.Count) + "\n";
      foreach (Match match in matches)
         outputBlock.Text += "   " + match.Value + "\n";
   }
}

Performing Regular Expression Operations

Whether you decide to instantiate a Regex object and call its methods or call static methods, the Regex class offers the following pattern-matching functionality:

Validation of a match. You call the IsMatch method to determine whether a match is present.
Retrieval of a single match. You call the Match method to retrieve a Match object that represents the first match in a string or in part of a string. Subsequent matches can be retrieved by calling the Match.NextMatch method.
Retrieval of all matches. You call the Matches method to retrieve a System.Text.RegularExpressions.MatchCollection object that represents all the matches found in a string or in part of a string.
Replacement of matched text. You call the Replace method to replace matched text. The replacement text can also be defined by a regular expression. In addition, some of the Replace methods include a MatchEvaluator parameter that enables you to programmatically define the replacement text.
Creation of a string array that is formed from parts of an input string. You call the Split method to split an input string at positions that are defined by the regular expression.

In addition to its pattern-matching methods, the Regex class includes several special-purpose methods:

The Escape method escapes any characters that may be interpreted as regular expression operators in a regular expression or input string.
The Unescape method removes these escape characters.

Examples

The following example uses a regular expression to check for repeated occurrences of words in a string. The regular expression \b(?<word>\w+)\s+(\k<word>)\b can be interpreted as shown in the following table.

Pattern	Description
\b	Start the match at a word boundary.
(?<word>\w+)	Match one or more word characters up to a word boundary. Name this captured group word.
\s+	Match one or more white-space characters.
(\k<word>)	Match the captured group that is named word.
\b	Match a word boundary.

Imports System.Text.RegularExpressions

Public Module Example

   Public Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      ' Define a regular expression for repeated words.
      Dim rx As New Regex("\b(?<word>\w+)\s+(\k<word>)\b", _
                          RegexOptions.IgnoreCase)

      ' Define a test string.        
      Dim text As String = "The the quick brown fox  fox jumped over the lazy dog dog."

      ' Find matches.
      Dim matches As MatchCollection = rx.Matches(text)

      ' Report the number of matches found.
      outputBlock.Text &= String.Format("{0} matches found in:", matches.Count) & vbCrLf
      outputBlock.Text &= String.Format("   {0}", text) & vbCrLf

      ' Report on each match.
      For Each match As Match In matches
         Dim groups As GroupCollection = match.Groups
         outputBlock.Text &= String.Format("'{0}' repeated at positions {1} and {2}", _
                           groups.Item("word").Value, _
                           groups.Item(0).Index, _
                           groups.Item(1).Index) & vbCrLf
      Next
   End Sub
End Module
' The example produces the following output:
'       3 matches found in:
'          The the quick brown fox  fox jumped over the lazy dog dog.
'       'The' repeated at positions 0 and 4
'       'fox' repeated at positions 20 and 25
'       'dog' repeated at positions 50 and 54

using System;
using System.Text.RegularExpressions;

public class Example
{

   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {

      // Define a regular expression for repeated words.
      Regex rx = new Regex(@"\b(?<word>\w+)\s+(\k<word>)\b",
                           RegexOptions.IgnoreCase);

      // Define a test string.        
      string text = "The the quick brown fox  fox jumped over the lazy dog dog.";

      // Find matches.
      MatchCollection matches = rx.Matches(text);

      // Report the number of matches found.
      outputBlock.Text += String.Format("{0} matches found in:\n   {1}",
                        matches.Count,
                        text) + "\n";

      // Report on each match.
      foreach (Match match in matches)
      {
         GroupCollection groups = match.Groups;
         outputBlock.Text += String.Format("'{0}' repeated at positions {1} and {2}",
                           groups["word"].Value,
                           groups[0].Index,
                           groups[1].Index) + "\n";
      }

   }

}
// The example produces the following output:
//       3 matches found in:
//          The the quick brown fox  fox jumped over the lazy dog dog.
//       'The' repeated at positions 0 and 4
//       'fox' repeated at positions 20 and 25
//       'dog' repeated at positions 50 and 54

The following example illustrates the use of a regular expression to check whether a string either represents a currency value or has the correct format to represent a currency value. In this case, the regular expression is built dynamically from the NumberFormatInfo.CurrencyDecimalSeparator, CurrencyDecimalDigits, NumberFormatInfo.CurrencySymbol, NumberFormatInfo.NegativeSign, and NumberFormatInfo.PositiveSign properties for the user's current culture. If the system's current culture is en-US, the resulting regular expression is ^\w*[\+-]?\w?\$?\w?(\d*\.?\d{2}?){1}$. This regular expression can be interpreted as shown in the following table.

Pattern	Description
^	Start at the beginning of the string.
\s*	Match zero or more white-space characters.
[\+-]?	Match zero or one occurrence of either the positive sign or the negative sign.
\s?	Match zero or one white-space character.
\$?	Match zero or one occurrence of the dollar sign.
\s?	Match zero or one white-space character.
\d*	Match zero or more decimal digits.
\.?	Match zero or one decimal point symbol.
\d{2}?	Match two decimal digits zero or one time.
(\d*\.?\d{2}?){1}	Match the pattern of integral and fractional digits separated by a decimal point symbol at least one time.
$	Match the end of the string.

In this case, the regular expression assumes that a valid currency string does not contain group separator symbols, and that it has either no fractional digits or the number of fractional digits defined by the current culture's CurrencyDecimalDigits property.

Imports System.Globalization
Imports System.Text.RegularExpressions

Public Module Example
   Public Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      ' Get the current NumberFormatInfo object to build the regular 
      ' expression pattern dynamically.
      Dim nfi As NumberFormatInfo = NumberFormatInfo.CurrentInfo

      ' Define the regular expression pattern.
      Dim pattern As String
      pattern = "^\s*["
      ' Get the positive and negative sign symbols.
      pattern += Regex.Escape(nfi.PositiveSign + nfi.NegativeSign) + "]?\s?"
      ' Get the currency symbol.
      pattern += Regex.Escape(nfi.CurrencySymbol) + "?\s?"
      ' Add integral digits to the pattern.
      pattern += "(\d*"
      ' Add the decimal separator.
      pattern += Regex.Escape(nfi.CurrencyDecimalSeparator) + "?"
      ' Add the fractional digits.
      pattern += "\d{"
      ' Determine the number of fractional digits in currency values.
      pattern += nfi.CurrencyDecimalDigits.ToString() + "}?){1}$"

      Dim rgx As New Regex(pattern)

      ' Define some test strings.
      Dim tests() As String = {"-42", "19.99", "0.001", "100 USD", _
                               ".34", "0.34", "1,052.21", "$10.62", _
                               "+1.43", "-$0.23"}

      ' Check each test string against the regular expression.
      For Each test As String In tests
         If rgx.IsMatch(test) Then
            outputBlock.Text += String.Format("{0} is a currency value.", test) & vbCrLf
         Else
            outputBlock.Text += String.Format("{0} is not a currency value.", test) & vbCrLf
         End If
      Next
   End Sub
End Module
' The example displays the following output:
'       -42 is a currency value.
'       19.99 is a currency value.
'       0.001 is not a currency value.
'       100 USD is not a currency value.
'       .34 is a currency value.
'       0.34 is a currency value.
'       1,052.21 is not a currency value.
'       $10.62 is a currency value.
'       +1.43 is a currency value.
'       -$0.23 is a currency value.

using System;
using System.Globalization;
using System.Text.RegularExpressions;

public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      // Get the current NumberFormatInfo object to build the regular 
      // expression pattern dynamically.
      NumberFormatInfo nfi = NumberFormatInfo.CurrentInfo;

      // Define the regular expression pattern.
      string pattern;
      pattern = @"^\s*[";
      // Get the positive and negative sign symbols.
      pattern += Regex.Escape(nfi.PositiveSign + nfi.NegativeSign) + @"]?\s?";
      // Get the currency symbol.
      pattern += Regex.Escape(nfi.CurrencySymbol) + @"?\s?";
      // Add integral digits to the pattern.
      pattern += @"(\d*";
      // Add the decimal separator.
      pattern += Regex.Escape(nfi.CurrencyDecimalSeparator) + "?";
      // Add the fractional digits.
      pattern += @"\d{";
      // Determine the number of fractional digits in currency values.
      pattern += nfi.CurrencyDecimalDigits.ToString() + "}?){1}$";

      Regex rgx = new Regex(pattern);

      // Define some test strings.
      string[] tests = { "-42", "19.99", "0.001", "100 USD", 
                         ".34", "0.34", "1,052.21", "$10.62", 
                         "+1.43", "-$0.23" };

      // Check each test string against the regular expression.
      foreach (string test in tests)
      {
         if (rgx.IsMatch(test))
            outputBlock.Text += String.Format("{0} is a currency value.", test) + "\n";
         else
            outputBlock.Text += String.Format("{0} is not a currency value.", test) + "\n";
      }
   }
}
// The example displays the following output:
//       -42 is a currency value.
//       19.99 is a currency value.
//       0.001 is not a currency value.
//       100 USD is not a currency value.
//       .34 is a currency value.
//       0.34 is a currency value.
//       1,052.21 is not a currency value.
//       $10.62 is a currency value.
//       +1.43 is a currency value.
//       -$0.23 is a currency value.

Because the regular expression in this example is built dynamically, we do not know at design time whether the current culture's currency symbol, decimal sign, or positive and negative signs might be misinterpreted by the regular expression engine as regular expression language operators. To prevent any misinterpretation, the example passes each dynamically generated string to the Escape method.

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

The Regex class is immutable (read-only) and is inherently thread safe. Regex objects can be created on any thread and shared between threads. Matching methods can be called from any thread and never alter any global state. However, result objects (Match and MatchCollection) that are returned by Regex methods should be used on a single thread. Although many of these objects are logically immutable, their implementations may delay computation of some results to improve performance; as a result, callers must serialize access to them.

Share via