Regex.Escape Method

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

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.

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

Syntax

'Declaration
Public Shared Function Escape ( _
    str As String _
) As String

public static string Escape(
    string str
)

Parameters

• str
  Type: System.String
  The input string containing the text to convert.

Return Value

Type: System.String
A string of characters with any metacharacters converted to their escaped form.

Exceptions

Exception	Condition
ArgumentNullException	str is nulla null reference (Nothing in Visual Basic).

Remarks

Escape converts a string so that the regular expression engine will interpret any metacharacters that it may contain as character literals. For example, consider a regular expression that is designed to extract comments that are delimited by opening and closing brackets ([ and ]) from text. In the following example, the regular expression "[(.*?)]" is interpreted as a character class. Rather than matching comments embedded in the input text, the regular expression matches each opening or closing parenthesis, period, asterisk, or question mark.

Dim pattern As String = "[(.*?)]"
Dim input As String = "The animal [what kind?] was visible [by whom?] from the window."

Dim matches As MatchCollection = Regex.Matches(input, pattern)
Dim commentNumber As Integer = 0
outputBlock.Text += String.Format("{0} produces the following matches:", pattern) & vbCrLf
For Each match As Match In matches
   commentNumber += 1
   outputBlock.Text += String.Format("{0}: {1}", commentNumber, match.Value) & vbCrLf
Next
' This example displays the following output:
'       1: ?
'       2: ?
'       3: .

string pattern = "[(.*?)]";
string input = "The animal [what kind?] was visible [by whom?] from the window.";

MatchCollection matches = Regex.Matches(input, pattern);
int commentNumber = 0;
outputBlock.Text += String.Format("{0} produces the following matches:", pattern) + "\n";
foreach (Match match in matches)
   outputBlock.Text += String.Format("   {0}: {1}", ++commentNumber, match.Value) + "\n";

// This example displays the following output:
//       [(.*?)] produces the following matches:
//          1: ?
//          2: ?
//          3: .

However, if the opening bracket is escaped by passing it to the Escape method, the regular expression succeeds in matching comments that are embedded in the input string. The following example illustrates this.

Dim pattern As String = Regex.Escape("[") + "(.*?)]"
Dim input As String = "The animal [what kind?] was visible [by whom?] from the window."

Dim matches As MatchCollection = Regex.Matches(input, pattern)
Dim commentNumber As Integer = 0
outputBlock.Text += String.Format("{0} produces the following matches:", pattern) & vbCrLf
For Each match As Match In matches
   commentNumber += 1
   outputBlock.Text += String.Format("   {0}: {1}", commentNumber, match.Value) & vbCrLf
Next
' This example displays the following output:
'       \[(.*?)] produces the following matches:
'          1: [what kind?]
'          2: [by whom?]

string pattern = Regex.Escape("[") + "(.*?)]";
string input = "The animal [what kind?] was visible [by whom?] from the window.";

MatchCollection matches = Regex.Matches(input, pattern);
int commentNumber = 0;
outputBlock.Text += String.Format("{0} produces the following matches:", pattern) + "\n";
foreach (Match match in matches)
   outputBlock.Text += String.Format("   {0}: {1}", ++commentNumber, match.Value) + "\n";

// This example displays the following output:
//       \[(.*?)] produces the following matches:
//          1: [what kind?]
//          2: [by whom?]

In a regular expression that is defined using static text, characters that are to be interpreted literally rather than as metacharacters can be escaped by preceding them with a backslash symbol (\) as well as by calling the Escape method. In a regular expression that is defined dynamically using characters that are not known at design time, calling the Escape method is particularly important to ensure that the regular expression engine interprets individual characters as literals rather than as metacharacters.

Note:
If a regular expression pattern includes either the number sign (#) or literal white-space characters, they must be escaped if input text is parsed with the RegexOptions.IgnorePatternWhitespace option enabled.

While the Escape method escapes the opening bracket ([) and opening brace ({) characters, it does not escape their corresponding closing characters (] and }). In most cases, escaping these is not necessary. If a closing bracket or brace is not preceded by its corresponding opening character, the regular expression engine interprets it literally. If an opening bracket or brace is interpreted as a metacharacter, the regular expression engine interprets the first corresponding closing character as a metacharacter. If this is not the desired behavior, the closing bracket or brace should be escaped by explicitly prepending the backslash (\) character. For an illustration, see the Example section.

Examples

The following example extracts comments from text. It assumes that the comments are delimited by a begin comment symbol and an end comment symbol that is selected by the user. Because the comment symbols are to be interpreted literally, they are passed to the Escape method to ensure that they cannot be misinterpreted as metacharacters. In addition, the example explicitly checks whether the end comment symbol entered by the user is a closing bracket (]) or brace (}). If it is, a backslash character (\) is prepended to the bracket or brace so that it is interpreted literally. Note that the example also uses the Match.Groups collection to display the comment only, rather than the comment together with its opening and closing comment symbols.

Imports System.Text.RegularExpressions

Module Example
   Public Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      Dim beginComment As Char = "["c
      Dim endComment As Char = "]"c

      Dim input As String = "Text [comment comment comment] more text [comment]"
      Dim pattern As String = Regex.Escape(beginComment.ToString()) + "(.*?)"
      Dim endPattern As String = Regex.Escape(endComment.ToString())
      If endComment = "]"c OrElse endComment = "}"c Then endPattern = "\" + endPattern
      pattern += endPattern

      Dim matches As MatchCollection = Regex.Matches(input, pattern)
      outputBlock.Text &= pattern & vbCrLf
      Dim commentNumber As Integer = 0
      For Each match As Match In matches
         commentNumber += 1
         outputBlock.Text += String.Format("{0}: {1}", commentNumber, match.Groups(1).Value) & vbCrLf
      Next
   End Sub
End Module
' The example shows possible output from the example:
'       \[(.*?)\]
'       1: comment comment comment
'       2: comment

using System;
using System.Text.RegularExpressions;

public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      char beginComment = '[';
      char endComment = ']';

      string input = "Text [comment comment comment] more text [comment]";
      string pattern;
      pattern = Regex.Escape(beginComment.ToString()) + @"(.*?)";
      string endPattern = Regex.Escape(endComment.ToString());
      if (endComment == ']' || endComment == '}') endPattern = @"\" + endPattern;
      pattern += endPattern;
      MatchCollection matches = Regex.Matches(input, pattern);
      outputBlock.Text += pattern + "\n";
      int commentNumber = 0;
      foreach (Match match in matches)
         outputBlock.Text += String.Format("{0}: {1}", ++commentNumber, match.Groups[1].Value) + "\n";

   }
}
// The example shows possible output from the example:
//       \[(.*?)\]
//       1: comment comment comment
//       2: comment

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.

See Also

Reference

Regex Class

System.Text.RegularExpressions Namespace