java.util.regex
類別 Matcher

java.lang.Object
  java.util.regex.Matcher

所有已實作的介面：

MatchResult

public final class Matcher
extends Object
implements MatchResult

通過解釋 Pattern 對 character sequence 執行比對操作的引擎。

通過調用網要的 matcher 方法從網要創建比對器。創建比對器後，可以使用它執行三種不同的比對操作：

• matches 方法嘗試將整個輸入序列與該網要比對。

• lookingAt 嘗試將輸入序列從頭開始與該網要比對。

• find 方法掃瞄輸入序列以尋找與該網要比對的下一個子序列。

每個方法都返回一個表示成功或失敗的布林值。通過查詢比對器的狀態可以獲取關於成功比對的更多資訊。

比對器在其輸入的子集（稱為區域）中尋找比對項。預設情況下，此區域包含全部的比對器輸入。可通過 region 方法修改區域，通過 regionStart 和 regionEnd 方法查詢區域。區域邊界與某些網要建構交互的方式是可以更改的。有關此內容更多的資訊，請參閱 useAnchoringBounds 和 useTransparentBounds。

此類別還定義使用新字元串替換比對子序列的方法，需要時，可以從比對結果計算出新字元串的內容。可以先後使用 appendReplacement 和 appendTail 方法將結果收集到現有的字元串緩衝區，或者使用更加便捷的 replaceAll 方法創建一個可以在其中替換輸入序列中每個比對子序列的字元串。

比對器的顯式狀態包括最近成功比對的開始和結束索引。它還包括網要中每個捕獲組捕獲的輸入子序列的開始和結束索引以及該子序列的總數。出於方便的考慮，還提供了以字元串的形式返回這些已捕獲子序列的方法。

比對器的顯式狀態最初是未定義的；在成功比對導致 IllegalStateException 拋出之前嘗試查詢其中的任何部分。每個比對操作都將重新計算比對器的顯式狀態。

比對器的隱式狀態包括輸入字元序列和添加位置，添加位置最初是零，然後由 appendReplacement 方法更新。

可以通過調用比對器的 reset() 方法來顯式重置比對器，如果需要新輸入序列，則調用其 reset(CharSequence) 方法。重置比對器將放棄其顯式狀態資訊並將添加位置設置為零。

此類別的實例用於多個共時執行緒是不安全的。

從以下版本開始：

1.4

方法摘要

Matcher	appendReplacement(StringBuffer sb, String replacement) 實作非終端添加和替換步驟。
StringBuffer	appendTail(StringBuffer sb) 實作終端添加和替換步驟。
int	end() 返回最後比對字元之後的偏移量。
int	end(int group) 返回在以前的比對操作期間，由給定組所捕獲子序列的最後字元之後的偏移量。
boolean	find() 嘗試尋找與該網要比對的輸入序列的下一個子序列。
boolean	find(int start) 重置此比對器，然後嘗試尋找比對該網要、從指定索引開始的輸入序列的下一個子序列。
String	group() 返回由以前比對操作所比對的輸入子序列。
String	group(int group) 返回在以前比對操作期間由給定組捕獲的輸入子序列。
int	groupCount() 返回此比對器網要中的捕獲組數。
boolean	hasAnchoringBounds() 查詢此比對器區域界限的定位。
boolean	hasTransparentBounds() 查詢此比對器區域邊界的透明度。
boolean	hitEnd() 如果比對器執行的最後比對操作中搜尋引擎遇到輸入結尾，則返回 true。
boolean	lookingAt() 嘗試將從區域開頭開始的輸入序列與該網要比對。
boolean	matches() 嘗試將整個區域與網要比對。
Pattern	pattern() 返回由此比對器解釋的網要。
static String	quoteReplacement(String s) 返回指定 String 的文字值替換 String。
Matcher	region(int start, int end) 設置此比對器的區域限制。
int	regionEnd() 報告此比對器區域的結束索引（不包括）。
int	regionStart() 報告此比對器區域的開始索引。
String	replaceAll(String replacement) 替換網要與給定替換字元串相比對的輸入序列的每個子序列。
String	replaceFirst(String replacement) 替換網要與給定替換字元串比對的輸入序列的第一個子序列。
boolean	requireEnd() 如果很多輸入都可以將正比對更改為負比對，則返回 true。
Matcher	reset() 重置比對器。
Matcher	reset(CharSequence input) 重置此具有新輸入序列的比對器。
int	start() 返回以前比對的初始索引。
int	start(int group) 返回在以前的比對操作期間，由給定組所捕獲的子序列的初始索引。
MatchResult	toMatchResult() 作為 MatchResult 返回此比對器的比對狀態。
String	toString() 返回比對器的字元串表示形式。
Matcher	useAnchoringBounds(boolean b) 設置比對器區域界限的定位。
Matcher	usePattern(Pattern newPattern) 更改此 Matcher 用於尋找比對項的 Pattern。
Matcher	useTransparentBounds(boolean b) 設置此比對器區域邊界的透明度。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

方法詳細資訊

pattern

public Pattern pattern()

返回由此比對器解釋的網要。

返回：

為其創建此比對器的網要。

toMatchResult

public MatchResult toMatchResult()

作為 MatchResult 返回此比對器的比對狀態。該結果不受對此比對器執行的後續操作的影響。

返回：

具有此比對器狀態的 MatchResult。

從以下版本開始：

1.5

usePattern

public Matcher usePattern(Pattern newPattern)

更改此 Matcher 用於尋找比對項的 Pattern。

此方法可導致比對器丟失有關最後發生比對的組的資訊。維持了輸入中比對器的位置並且不影響其最後添加的位置。

參數：

newPattern - 比對器使用的新網要。

返回：

比對器。

拋出：

IllegalArgumentException - 如果 newPattern 為 null。

從以下版本開始：

1.5

reset

public Matcher reset()

重置比對器。

重置比對器將放棄其所有顯式狀態資訊並將其添加位置設置為零。比對器的區域被設置為預設區域，預設區域就是其整個字元序列。此比對器的區域邊界的定位和透明度都不受影響。

返回：

比對器。

reset

public Matcher reset(CharSequence input)

重置此具有新輸入序列的比對器。

重置比對器將放棄其所有顯式狀態資訊並將其添加位置設置為零。比對器的區域被設置為預設區域，預設區域就是其整個字元序列。此比對器的區域邊界的定位和透明度都不受影響。

參數：

input - 新的輸入字元序列。

返回：

比對器。

start

public int start()

返回以前比對的初始索引。

指定者：

介面 MatchResult 中的 start

返回：

第一個比對字元的索引。

拋出：

IllegalStateException - 如果沒有嘗試任何比對，或者以前的比對操作失敗。

start

public int start(int group)

返回在以前的比對操作期間，由給定組所捕獲的子序列的初始索引。

捕獲組是從 1 開始從左到右的索引。組零表示整個網要，因此表達式 m.start(0) 等效於 m.start()。

指定者：

介面 MatchResult 中的 start

參數：

group - 此比對器網要中捕獲組的索引。

返回：

組捕獲的首個字元的索引；如果比對成功但組本身沒有任何比對項，則返回 -1。

拋出：

IllegalStateException - 如果沒有嘗試任何比對，或者以前的比對操作失敗。

IndexOutOfBoundsException - 如果在給定索引的網要中不存在捕獲組。

end

public int end()

返回最後比對字元之後的偏移量。

指定者：

介面 MatchResult 中的 end

返回：

最後比對字元之後的偏移量。

拋出：

IllegalStateException - 如果沒有嘗試任何比對，或者以前的比對操作失敗。

end

public int end(int group)

返回在以前的比對操作期間，由給定組所捕獲子序列的最後字元之後的偏移量。

捕獲組是從 1 開始從左到右的索引。組零表示整個網要，因此表達式 m.end(0) 等效於 m.end()。

指定者：

介面 MatchResult 中的 end

參數：

group - 此比對器網要中捕獲組的索引。

返回：

組捕獲的最後字元之後的偏移量；如果比對成功但組本身沒有任何比對項，則返回 -1。

拋出：

IllegalStateException - 如果沒有嘗試任何比對，或者以前的比對操作失敗。

IndexOutOfBoundsException - 如果在給定索引的網要中不存在捕獲組。

group

public String group()

返回由以前比對操作所比對的輸入子序列。

對於具有輸入序列 s 的比對器 m，表達式 m.group() 和 s.substring(m.start(), m.end()) 是等效的。

注意，某些網要（例如，a*）比對空字元串。當網要成功比對輸入中的空字元串時，此方法將返回空字元串。

指定者：

介面 MatchResult 中的 group

返回：

以前比對操作所比對的字元串形式的子序列（可能為空）。

拋出：

IllegalStateException - 如果沒有嘗試任何比對，或者以前的比對操作失敗。

group

public String group(int group)

返回在以前比對操作期間由給定組捕獲的輸入子序列。

對於比對器 m、輸入序列 s 和組索引 g，表達式 m.group(g) 和 s.substring(m.start(g), m.end(g)) 是等效的。

捕獲組是從 1 開始從左到右的索引。組零表示整個網要，因此表達式 m.group(0) 等效於 m.group()。

如果該比對成功了，但指定組未能比對輸入序列的任何部分，則返回 null。注意，某些組（例如，(a*)）比對空字元串。當這些的組成功比對輸入中的空字元串時，此方法將返回空字元串。

指定者：

介面 MatchResult 中的 group

參數：

group - 此比對器網要中捕獲組的索引。

返回：

在以前的比對期間組所捕獲的子序列（可能為空）；如果組未能比對輸入的部分，則返回 null。

拋出：

IllegalStateException - 如果沒有嘗試任何比對，或者以前的比對操作失敗。

IndexOutOfBoundsException - 如果在給定索引的網要中不存在捕獲組。

groupCount

public int groupCount()

返回此比對器網要中的捕獲組數。

根據慣例，零組表示整個網要。它不包括在此計數中。

任何小於等於此方法返回值的非負整數保證是此比對器的有效組索引。

指定者：

介面 MatchResult 中的 groupCount

返回：

此比對器網要中的捕獲組數。

matches

public boolean matches()

嘗試將整個區域與網要比對。

如果比對成功，則可以通過 start、end 和 group 方法獲取更多資訊。

返回：

當且僅當整個區域序列比對此比對器的網要時才返回 true。

find

public boolean find()

嘗試尋找與該網要比對的輸入序列的下一個子序列。

此方法從比對器區域的開頭開始，如果該方法的前一次調用成功了並且從那時開始比對器沒有被重置，則從以前比對操作沒有比對的第一個字元開始。

如果比對成功，則可以通過 start、end 和 group 方法獲取更多資訊。

返回：

當且僅當輸入序列的子序列比對此比對器的網要時才返回 true。

find

public boolean find(int start)

重置此比對器，然後嘗試尋找比對該網要、從指定索引開始的輸入序列的下一個子序列。

如果比對成功，則可通過 start、end 和 group 方法獲取更多資訊，而 find() 方法的後續調用將從此比對操作未比對的第一個字元開始。

返回：

當且僅當從給定索引開始的輸入序列的子序列比對此比對器的網要時才返回 true。

拋出：

IndexOutOfBoundsException - 如果開始點小於零或大於輸入序列的長度。

lookingAt

public boolean lookingAt()

嘗試將從區域開頭開始的輸入序列與該網要比對。

與 matches 方法類似，此方法始終從區域的開頭開始；與之不同的是，它不需要比對整個區域。

如果比對成功，則可以通過 start、end 和 group 方法獲取更多資訊。

返回：

當且僅當輸入序列的前綴比對此比對器的網要時才返回 true。

quoteReplacement

public static String quoteReplacement(String s)

返回指定 String 的文字值替換 String。 此方法將產生一個 String，它將用作 Matcher 類別的 appendReplacement 方法中的文字值替換 s。所產生的 String 將與作為文字值序列的 s 中的字元序列比對。斜線 ('\') 和美元符號 ('$') 將不具有任何特殊意義。

參數：

s - 要文字值化的字元串。

返回：

文字值字元串替換。

從以下版本開始：

1.5

appendReplacement

public Matcher appendReplacement(StringBuffer sb,
                                 String replacement)

實作非終端添加和替換步驟。

此方法執行以下操作：

1. 它從添加位置開始在輸入序列讀取字元，並將其添加到給定字元串緩衝區。在讀取以前比對之前的最後字元（即位於索引 start() - 1 處的字元）之後，它就會停止。

2. 它將給定替換字元串添加到字元串緩衝區。

3. 它將此比對器的添加位置設置為最後比對位置的索引加 1，即 end()。

替換字元串可能包含到以前比對期間所捕獲的子序列的參考：$g 每次出現時，都將被 group(g) 的計算結果替換。$ 之後的第一個數始終被視為組參考的一部分。如果後續的數可以形成合法組參考，則將被合併到 g 中。只有數字 '0' 到 '9' 被視為組參考的可能元件。例如，如果第二個組比對字元串 "foo"，則傳遞替換字元串 "$2bar" 將導致 "foobar" 被添加到字元串緩衝區。可能將美元符號 ($) 作為替換字元串中的文字值（通過前面使用一個反斜線 (\$)）包括進來。

注意，在替換字元串中使用反斜線 (\) 和美元符號 ($) 可能導致與作為文字值替換字元串時所產生的結果不同。美元符號可視為到如上所述已捕獲子序列的參考，反斜線可用於轉義替換字元串中的文字值字元。

此方法設計用於循環以及 appendTail 和 find 方法中。例如，以下程式碼將 one dog two dogs in the yard 寫入標準輸出串流中：

 Pattern p = Pattern.compile("cat");
 Matcher m = p.matcher("one cat two cats in the yard");
 StringBuffer sb = new StringBuffer();
 while (m.find()) {
     m.appendReplacement(sb, "dog");
 }
 m.appendTail(sb);
 System.out.println(sb.toString());

參數：

sb - 目標字元串緩衝區。

replacement - 替換字元串。

返回：

比對器。

拋出：

IllegalStateException - 如果沒有嘗試任何比對，或者以前的比對操作失敗。

IndexOutOfBoundsException - 如果替換字元串參考網要中不存在的捕獲組。

appendTail

public StringBuffer appendTail(StringBuffer sb)

實作終端添加和替換步驟。

此方法從添加位置開始從輸入序列讀取字元，並將其添加到給定字元串緩衝區。可以在一次或多次調用 appendReplacement 方法後調用它來複製剩餘的輸入序列。

參數：

sb - 目標字元串緩衝區。

返回：

目標字元串緩衝區。

replaceAll

public String replaceAll(String replacement)

替換網要與給定替換字元串相比對的輸入序列的每個子序列。

此方法首先重置比對器。然後，它將掃瞄輸入序列以尋找該網要的比對項。不屬於任何比對的字元被直接添加到結果字元串；在結果中每個比對都將被替換字元串所替換。替換字元串可能包含到已捕獲子序列的參考，如在 appendReplacement 方法中一樣。

注意，在替換字元串中使用反斜線 (\) 和美元符號 ($) 可能導致與作為文字值替換字元串時所產生的結果不同。美元符號可視為到如上所述已捕獲子序列的參考，反斜線可用於轉義替換字元串中的文字值字元。

在給定正則表達式 a*b、輸入 "aabfooaabfooabfoob" 和替換字元串 "-" 的情況下，為該表達式針對比對器調用此方法將產生字元串 "-foo-foo-foo-"。

調用此方法將更改此比對器的狀態。如果在將來的比對操作中使用該比對器，則應該首先重置它。

參數：

replacement - 替換字元串。

返回：

通過使用替換字元串替換每個比對子序列，並在需要時取代已捕獲子序列所建構的字元串。

replaceFirst

public String replaceFirst(String replacement)

替換網要與給定替換字元串比對的輸入序列的第一個子序列。

此方法首先重置比對器。然後，它將掃瞄輸入序列以尋找該網要的比對項。不是比對一部分的字元被直接添加到結果字元串；在結果中比對內容將被替換字元串替換。替換字元串可能包含到已捕獲子序列的參考，如在 appendReplacement 方法中一樣。

注意，在替換字元串中使用反斜線 (\) 和美元符號 ($) 可能導致與作為文字值替換字元串時所產生的結果不同。美元符號可視為到如上所述已捕獲子序列的參考，反斜線可用於轉義替換字元串中的文字值字元。

在給定正則表達式 dog、輸入 "zzzdogzzzdogzzz" 和替換字元串 "cat" 的情況下，為該表達式針對比對器調用此方法將產生字元串 "zzzcatzzzdogzzz"。

調用此方法將更改此比對器的狀態。如果在將來的比對操作中使用該比對器，則應該首先重置它。

參數：

replacement - 替換字元串。

返回：

通過使用替換字元串替換第一個比對子序列，並在需要時取代已捕獲子序列所建構的字元串。

region

public Matcher region(int start,
                      int end)

設置此比對器的區域限制。區域是輸入序列的一部分，搜尋它可以尋找比對。調用此方法會重置比對器，然後設置區域，使其從 start 參數指定的索引開始，到 end 參數指定的索引結束。

某些建構（如定位點）可能因所用的透明度和定位不同（參見 useTransparentBounds 和 useAnchoringBounds），從而在區域的邊界上或邊界四周的行為也有所不同。

參數：

start - 索引，從此索引（包括在內）開始搜尋。

end - 到此（包括在內）結束搜尋的索引。

返回：

比對器。

拋出：

IndexOutOfBoundsException - 如果開始點或結束點小於零，並且開始點的長度大於輸入序列的長度，結束點的長度大於輸入序列的長度，或者開始點大於結束點。

從以下版本開始：

1.5

regionStart

public int regionStart()

報告此比對器區域的開始索引。此比對器所進行的搜尋被限制在 regionStart（包括）和 regionEnd（不包括）中尋找比對。

返回：

比對器區域的開始點。

從以下版本開始：

1.5

regionEnd

public int regionEnd()

報告此比對器區域的結束索引（不包括）。此比對器所進行的搜尋被限制在 regionStart（包括）和 regionEnd（不包括）中尋找比對。

返回：

比對器區域的結束點。

從以下版本開始：

1.5

hasTransparentBounds

public boolean hasTransparentBounds()

查詢此比對器區域邊界的透明度。

如果此比對器使用透明 邊界，則此方法返回 true；如果使用不透明 邊界，則返回 false。

有關透明和不透明邊界的描述，請參閱 useTransparentBounds。

預設情況下，比對器使用不透明區域邊界。

返回：

當且僅當此比對器使用透明邊界時才返回 true；否則返回 false。

從以下版本開始：

1.5

另請參見：

useTransparentBounds(boolean)

useTransparentBounds

public Matcher useTransparentBounds(boolean b)

設置此比對器區域邊界的透明度。

利用參數 true 調用此方法將設置此比對器使用透明 邊界。如果布林參數為 false，則使用不透明 邊界。

使用透明邊界，此比對器區域的邊界對 lookahead、lookbehind 和邊界比對建構都是透明的。可以使用這些建構查看區域邊界的外部，以瞭解比對是否正確。

使用不透明邊界，此比對器區域的邊界對 lookahead、lookbehind 和試圖查看其外部的邊界比對建構都是不透明的。這些建構無法穿過邊界查看，因此不能使用它們比對區域之外的任何內容。

預設情況下，比對器使用不透明邊界。

參數：

b - 指示使用不透明還是透明區域的布林值。

返回：

比對器。

從以下版本開始：

1.5

另請參見：

hasTransparentBounds()

hasAnchoringBounds

public boolean hasAnchoringBounds()

查詢此比對器區域界限的定位。

如果此比對器使用定位 界限，則此方法返回 true；否則返回 false。

有關獲取定位界限的描述，請參閱 useAnchoringBounds。

預設情況下，比對器使用定位區域邊界。

返回：

當且僅當此比對器使用定位界限時才返回 true；否則返回 false。

從以下版本開始：

1.5

另請參見：

useAnchoringBounds(boolean)

useAnchoringBounds

public Matcher useAnchoringBounds(boolean b)

設置比對器區域界限的定位。

利用參數 true 調用此方法將設置此比對器使用定位 界限。如果布林參數為 false，則使用非定位 界限。

使用定位界限，此比對器區域的邊界與定位點（如 ^ 和 $）比對。

不使用定位界限，此比對器區域的邊界將與定位點（如 ^ 和 $）不比對。

預設情況下，比對器使用定位區域邊界。

參數：

b - 指示是否使用定位界限的布林值。

返回：

比對器。

從以下版本開始：

1.5

另請參見：

hasAnchoringBounds()

toString

public String toString()

返回比對器的字元串表示形式。包含可用於除錯的資訊的 Matcher 字元串表示形式。未指定確切格式。

覆寫：

類別 Object 中的 toString

返回：

比對器的字元串表示形式。

從以下版本開始：

1.5

hitEnd

public boolean hitEnd()

如果比對器執行的最後比對操作中搜尋引擎遇到輸入結尾，則返回 true。

此方法返回 true 時，很多輸入都可能更改最後搜尋的結果。

返回：

當且僅當在最後比對中遇到輸入結尾時才返回 true；否則返回 false。

從以下版本開始：

1.5

requireEnd

public boolean requireEnd()

如果很多輸入都可以將正比對更改為負比對，則返回 true。

如果此方法返回 true，並且找到了比對，則很多輸入可能導致比對丟失。如果此方法返回 false，並且找到了比對，則很多輸入可能更改比對，但是比對不會丟失。如果未找到比對，則 requireEnd 沒有意義。

返回：

當且僅當很多輸入都可以將正比對更改為負比對時才返回 true。

從以下版本開始：

1.5