Java java.util.regex 类 Matcher（JDK5）

所有类

java.util.regex
类 Matcher

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

所有已实现的接口：

MatchResult

public final class Matcher
   
   
   
   
   
extends Object
   
   
   
   
   
   
   
   
   
   
implements MatchResult
   
   
   
   
   

通过解释 Pattern 对 字符序列 执行匹配操作的引擎。

通过调用模式的 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。

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 - 如果在给定索引的模式中不存在捕获组。