Regex.Match Method

Definition

Namespace:

System.Text.RegularExpressions

Assemblies:

netstandard.dll, System.Text.RegularExpressions.dll

Searches an input string for a substring that matches a regular expression pattern and returns the first occurrence as a single Match object.

Overloads

Name	Description
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, Int32, Int32)	Searches the input string for the first occurrence of a regular expression, beginning at the specified starting position and searching only the specified number of characters.
Match(String, String, RegexOptions)	Searches the input string for the first occurrence of the specified regular expression, using the specified matching options.
Match(String, String, RegexOptions, TimeSpan)	Searches the input string for the first occurrence of the specified regular expression, using the specified matching options and time-out interval.

Match(String)

Source:

Regex.Match.cs

Searches the specified input string for the first occurrence of the regular expression specified in the Regex constructor.

public:
 System::Text::RegularExpressions::Match ^ Match(System::String ^ input);

public System.Text.RegularExpressions.Match Match(string input);

member this.Match : string -> System.Text.RegularExpressions.Match

Public Function Match (input As String) As Match

Parameters

input

String

The string to search for a match.

Returns

Match

An object that contains information about the match.

Exceptions

ArgumentNullException

input is null.

RegexMatchTimeoutException

A time-out occurred.

Remarks

The Match(String) method returns the first substring that matches a regular expression pattern in an input string.

You can determine whether the regular expression pattern has been found in the input string by checking the returned Match object's Success property. If a match is found, the returned Match object's Value property contains the matched substring. If no match is found, its value is Empty.

This method returns the first match. You can retrieve subsequent matches by repeatedly calling the returned Match object's NextMatch() method. You can also retrieve all matches in a single method call by calling Matches(String).

The RegexMatchTimeoutException exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the Regex(String, RegexOptions, TimeSpan) constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the Regex object is created. If no time-out is defined in the Regex constructor call or in the application domain's properties, or if the time-out value is InfiniteMatchTimeout, no exception is thrown.

See also

• NextMatch()
• Regular Expression Language - Quick Reference

Match(String, Int32)

Source:

Regex.Match.cs

Searches the input string for the first occurrence of a regular expression, beginning at the specified starting position in the string.

public:
 System::Text::RegularExpressions::Match ^ Match(System::String ^ input, int startat);

public System.Text.RegularExpressions.Match Match(string input, int startat);

member this.Match : string * int -> System.Text.RegularExpressions.Match

Public Function Match (input As String, startat As Integer) As Match

Parameters

input

String

The string to search for a match.

startat

Int32

The zero-based character position at which to start the search.

Returns

Match

An object that contains information about the match.

Exceptions

ArgumentNullException

input is null.

ArgumentOutOfRangeException

startat is less than zero or greater than the length of input.

RegexMatchTimeoutException

A time-out occurred.

Remarks

The Match(String, Int32) method returns the first substring that matches a regular expression pattern, starting at or after the startat character position, in an input string. The regular expression pattern for which the Match(String, Int32) method searches is defined by the call to one of the Regex class constructors. For information about the language elements used to build a regular expression pattern, see Regular Expression Language - Quick Reference.

The startat parameter

Use the startat parameter to specify the character position at which the search starts. In a left-to-right search, any matches that begin before startat in the string are ignored. To start at the default position, use the Match(String) overload (or pass 0 for a left-to-right search and input.Length for a right-to-left search). Despite starting the search at startat, the index of any returned match is relative to the start of the string.

Although the regular expression engine doesn't return any match starting before startat, it doesn't ignore the string before startat. This means that assertions such as anchors or lookbehind assertions still apply to the input as a whole. For example, the following code includes a pattern with a lookbehind assertion that's satisfied even though it occurs before the startat index of 5 in the input string.

string input = "Zip code: 98052";
var regex = new Regex(@"(?<=Zip code: )\d{5}");
Match match = regex.Match(input, 5);
if (match.Success)
{
    Console.WriteLine($"Match found: {match.Value}");
}

// This code prints the following output:
//
// Match found: 98052

Tip

• If a pattern starts with the ^ anchor, startat is greater than 0, and the regular expression isn't using RegexOptions.Multiline, no matches will ever be found since they are constrained by ^ to start at index 0.
• The \G anchor is satisfied at startat. Because of this, if you want to restrict a match so that it begins exactly at a particular character position in the string, anchor the regular expression with a \G on the left for a left-to-right pattern. This restricts the match so it must start exactly at startat (or, when multiple matches are desired, so the matches are contiguous).

Right-to-left searches

A right-to-left search, that is, when the regular expression pattern is constructed with the RegexOptions.RightToLeft option, behaves in the following ways:

• The scan moves in the opposite direction and the pattern is matched from back (right) to front (left).
• The default starting position is the right end of the input string.
• If startat is specified, the right-to-left scan begins at the character at startat - 1 (not startat).
• When the \G anchor is specified at the right end of a pattern, it restricts the (first) match to end exactly at startat - 1.

For more information about right-to-left searches, see Right-to-left mode.

Determine whether a match is found

You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned Match object's Success property. If a match is found, the returned Match object's Value property contains the substring from input that matches the regular expression pattern. If no match is found, its value is String.Empty.

First or multiple matches

This method returns the first substring found by scanning input starting at the startat position (or, for right-to-left searches, at startat - 1) that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned Match object's Match.NextMatch method. You can also retrieve all matches in a single method call by calling the Regex.Matches(String, Int32) method.

Time-out exceptions

The RegexMatchTimeoutException exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the Regex.Regex(String, RegexOptions, TimeSpan) constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the Regex object is created. If no time-out is defined in the Regex constructor call or in the application domain's properties, or if the time-out value is Regex.InfiniteMatchTimeout, no exception is thrown.

See also

• NextMatch()
• Regular Expression Language - Quick Reference

Match(String, String)

Source:

Regex.Match.cs

Searches the specified input string for the first occurrence of the specified regular expression.

public:
 static System::Text::RegularExpressions::Match ^ Match(System::String ^ input, System::String ^ pattern);

public static System.Text.RegularExpressions.Match Match(string input, string pattern);

static member Match : string * string -> System.Text.RegularExpressions.Match

Public Shared Function Match (input As String, pattern As String) As Match

Parameters

input

String

The string to search for a match.

pattern

String

The regular expression pattern to match.

Returns

Match

An object that contains information about the match.

Exceptions

ArgumentException

A regular expression parsing error occurred.

ArgumentNullException

input or pattern is null.

RegexMatchTimeoutException

A time-out occurred.

Remarks

The static Match(String, String) method is equivalent to constructing a Regex object with the specified pattern and calling the instance Match(String) method. The regular expression engine caches the pattern.

You can determine whether the regular expression pattern has been found in the input string by checking the returned Match object's Success property. If a match is found, the returned Match object's Value property contains the matched substring. If no match is found, its value is Empty.

You can retrieve subsequent matches by repeatedly calling the returned Match object's NextMatch() method. You can also retrieve all matches in a single method call by calling the Matches(String, String) method.

Notes to Callers

This method times out after an interval that is equal to the default time-out value of the application domain in which it is called. If a time-out value has not been defined for the application domain, the value InfiniteMatchTimeout, which prevents the method from timing out, is used. The recommended static method for retrieving a pattern match is Match(String, String), which lets you set the time-out interval.

See also

• NextMatch()
• Regular Expression Language - Quick Reference

Match(String, Int32, Int32)

Source:

Regex.Match.cs

Searches the input string for the first occurrence of a regular expression, beginning at the specified starting position and searching only the specified number of characters.

public:
 System::Text::RegularExpressions::Match ^ Match(System::String ^ input, int beginning, int length);

public System.Text.RegularExpressions.Match Match(string input, int beginning, int length);

member this.Match : string * int * int -> System.Text.RegularExpressions.Match

Public Function Match (input As String, beginning As Integer, length As Integer) As Match

Parameters

input

String

The string to search for a match.

beginning

Int32

The zero-based character position in the input string that defines the leftmost position to be searched.

length

Int32

The number of characters in the substring to include in the search.

Returns

Match

An object that contains information about the match.

Exceptions

ArgumentNullException

input is null.

ArgumentOutOfRangeException

beginning is less than zero or greater than the length of input. -or- length is less than zero or greater than the length of input. -or- beginning + length - 1 identifies a position that is outside the range of input.

RegexMatchTimeoutException

A time-out occurred.

Remarks

The Match(String, Int32, Int32) method searches the portion of input defined by the beginning and length parameters for the regular expression pattern. beginning always defines the index of the leftmost character to include in the search, and length defines the maximum number of characters to search. Together, they define the range of the search. The behavior is exactly as if the input was effectively input.Substring(beginning, length), except that the index of any match is counted relative to the start of input. This means that any anchors or zero-width assertions at the start or end of the pattern behave as if there is no input outside of this range.

If the search proceeds from left to right (the default), the regular expression engine searches from the character at index beginning to the character at index beginning + length - 1. If the regular expression engine was instantiated by using the RightToLeft option, the engine searches from the character at index beginning + length - 1 to the character at index beginning.

This method returns the first match found within this range. You can retrieve subsequent matches by repeatedly calling the returned Match object's NextMatch() method.

See also

• NextMatch()
• Regular Expression Language - Quick Reference

Match(String, String, RegexOptions)

Source:

Regex.Match.cs

Searches the input string for the first occurrence of the specified regular expression, using the specified matching options.

public:
 static System::Text::RegularExpressions::Match ^ Match(System::String ^ input, System::String ^ pattern, System::Text::RegularExpressions::RegexOptions options);

public static System.Text.RegularExpressions.Match Match(string input, string pattern, System.Text.RegularExpressions.RegexOptions options);

static member Match : string * string * System.Text.RegularExpressions.RegexOptions -> System.Text.RegularExpressions.Match

Public Shared Function Match (input As String, pattern As String, options As RegexOptions) As Match

Parameters

input

String

The string to search for a match.

pattern

String

The regular expression pattern to match.

options

RegexOptions

A bitwise combination of the enumeration values that provide options for matching.

Returns

Match

An object that contains information about the match.

Exceptions

ArgumentException

A regular expression parsing error occurred.

ArgumentNullException

input or pattern is null.

ArgumentOutOfRangeException

options is not a valid bitwise combination of RegexOptions values.

RegexMatchTimeoutException

A time-out occurred.

Remarks

The static Match(String, String, RegexOptions) method is equivalent to constructing a Regex object with the Regex(String, RegexOptions) constructor and calling the instance Match(String) method.

You can determine whether the regular expression pattern has been found in the input string by checking the returned Match object's Success property. You can retrieve subsequent matches by repeatedly calling the returned Match object's NextMatch() method. You can also retrieve all matches in a single method call by calling the Matches(String, String, RegexOptions) method.

Notes to Callers

This method times out after an interval that is equal to the default time-out value of the application domain in which it is called. If a time-out value has not been defined for the application domain, the value InfiniteMatchTimeout, which prevents the method from timing out, is used. The recommended static method for retrieving a pattern match is Match(String, String), which lets you set the time-out interval.

See also

• NextMatch()
• Regular Expression Language - Quick Reference

Match(String, String, RegexOptions, TimeSpan)

Source:

Regex.Match.cs

Searches the input string for the first occurrence of the specified regular expression, using the specified matching options and time-out interval.

public:
 static System::Text::RegularExpressions::Match ^ Match(System::String ^ input, System::String ^ pattern, System::Text::RegularExpressions::RegexOptions options, TimeSpan matchTimeout);

public static System.Text.RegularExpressions.Match Match(string input, string pattern, System.Text.RegularExpressions.RegexOptions options, TimeSpan matchTimeout);

static member Match : string * string * System.Text.RegularExpressions.RegexOptions * TimeSpan -> System.Text.RegularExpressions.Match

Public Shared Function Match (input As String, pattern As String, options As RegexOptions, matchTimeout As TimeSpan) As Match

Parameters

input

String

The string to search for a match.

pattern

String

The regular expression pattern to match.

options

RegexOptions

A bitwise combination of the enumeration values that provide options for matching.

matchTimeout

TimeSpan

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

Returns

Match

An object that contains information about the match.

Exceptions

ArgumentException

A regular expression parsing error occurred.

ArgumentNullException

input or pattern is null.

ArgumentOutOfRangeException

options is not a valid bitwise combination of RegexOptions values. -or- matchTimeout is negative, zero, or greater than approximately 24 days.

RegexMatchTimeoutException

A time-out occurred.

Remarks

The static Match(String, String, RegexOptions, TimeSpan) method is equivalent to constructing a Regex object with the Regex(String, RegexOptions, TimeSpan) constructor and calling the instance Match(String) method.

You can determine whether the regular expression pattern has been found in the input string by checking the returned Match object's Success property. You can retrieve subsequent matches by repeatedly calling the returned Match object's NextMatch() method.

The matchTimeout parameter specifies how long a pattern matching method should try to find a match before it times out. 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. If no match is found in that time interval, the method throws a RegexMatchTimeoutException exception. matchTimeout overrides any default time-out value defined for the application domain in which the method executes.

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 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.

See also

• Regular Expression Language - Quick Reference