Export (0) Print
Expand All

Regex Constructor (String, RegexOptions, TimeSpan)

.NET Framework 4.5

Initializes a new instance of the Regex class for the specified regular expression, with options that modify the pattern and a value that specifies how long a pattern matching method should attempt a match before it times out.

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

public:
Regex(
	String^ pattern, 
	RegexOptions options, 
	TimeSpan matchTimeout
)

Parameters

pattern
Type: System::String

The regular expression pattern to match.

options
Type: System.Text.RegularExpressions::RegexOptions

A bitwise combination of the enumeration values that modify the regular expression.

matchTimeout
Type: System::TimeSpan

A time-out interval, or Regex::InfiniteMatchTimeout to indicate that the method should not time out.

ExceptionCondition
ArgumentException

A regular expression parsing error occurred.

ArgumentNullException

pattern is nullptr.

ArgumentOutOfRangeException

options is not a valid RegexOptions value.

-or-

matchTimeout is negative, zero, or greater than approximately 24 days.

The pattern parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see the .NET Framework Regular Expressions and Regular Expression Language - Quick Reference topics.

A Regex object is immutable, which means that it can be used only for the match pattern that you define when you create it. However, it can be used any number of times without being recompiled.

The matchTimeout parameter specifies how long a pattern-matching method should try to find a match before it times out. If no match is found in that time interval, the pattern-matching method throws a RegexMatchTimeoutException exception. matchTimeout overrides any default time-out value defined for the application domain in which the Regex object is created. The instance pattern-matching methods that observe the matchTimeout time-out interval include the following:

Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see Best Practices for Regular Expressions in the .NET Framework and Backtracking in Regular Expressions. To set a reasonable time-out interval, consider the following factors:

  • The length and complexity of the regular expression pattern. Longer and more complex regular expressions require more time than shorter and simpler ones.

  • The expected machine load. Processing takes more time on systems that have high CPU and memory utilization.

Notes to Callers

We recommend that you set the matchTimeout parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying Regex::InfiniteMatchTimeout, the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions:

  • When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users.

  • When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches.

  • When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match.

The following example calls the Regex(String, RegexOptions, TimeSpan) constructor to instantiate a Regex object with a time-out value of one second. The regular expression pattern (a+)+$, which matches one or more sequences of one or more "a" characters at the end of a line, is subject to excessive backtracking. If a RegexMatchTimeoutException is thrown, the example increases the time-out value up to the maximum value of three seconds. Otherwise, it abandons the attempt to match the pattern.

No code example is currently available or this language may not be supported.

.NET Framework

Supported in: 4.5

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

Show:
© 2014 Microsoft