Regex.Match 方法

參考

定義

命名空間:: System.Text.RegularExpressions

組件:: System.Text.RegularExpressions.dll

組件:: System.dll

組件:: netstandard.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

搜尋輸入字串中符合正則表達式模式的子字串，並以單一 Match 對象傳回第一個出現專案。

多載

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

來源:: 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

發生逾時。如需逾時的詳細資訊，請參閱一節。

範例

下列範例會在字串中尋找正則表示式模式相符專案，然後列出相符的群組、擷取和擷取位置。

#using <System.dll>

using namespace System;
using namespace System::Text::RegularExpressions;
void main()
{
   
   String^ text = "One car red car blue car";
   String^ pat = "(\\w+)\\s+(car)";
   
   // Compile the regular expression.
   Regex^ r = gcnew Regex( pat,RegexOptions::IgnoreCase );
   
   // Match the regular expression pattern against a text string.
   Match^ m = r->Match(text);
   int matchCount = 0;
   while ( m->Success )
   {
      Console::WriteLine( "Match{0}", ++matchCount );
      for ( int i = 1; i <= 2; i++ )
      {
         Group^ g = m->Groups[ i ];
         Console::WriteLine( "Group{0}='{1}'", i, g );
         CaptureCollection^ cc = g->Captures;
         for ( int j = 0; j < cc->Count; j++ )
         {
            Capture^ c = cc[ j ];
            System::Console::WriteLine( "Capture{0}='{1}', Position={2}", j, c, c->Index );
         }
      }
      m = m->NextMatch();
   }
}  
// This example displays the following output:
//       Match1
//       Group1='One'
//       Capture0='One', Position=0
//       Group2='car'
//       Capture0='car', Position=4
//       Match2
//       Group1='red'
//       Capture0='red', Position=8
//       Group2='car'
//       Capture0='car', Position=12
//       Match3
//       Group1='blue'
//       Capture0='blue', Position=16
//       Group2='car'
//       Capture0='car', Position=21

using System;
using System.Text.RegularExpressions;

class Example
{
   static void Main()
   {
      string text = "One car red car blue car";
      string pat = @"(\w+)\s+(car)";

      // Instantiate the regular expression object.
      Regex r = new Regex(pat, RegexOptions.IgnoreCase);

      // Match the regular expression pattern against a text string.
      Match m = r.Match(text);
      int matchCount = 0;
      while (m.Success)
      {
         Console.WriteLine("Match"+ (++matchCount));
         for (int i = 1; i <= 2; i++)
         {
            Group g = m.Groups[i];
            Console.WriteLine("Group"+i+"='" + g + "'");
            CaptureCollection cc = g.Captures;
            for (int j = 0; j < cc.Count; j++)
            {
               Capture c = cc[j];
               System.Console.WriteLine("Capture"+j+"='" + c + "', Position="+c.Index);
            }
         }
         m = m.NextMatch();
      }
   }
}
// This example displays the following output:
//       Match1
//       Group1='One'
//       Capture0='One', Position=0
//       Group2='car'
//       Capture0='car', Position=4
//       Match2
//       Group1='red'
//       Capture0='red', Position=8
//       Group2='car'
//       Capture0='car', Position=12
//       Match3
//       Group1='blue'
//       Capture0='blue', Position=16
//       Group2='car'
//       Capture0='car', Position=21

Imports System.Text.RegularExpressions

Module Example
   Public Sub Main()
      Dim text As String = "One car red car blue car"
      Dim pattern As String = "(\w+)\s+(car)"

      ' Instantiate the regular expression object.
      Dim r As Regex = new Regex(pattern, RegexOptions.IgnoreCase)

      ' Match the regular expression pattern against a text string.
      Dim m As Match = r.Match(text)
      Dim matchcount as Integer = 0
      Do While m.Success
         matchCount += 1
         Console.WriteLine("Match" & (matchCount))
         Dim i As Integer
         For i = 1 to 2
            Dim g as Group = m.Groups(i)
            Console.WriteLine("Group" & i & "='" & g.ToString() & "'")
            Dim cc As CaptureCollection = g.Captures
            Dim j As Integer 
            For j = 0 to cc.Count - 1
              Dim c As Capture = cc(j)
               Console.WriteLine("Capture" & j & "='" & c.ToString() _
                  & "', Position=" & c.Index)
            Next 
         Next 
         m = m.NextMatch()
      Loop
   End Sub
End Module
' This example displays the following output:
'       Match1
'       Group1='One'
'       Capture0='One', Position=0
'       Group2='car'
'       Capture0='car', Position=4
'       Match2
'       Group1='red'
'       Capture0='red', Position=8
'       Group2='car'
'       Capture0='car', Position=12
'       Match3
'       Group1='blue'
'       Capture0='blue', Position=16
'       Group2='car'
'       Capture0='car', Position=21

正則表達式模式 (\w+)\s+(car) 會比對「car」一詞的出現次數，以及前面出現的字組。其解譯如下表所示。

模式	描述
`(\w+)`	比對一或多個單字字元。這是第一個擷取群組。
`\s+`	比對一或多個空格符。
（車）	比對常值字串「car」。這是第二個擷取群組。

備註

Match(String) 方法會傳回符合輸入字串中正則表達式模式的第一個子字串。如需用來建置正規表示式模式之語言項目的相關信息，請參閱正規表示式語言 - 快速參考。

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

此方法會傳回 input 中符合正則表示式模式的第一個子字串。您可以重複呼叫傳回 Match 物件的 Match.NextMatch 方法，以擷取後續相符專案。您也可以呼叫 Regex.Matches(String) 方法，以擷取單一方法呼叫中的所有相符專案。

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

另請參閱

適用於

Match(String, Int32)

來源:: Regex.Match.cs

來源:: Regex.Match.cs

來源:: 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

發生逾時。如需逾時的詳細資訊，請參閱一節。

備註

如需此 API 的詳細資訊，請參閱 Regex.Match的補充 API 備註。

另請參閱

適用於

Match(String, String)

來源:: Regex.Match.cs

來源:: Regex.Match.cs

來源:: 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 或 patternnull。

RegexMatchTimeoutException

發生逾時。如需逾時的詳細資訊，請參閱一節。

範例

下列範例會呼叫 Match(String, String) 方法來尋找包含至少一個 z 字元的第一個單字，然後呼叫 Match.NextMatch 方法來尋找任何其他相符專案。

using System;
using System.Text.RegularExpressions;

namespace Examples
{
    public class Example
    {
        public static void Main()
        {
            string input = "ablaze beagle choral dozen elementary fanatic " +
                           "glaze hunger inept jazz kitchen lemon minus " +
                           "night optical pizza quiz restoration stamina " +
                           "train unrest vertical whiz xray yellow zealous";
            string pattern = @"\b\w*z+\w*\b";
            Match m = Regex.Match(input, pattern);
            while (m.Success)
            {
                Console.WriteLine("'{0}' found at position {1}", m.Value, m.Index);
                m = m.NextMatch();
            }
        }
    }
}

// The example displays the following output:
//    'ablaze' found at position 0
//    'dozen' found at position 21
//    'glaze' found at position 46
//    'jazz' found at position 65
//    'pizza' found at position 104
//    'quiz' found at position 110
//    'whiz' found at position 157
//    'zealous' found at position 174

Imports System.Text.RegularExpressions

Module Example
   Public Sub Main()
      Dim input As String = "ablaze beagle choral dozen elementary fanatic " +
                            "glaze hunger inept jazz kitchen lemon minus " +
                            "night optical pizza quiz restoration stamina " +
                            "train unrest vertical whiz xray yellow zealous"
      Dim pattern As String = "\b\w*z+\w*\b"
      Dim m As Match = Regex.Match(input, pattern)
      Do While m.Success 
         Console.WriteLine("'{0}' found at position {1}", m.Value, m.Index)
         m = m.NextMatch()
      Loop                      
   End Sub
End Module
' The example displays the following output:
    'ablaze' found at position 0
    'dozen' found at position 21
    'glaze' found at position 46
    'jazz' found at position 65
    'pizza' found at position 104
    'quiz' found at position 110
    'whiz' found at position 157
    'zealous' found at position 174

正則表達式模式 \b\w*z+\w*\b 會解譯如下表所示。

模式	描述
`\b`	在字邊界開始比對。
`\w*`	比對零、一或多個單字字元。
`z+`	比對 `z` 字元的一或多個專案。
`\w*`	比對零、一或多個單字字元。
`\b`	在字邊界結束比對。

備註

Match(String, String) 方法會傳回符合輸入字串中正則表達式模式的第一個子字串。如需用來建置正規表示式模式之語言項目的相關信息，請參閱正規表示式語言 - 快速參考。

靜態 Match(String, String) 方法相當於使用指定的正則表示式模式建構 Regex 物件，並呼叫實例 Match(String) 方法。在此情況下，正則表達式引擎會快取正則表示式模式。

pattern 參數是由正則表達式語言專案所組成，這些元素會以符號方式描述要比對的字串。如需正規表示式的詳細資訊，請參閱 .NET 正則表示式和正則表示式語言 - 快速參考。

此方法會傳回 input 中符合正則表示式模式的第一個子字串。您可以重複呼叫傳回 Match 物件的 Match.NextMatch 方法，以擷取後續相符專案。您也可以呼叫 Regex.Matches(String, String) 方法，以擷取單一方法呼叫中的所有相符專案。

如果比對作業的運行時間超過呼叫方法的應用程式域所指定的超時時間間隔，就會擲回 RegexMatchTimeoutException 例外狀況。如果在應用程式域的屬性中未定義逾時，或逾時值 Regex.InfiniteMatchTimeout，則不會擲回任何例外狀況。

給呼叫者的注意事項

這個方法會在間隔後逾時，這個間隔等於呼叫它之應用程式域的預設逾時值。如果尚未為應用程式域定義逾時值，則會使用 InfiniteMatchTimeout值，以防止方法逾時。擷取模式比對的建議靜態方法是 Match(String, String)，這可讓您設定超時時間間隔。

另請參閱

適用於

Match(String, Int32, Int32)

來源:: Regex.Match.cs

來源:: Regex.Match.cs

來源:: 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) 方法會傳回第一個子字串，該子字串符合輸入字串的一部分中的正則表達式模式。如需用來建置正規表示式模式之語言項目的相關信息，請參閱正規表示式語言 - 快速參考。

Match(String, Int32, Int32) 方法搜尋的正規表達式模式是由其中一個 Regex 類別建構函式的呼叫所定義。如需可形成正規表示式模式的項目詳細資訊，請參閱正則表示式語言 - 快速參考。

Match(String, Int32, Int32) 方法會搜尋正規表示式模式 beginning 和 length 參數所定義的 input 部分。 beginning 一律會定義要包含在搜尋中最左邊字元的索引，length 定義要搜尋的字元數上限。它們會一起定義搜尋的範圍。行為與 input 實際上是 input.Substring(beginning, length)一樣，不同之處在於，任何相符專案的索引都會相對於 input的開頭計算。這表示模式開頭或結尾的任何錨點或零寬度判斷提示的行為，就好像在這個範圍之外沒有 input 一樣。例如，錨點 ^、\G和 \A 會在 beginning 滿足，$ 和 \z 會在 beginning + length - 1滿足。

如果搜尋從左至右（預設值），正則表示式引擎會從索引處的字元搜尋 beginning 索引處的字元，beginning + length - 1。如果使用 [RegexOptions.RightToLeft] 選項具現化正則表示式引擎，讓搜尋從右至左進行，則正則表達式引擎會從索引處的字元搜尋 beginning + length - 1 索引處的字元 beginning。

這個方法會傳回它在此範圍內找到的第一個相符專案。您可以重複呼叫傳回 Match 物件的 Match.NextMatch 方法，以擷取後續相符專案。

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

另請參閱

適用於

Match(String, String, RegexOptions)

來源:: Regex.Match.cs

來源:: Regex.Match.cs

來源:: 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 或 patternnull。

ArgumentOutOfRangeException

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

RegexMatchTimeoutException

發生逾時。如需逾時的詳細資訊，請參閱一節。

範例

下列範例會定義正則表達式，以字母「a」開頭的字組相符。它會使用 RegexOptions.IgnoreCase 選項來確保正則表達式會找出開頭為大寫 “a” 和小寫 “a” 的字組。

using System;
using System.Text.RegularExpressions;

namespace Examples
{
    public class Example2
    {
        public static void Main()
        {
            string pattern = @"\ba\w*\b";
            string input = "An extraordinary day dawns with each new day.";
            Match m = Regex.Match(input, pattern, RegexOptions.IgnoreCase);
            if (m.Success)
                Console.WriteLine("Found '{0}' at position {1}.", m.Value, m.Index);
        }
    }
}

// The example displays the following output:
//        Found 'An' at position 0.

Imports System.Text.RegularExpressions

Module Example
   Public Sub Main()
      Dim pattern As String = "\ba\w*\b"
      Dim input As String = "An extraordinary day dawns with each new day."
      Dim m As Match = Regex.Match(input, pattern, RegexOptions.IgnoreCase)
      If m.Success Then
         Console.WriteLine("Found '{0}' at position {1}.", m.Value, m.Index)
      End If
   End Sub
End Module
' The example displays the following output:
'       Found 'An' at position 0.

正則表達式模式 \ba\w*\b 會解譯如下表所示。

模式	描述
`\b`	在字邊界開始比對。
`a`	比對字元「a」。
`\w*`	比對零、一或多個單字字元。
`\b`	在字邊界結束比對。

備註

Match(String, String, RegexOptions) 方法會傳回符合輸入字串中正則表達式模式的第一個子字串。如需用來建置正規表示式模式之語言項目的相關信息，請參閱正規表示式語言 - 快速參考。

靜態 Match(String, String, RegexOptions) 方法相當於使用 Regex(String, RegexOptions) 建構函式建構 Regex 物件，並呼叫實例 Match(String) 方法。

這個方法會傳回符合正則表達式模式之 input 中找到的第一個子字串。您可以重複呼叫傳回 Match 物件的 NextMatch 方法，以擷取後續相符專案。您也可以呼叫 Regex.Matches(String, String, RegexOptions) 方法，以擷取單一方法呼叫中的所有相符專案。

給呼叫者的注意事項

另請參閱

適用於

Match(String, String, RegexOptions, TimeSpan)

來源:: Regex.Match.cs

來源:: Regex.Match.cs

來源:: 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 或 patternnull。

ArgumentOutOfRangeException

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

-或-

matchTimeout 為負數、零或大於大約 24 天。

RegexMatchTimeoutException

發生逾時。如需逾時的詳細資訊，請參閱一節。

備註

Match(String, String, RegexOptions, TimeSpan) 方法會傳回符合輸入字串中正則表達式模式的第一個子字串。如需用來建置正規表示式模式之語言項目的相關信息，請參閱正規表示式語言 - 快速參考。

靜態 Match(String, String, RegexOptions, TimeSpan) 方法相當於使用 Regex(String, RegexOptions, TimeSpan) 建構函式建構 Regex 物件，並呼叫實例 Match(String) 方法。

matchTimeout 參數會指定模式比對方法在逾時之前應該嘗試尋找相符項目的時間長度。設定超時時間間隔可防止依賴過度回溯的正則表達式在處理包含接近相符項目的輸入時停止回應。如需詳細資訊，請參閱正則表示式的最佳做法和回溯。如果該時間間隔中找不到相符專案，此方法會擲回 RegexMatchTimeoutException 例外狀況。 matchTimeout 會覆寫針對方法執行的應用程式域所定義的任何預設逾時值。

給呼叫者的注意事項

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

正則表達式所處理的輸入衍生自已知且受信任的來源，或包含靜態文字時。這會排除使用者動態輸入的文字。
當正則表達式模式經過徹底測試，以確保其有效率地處理相符專案、不相符專案和接近相符專案時。
當正則表達式模式不包含任何已知在處理接近相符專案時造成過度回溯的語言元素。

另請參閱

正則表示式語言 - 快速參考

適用於

共用方式為

Regex.Match 方法

定義

多載

Match(String)

參數

傳回

例外狀況

範例

備註

另請參閱

適用於

Match(String, Int32)

參數

傳回

例外狀況

備註

另請參閱

適用於

Match(String, String)

參數

傳回

例外狀況

範例

備註

給呼叫者的注意事項

另請參閱

適用於

Match(String, Int32, Int32)

參數

傳回

例外狀況

備註

另請參閱

適用於

Match(String, String, RegexOptions)

參數

傳回

例外狀況

範例

備註

給呼叫者的注意事項

另請參閱

適用於

Match(String, String, RegexOptions, TimeSpan)

參數

傳回

例外狀況

備註

給呼叫者的注意事項

另請參閱

適用於

其他資源