Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
Represents an immutable regular expression.
Inheritance Hierarchy
System. . :: . .Object
System.Text.RegularExpressions..::..Regex
Namespace: System.Text.RegularExpressions
Assembly: System.Text.RegularExpressions (in System.Text.RegularExpressions.dll)
Syntax
'Declaration
Public NotInheritable Class Regex
public sealed class Regex
public ref class Regex sealed
[<Sealed>]
type Regex = class end
public final class Regex
The Regex type exposes the following members.
Constructors
| Name | Description | |
|---|---|---|
.gif "Public method") |
Regex() () () () | Initializes a new instance of the Regex class. |
|
Regex(String) | Initializes a new instance of the Regex class for the specified regular expression. |
|
Regex(String, RegexOptions) | Initializes a new instance of the Regex class for the specified regular expression, with options that modify the pattern. |
Top
Properties
| Name | Description | |
|---|---|---|
.gif "Public property") .gif "Static member") |
CacheSize | Gets or sets the maximum number of entries in the current static cache of compiled regular expressions. |
|
Options | Gets the options that were passed into the Regex constructor. |
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. |
|
GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
|
GetMatches(String) | Searches the specified input string for all occurrences of a regular expression. |
|
GetMatches(array<String> [] () [] []) | Searches the specified array for all occurrences of a regular expression. |
|
GetMatches(array<String> [] () [] [], Int32, Int32) | Searches the specified array for all occurrences of a regular expression, beginning at the specified starting position and ending at the specified length. |
|
GetType | Gets the Type of the current instance. (Inherited from Object.) |
|
IsMatch(String) | Indicates whether the regular expression specified in the Regex constructor finds a match in a specified input string. |
|
IsMatch(String, Int32) | Indicates whether the regular expression specified in the Regex constructor finds a match in the specified input string, beginning at the specified starting position in the string. |
|
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, beginning at the specified starting position in the string. |
|
Match(String, String) | Searches the specified input string for the first occurrence of the specified regular expression. |
|
Match(String, String, RegexOptions) | Searches the input string for the first occurrence of the specified regular expression, using the specified matching options. |
|
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 a specified regular expression. |
|
Matches(String, String, RegexOptions) | Searches the specified input string for all occurrences of a specified regular expression, using the specified matching options. |
|
Replace(String, String) | In a specified input string, replaces all strings that match a regular expression pattern with a specified replacement string. |
|
Replace(String, String, Int32, Int32) | In a specified input substring, replaces a specified maximum number of strings that match a regular expression pattern with a specified replacement string. |
|
Split(String) | Splits an input string into an array of substrings at the positions defined by a regular expression pattern specified in the Regex constructor. |
|
Split(String, Int32) | Splits an input string a specified maximum number of times into an array of substrings, at the positions defined by a regular expression specified in the Regex constructor. |
|
Split(String, String, RegexOptions) | Splits an input string into an array of substrings at the positions defined by a specified regular expression pattern. Specified options modify the matching operation. |
|
Split(Regex, String, Int32, Int32) | Splits the input string at the positions defined by a specified regular expression pattern and with the specified options. |
|
Split(String, Int32, Int32, Int32) | Splits an input string a specified maximum number of times into an array of substrings, at the positions defined by a regular expression specified in the Regex constructor. |
|
Split(String, RegexOptions, String, Int32, Int32) | Splits the input string at the positions defined by a specified regular expression pattern. Specified options modify the matching operation. |
|
ToFullRegularExpression | Converts a simplified regular expression to a full regular expression. |
|
ToString | Returns the regular expression pattern that was passed into the Regex constructor. (Overrides Object. . :: . .ToString() () () ().) |
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 extract, edit, replace, or delete text substrings; and to add the extracted strings to a collection to generate a report.
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 .NET Framework Regular Expressions.
Back to Remarks
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 the pattern can be used. Because Regex objects are immutable, this is a one-time procedure that occurs when a Regex class constructor or 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, caching 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.
When you instantiate new Regex objects with regular expressions that have previously been compiled.
To prevent recompilation, you should instantiate a single Regex object that is accessible to all code that requires it.
Back to Remarks
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.
Back to Remarks
Defining a Time-Out Value
The .NET Framework supports a full-featured regular expression language that provides substantial power and flexibility in pattern matching. However, the power and flexibility come at a cost: the risk of poor performance. Regular expressions that perform poorly are surprisingly easy to create. In some cases, regular expression operations that rely on excessive backtracking can appear to stop responding when they process text that nearly matches the regular expression pattern.
How you handle the exception depends on the cause of the exception. If the exception occurs because the time-out interval is set too low or because of excessive machine load, you can increase the time-out interval and retry the matching operation. If the exception occurs because the regular expression relies on excessive backtracking, you can assume that a match does not exist, and, optionally, you can log information that will help you modify the regular expression pattern.
Back to Remarks
Thread Safety
The Regex class is immutable (read-only) and thread safe. Regex objects can be created on any thread and shared between threads. For more information, see [<topic://cpconThreadSafety>].