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

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