Regex.Match 方法

定義

命名空間:

System.Text.RegularExpressions

組件:

netstandard.dll, System.Text.RegularExpressions.dll

搜尋輸入字串中符合正則表達式模式的子字串，並以單一 Match 物件回傳第一次出現。

多載

名稱	Description
Match(String)	搜尋指定的輸入字串，尋找建構子中指定的 Regex 正則表達式的首次出現。
Match(String, Int32)	搜尋輸入字串中第一次出現的正則表示式，從字串中指定的起始位置開始。
Match(String, String)	搜尋指定的輸入字串中第一個出現的指定正則表達式。
Match(String, Int32, Int32)	搜尋輸入字串中第一次出現的正則表示式，從指定的起始位置開始，並只搜尋指定的字元數。
Match(String, String, RegexOptions)	使用指定的比對選項，搜尋輸入字串中第一個出現的指定正則表達式。
Match(String, String, RegexOptions, TimeSpan)	使用指定的比對選項和超時時間間隔，搜尋輸入字串中第一個出現的指定正則表達式。

Match(String)

來源:

Regex.Match.cs

搜尋指定的輸入字串，尋找建構子中指定的 Regex 正則表達式的首次出現。

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

參數

input

String

要搜尋相符專案的字串。

傳回

Match

物件，包含相符專案的相關信息。

例外狀況

ArgumentNullException

input 是 null。

RegexMatchTimeoutException

發生逾時。

備註

該 Match(String) 方法會回傳第一個與輸入字串中正則表達式模式相符的子字串。

你可以透過檢查回傳 Match 物件的 Success 屬性來判斷輸入字串中是否找到正則表達式模式。 若找到匹配，回傳 Match 物件的屬性包含 Value 匹配的子字串。 如果找不到匹配項目，其值為 Empty。

此方法回傳第一個匹配。 您可以透過反覆調用返回的 Match 物件的 NextMatch() 方法，來檢索後續匹配項目。 你也可以透過呼叫 Matches(String)來取得單一方法呼叫中的所有匹配。

如果比對作業的運行時間超過 RegexMatchTimeoutException 建構函式指定的超時時間間隔，就會擲回 Regex(String, RegexOptions, TimeSpan) 例外狀況。 如果您在呼叫建構函式時未設定超時時間間隔，則如果作業超過為建立 Regex 對象的應用程式域所建立的任何逾時值，則會擲回例外狀況。 如果在 Regex 建構函式呼叫或應用程式域的屬性中未定義逾時，或逾時值 InfiniteMatchTimeout，則不會擲回任何例外狀況。

另請參閱

• NextMatch()
• 正則表達式語言 - 快速參考

Match(String, Int32)

來源:

Regex.Match.cs

搜尋輸入字串中第一次出現的正則表示式，從字串中指定的起始位置開始。

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

參數

input

String

要搜尋相符專案的字串。

startat

Int32

要開始搜尋之以零起始的字元位置。

傳回

Match

物件，包含相符專案的相關信息。

例外狀況

ArgumentNullException

input 是 null。

ArgumentOutOfRangeException

startat 小於零或大於 的 input長度。

RegexMatchTimeoutException

發生逾時。

備註

Match(String, Int32) 方法會傳回符合正則表達式模式的第一個子字串，從輸入字串中的 startat 字元位置開始或之後。 Match(String, Int32) 方法搜尋的正規表達式模式是由其中一個 Regex 類別建構函式的呼叫所定義。 如需用來建置正規表示式模式之語言項目的相關信息，請參閱 正規表示式語言 - 快速參考。

startat 參數

使用參數 startat 指定搜尋開始的字元位置。 在從左到右的搜尋中，字串中之前開始 startat 的匹配會被忽略。 要從預設位置開始，使用超載（ Match(String) 或通過 0 進行左至右搜尋， input.Length 或從右至左搜尋）。 儘管搜尋從 startat開始，任何回傳匹配的索引仍相對於字串的起始點。

雖然正則表達式引擎不會在 startat之前傳回任何匹配項目，但它不會忽略 startat之前的字串。 這表示像 錨點的斷言 或 向後檢測的斷言 仍然適用於整個輸入。 例如，下列程式碼包含一個包含反向預測的模式，即使它出現在輸入字串中5之前的startat索引，它仍然被滿足。

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

• 如果一個模式以錨點開始 ^ ，且 startat 大於 0，且正則表達式未使用 RegexOptions.Multiline，則永遠找不到匹配，因為它們被限制 ^ 為從索引 0 開始。
• \G 錨點 在 startat滿足。 因此，如果您想限制匹配，使其於字串中特定字符位置開始，請將正則表達式以 \G 在左側錨定，以適用於從左至右的模式。 這會限制匹配，必須精確從 startat 開始（或，當需要多個匹配時，匹配必須是連續的）。

由右至左搜尋

從右至左搜尋，也就是使用 RegexOptions.RightToLeft 選項建構正則表示式模式時，會以下列方式運作：

• 掃描會向相反方向移動，且模式會從後方（右）到前方（左）進行比對。
• 默認起始位置是輸入字串的右端。
• 如果指定了 startat，則由右至左掃描從字元開始於 startat - 1 （而非 startat）。
• 當 \G 錨點被指定在模式的右端時，將限制首次比對必須恰好以 startat - 1 作結尾。

如需從右至左搜尋的詳細資訊，請參閱 從右至左模式。

判斷是否找到相符

您可以藉由檢查傳回 Match 物件的 Success 屬性的值，來判斷輸入字串中是否已找到正規表示式模式。 如果找到相符項目，傳回 Match 物件的 Value 屬性會包含符合正則表達式模式之 input 子字串。 如果找不到匹配項目，其值為 String.Empty。

第一個或多個相符項目

此方法回傳從位置（input或從右至左搜尋為 startat -1）與正則表達式模式相符的位置掃描後找到startat的第一個子字串。 您可以透過反覆調用返回的 Match 物件的 Match.NextMatch 方法，來檢索後續匹配項目。 您也可以透過呼叫 Regex.Matches(String, Int32) 方法來一次取得所有相符項目。

逾時例外狀況

如果比對作業的運行時間超過 RegexMatchTimeoutException 建構函式指定的超時時間間隔，就會擲回 Regex.Regex(String, RegexOptions, TimeSpan) 例外狀況。 如果您在呼叫建構函式時未設定超時時間間隔，則如果作業超過為建立 Regex 對象的應用程式域所建立的任何逾時值，則會擲回例外狀況。 如果在 Regex 建構函式呼叫或應用程式域的屬性中未定義逾時，或逾時值 Regex.InfiniteMatchTimeout，則不會擲回任何例外狀況。

另請參閱

• NextMatch()
• 正則表達式語言 - 快速參考

Match(String, String)

來源:

Regex.Match.cs

搜尋指定的輸入字串中第一個出現的指定正則表達式。

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

參數

input

String

要搜尋相符專案的字串。

pattern

String

要比對的正則表達式模式。

傳回

Match

物件，包含相符專案的相關信息。

例外狀況

ArgumentException

發生正則表達式剖析錯誤。

ArgumentNullException

input 或 pattern 為 null。

RegexMatchTimeoutException

發生逾時。

備註

靜態 Match(String, String) 方法等同於用 Regex 指定模式建構物件並呼叫實例 Match(String) 方法。 正則表達式引擎會快取這個模式。

你可以透過檢查回傳 Match 物件的 Success 屬性來判斷輸入字串中是否找到正則表達式模式。 若找到匹配，回傳 Match 物件的屬性包含 Value 匹配的子字串。 如果找不到匹配項目，其值為 Empty。

您可以透過反覆調用返回的 Match 物件的 NextMatch() 方法，來檢索後續匹配項目。 您也可以透過呼叫 Matches(String, String) 方法來一次取得所有相符項目。

給呼叫者的注意事項

這個方法會在間隔後逾時，這個間隔等於呼叫它之應用程式域的預設逾時值。 若應用程式域尚未定義逾時值，則使用阻止方法逾時的值 InfiniteMatchTimeout。 建議的靜態方法為 Match(String, String)，可設定逾時間隔。

另請參閱

• NextMatch()
• 正則表達式語言 - 快速參考

Match(String, Int32, Int32)

來源:

Regex.Match.cs

搜尋輸入字串中第一次出現的正則表示式，從指定的起始位置開始，並只搜尋指定的字元數。

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

參數

input

String

要搜尋相符專案的字串。

beginning

Int32

輸入字串中以零起始的字元位置，定義要搜尋的最左邊位置。

length

Int32

要包含在搜尋中的子字串中的字元數。

傳回

Match

物件，包含相符專案的相關信息。

例外狀況

ArgumentNullException

input 是 null。

ArgumentOutOfRangeException

beginning 小於零或大於 的 input長度。 -或- length 小於零或大於 的 input長度。 -或- beginning + length - 1 表示位於 範圍 input之外的位置。

RegexMatchTimeoutException

發生逾時。

備註

該Match(String, Int32, Int32)方法搜尋由 input 和 beginning 參數定義的length正則表達式模式部分。 beginning 總是定義搜尋中最左邊字元的索引，並 length 定義搜尋的最大字元數。 它們會一起定義搜尋的範圍。 行為與輸入實際上為 input.Substring(beginning, length)完全相同，不同的是，任何匹配的索引相對於 的 input起始點被計數。 這表示圖案開始或結束時的任何錨點或零寬度斷言，行為就像沒有超出此範圍的輸入一樣。

如果搜尋從左到右（預設），正則表達式引擎會從索引 beginning 的字元搜尋到索引為 beginning + length - 1 的字元。 若正則表達式引擎是透過選項RightToLeft實例化，引擎會從索引beginning + length為 -1 的字元搜尋到索引為 beginning的字元。

此方法會回傳該範圍內的第一個匹配。 您可以透過反覆調用返回的 Match 物件的 NextMatch() 方法，來檢索後續匹配項目。

另請參閱

• NextMatch()
• 正則表達式語言 - 快速參考

Match(String, String, RegexOptions)

來源:

Regex.Match.cs

使用指定的比對選項，搜尋輸入字串中第一個出現的指定正則表達式。

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

參數

input

String

要搜尋相符專案的字串。

pattern

String

要比對的正則表達式模式。

options

RegexOptions

列舉值的位元組合，提供比對的選項。

傳回

Match

物件，包含相符專案的相關信息。

例外狀況

ArgumentException

發生正則表達式剖析錯誤。

ArgumentNullException

input 或 pattern 為 null。

ArgumentOutOfRangeException

options 不是有效的位元組合 RegexOptions 。

RegexMatchTimeoutException

發生逾時。

備註

靜態Match(String, String, RegexOptions)方法等同於用RegexRegex(String, RegexOptions)建構子建構物件並呼叫實例Match(String)方法。

你可以透過檢查回傳 Match 物件的 Success 屬性來判斷輸入字串中是否找到正則表達式模式。 您可以透過反覆調用返回的 Match 物件的 NextMatch() 方法，來檢索後續匹配項目。 您也可以透過呼叫 Matches(String, String, RegexOptions) 方法來一次取得所有相符項目。

給呼叫者的注意事項

這個方法會在間隔後逾時，這個間隔等於呼叫它之應用程式域的預設逾時值。 若應用程式域尚未定義逾時值，則使用阻止方法逾時的值 InfiniteMatchTimeout。 建議的靜態方法為 Match(String, String)，可設定逾時間隔。

另請參閱

• NextMatch()
• 正則表達式語言 - 快速參考

Match(String, String, RegexOptions, TimeSpan)

來源:

Regex.Match.cs

使用指定的比對選項和超時時間間隔，搜尋輸入字串中第一個出現的指定正則表達式。

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

參數

input

String

要搜尋相符專案的字串。

pattern

String

要比對的正則表達式模式。

options

RegexOptions

列舉值的位元組合，提供比對的選項。

matchTimeout

TimeSpan

一個逾時區間，或 InfiniteMatchTimeout 表示方法不應逾時。

傳回

Match

物件，包含相符專案的相關信息。

例外狀況

ArgumentException

發生正則表達式剖析錯誤。

ArgumentNullException

input 或 pattern 為 null。

ArgumentOutOfRangeException

options 不是有效的位元組合 RegexOptions 。 -或- matchTimeout 為負性、零或大於約24天。

RegexMatchTimeoutException

發生逾時。

備註

靜態Match(String, String, RegexOptions, TimeSpan)方法等同於用RegexRegex(String, RegexOptions, TimeSpan)建構子建構物件並呼叫實例Match(String)方法。

你可以透過檢查回傳 Match 物件的 Success 屬性來判斷輸入字串中是否找到正則表達式模式。 您可以透過反覆調用返回的 Match 物件的 NextMatch() 方法，來檢索後續匹配項目。

參數 matchTimeout 指定模式匹配方法應該嘗試尋找匹配的時間，直到逾時結束。設定逾時間隔可防止依賴過度回溯的正則表達式在處理包含接近匹配的輸入時似乎停止回應。 若在該時間區內未找到匹配，方法會拋 RegexMatchTimeoutException 出例外。 matchTimeout 覆蓋該方法執行的應用程式域中所定義的任何預設逾時值。

給呼叫者的注意事項

我們建議你將參數設定 matchTimeout 為適當的值，例如兩秒。 如果你指定 InfiniteMatchTimeout，則會讓 停止，正則表達式引擎的效能會稍微好一點。 不過，您應該只在下列情況下停用逾時：

• 正則表達式所處理的輸入衍生自已知且受信任的來源，或包含靜態文字時。 這會排除使用者動態輸入的文字。

• 當正則表達式模式經過徹底測試，以確保其有效率地處理相符專案、不相符專案和接近相符專案時。

• 當正則表達式模式不包含任何已知在處理接近相符專案時造成過度回溯的語言元素。

另請參閱

• 正則表達式語言 - 快速參考