Most visited

Recently visited

Added in API level 1

Matcher

public final class Matcher
extends Object implements MatchResult

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


通过解释 Pattern character sequence上执行匹配操作的引擎。

通过调用模式的matcher方法从模式创建匹配器。 一旦创建,匹配器就可以用来执行三种不同类型的匹配操作:

这些方法中的每一个都会返回一个表示成功或失败的布尔值 通过查询匹配器的状态可以获得关于成功匹配的更多信息。

匹配器在称为区域的输入子集中找到匹配项。 默认情况下,该区域包含所有匹配器的输入。 该区域可以通过region方法进行修改,并通过regionStartregionEnd方法进行查询。 区域边界与一些模式构造交互的方式可以改变。 有关更多详细信息,请参阅useAnchoringBoundsuseTransparentBounds

该类还定义了用新字符串替换匹配子序列的方法,如果需要,可以根据匹配结果计算其内容。 appendReplacementappendTail方法可以串联使用,以便收集的结果到一个现有的字符串缓冲区,或更方便的replaceAll方法可用于创建在该输入序列中的每一个匹配的子序列被替换的字符串。

匹配器的显式状态包括最近成功匹配的开始和结束索引。 它还包括模式中每个capturing group捕获的输入子序列的开始和结束索引以及这些子序列的总数。 为了方便起见,还提供了以字符串形式返回这些捕获的子序列的方法。

匹配器的显式状态最初是未定义的; 试图在成功匹配之前查询它的任何部分将导致IllegalStateException被抛出。 每个匹配操作都会重新计算匹配器的显式状态。

匹配器的隐式状态包括输入字符序列以及 附加位置 ,该 位置最初为零,并且由 appendReplacement方法进行更新。

甲匹配器可以明确地通过调用其复位reset()方法,或者,如果一个新的输入序列是期望的,其reset(CharSequence)方法。 重置匹配器会丢弃其明确的状态信息,并将追加位置设置为零。

这个类的实例对于多个并发线程不安全。

Summary

Public methods

Matcher appendReplacement(StringBuffer sb, String replacement)

实现非终端追加和替换步骤。

StringBuffer appendTail(StringBuffer sb)

实现终端附加和替换步骤。

int end(int group)

返回前一次匹配操作期间给定组捕获的子序列的最后一个字符后的偏移量。

int end()

返回匹配的最后一个字符后的偏移量。

boolean find()

尝试查找与模式匹配的输入序列的下一个子序列。

boolean find(int start)

重置此匹配器,然后尝试从指定索引处开始查找与模式匹配的输入序列的下一个子序列。

String group(int group)

返回上一次匹配操作期间给定组所捕获的输入子序列。

String 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(CharSequence input)

用新的输入序列重新设置匹配器。

Matcher reset()

重置此匹配器。

int start()

返回上一场比赛的开始索引。

int start(int group)

返回上一次匹配操作期间给定组捕获的子序列的开始索引。

MatchResult toMatchResult()

MatchResult返回此匹配器的匹配状态。

String toString()

返回此匹配器的字符串表示形式。

Matcher useAnchoringBounds(boolean value)

设置此匹配器的区域边界的锚定。

Matcher usePattern(Pattern newPattern)

更改 Pattern,Matcher用于查找与匹配。

Matcher useTransparentBounds(boolean value)

设置此匹配器的区域边界的透明度。

Inherited methods

From class java.lang.Object
From interface java.util.regex.MatchResult

Public methods

appendReplacement

Added in API level 1
Matcher appendReplacement (StringBuffer sb, 
                String replacement)

实现非终端追加和替换步骤。

该方法执行以下操作:

  1. 它从输入序列中读取字符,从append位置开始,并将它们附加到给定的字符串缓冲区。 它在读取前一匹配之前的最后一个字符后停止,即索引为start() - 1的字符。

  2. 它将给定的替换字符串附加到字符串缓冲区。

  3. 它将匹配器的追加位置设置为匹配的最后一个字符的索引,再加上一个,即 end()

替换字符串可能包含对前一次匹配过程中捕获的子序列的引用:每次出现$ g将被替换为分别评估相应的group(g)的结果。 对于$克 $后的第一个数字始终被视为该组参考的一部分。 随后的数字会被合并到g中,如果它们会形成合法的组参考。 只有数字“0”到“9”被认为是组参考的潜在组成部分。 例如,如果第二组匹配字符串"foo" ,则传递替换字符串"$2bar"将导致"foobar"追加到字符串缓冲区。 美元符号( $ )可能作为文字包含在替换字符串中,前面带有反斜杠( \$ )。

请注意替换字符串中的反斜杠( \ )和美元符号( $ )可能会导致结果与将它视为字面替换字符串时的结果不同。 如上所述,美元符号可以视为对捕获的子序列的引用,而反斜杠用于转义替换字符串中的文字字符。

此方法旨在与appendTailfind方法一起用于循环中。 例如,以下代码将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());

Parameters
sb StringBuffer: The target string buffer
replacement String: The replacement string
Returns
Matcher This matcher
Throws
IllegalStateException If no match has yet been attempted, or if the previous match operation failed
IllegalArgumentException If the replacement string refers to a named-capturing group that does not exist in the pattern
IndexOutOfBoundsException If the replacement string refers to a capturing group that does not exist in the pattern

appendTail

Added in API level 1
StringBuffer appendTail (StringBuffer sb)

实现终端附加和替换步骤。

此方法从输入序列中读取字符,从append位置开始,并将它们附加到给定的字符串缓冲区。 它旨在调用appendReplacement方法的一个或多个调用以复制输入序列的其余部分。

Parameters
sb StringBuffer: The target string buffer
Returns
StringBuffer The target string buffer

end

Added in API level 1
int end (int group)

返回前一次匹配操作期间给定组捕获的子序列的最后一个字符后的偏移量。

Capturing groups从左到右索引,从1开始。 零组表示整个模式,所以表达式m。 end(0)等于m。 end()

Parameters
group int: The index of a capturing group in this matcher's pattern
Returns
int The offset after the last character captured by the group, or -1 if the match was successful but the group itself did not match anything
Throws
IllegalStateException If no match has yet been attempted, or if the previous match operation failed
IndexOutOfBoundsException If there is no capturing group in the pattern with the given index

end

Added in API level 1
int end ()

Returns the offset after the last character matched.

Returns
int The offset after the last character matched
Throws
IllegalStateException If no match has yet been attempted, or if the previous match operation failed

find

Added in API level 1
boolean find ()

尝试查找与模式匹配的输入序列的下一个子序列。

该方法从该匹配器的区域的开始处开始,或者如果之前的方法调用成功并且匹配器尚未被重置,则在与先前的匹配不匹配的第一个字符处开始。

如果匹配成功可以通过 start,end,group方法来获得,然后更多的信息。

Returns
boolean true if, and only if, a subsequence of the input sequence matches this matcher's pattern

find

Added in API level 1
boolean find (int start)

重置此匹配器,然后尝试从指定索引处开始查找与模式匹配的输入序列的下一个子序列。

如果匹配成功可以通过 start,end,group方法,以及随后的调用能够得到那么更多的信息 find()方法将在不受此匹配匹配的第一个字符开始。

Parameters
start int
Returns
boolean true if, and only if, a subsequence of the input sequence starting at the given index matches this matcher's pattern
Throws
IndexOutOfBoundsException If start is less than zero or if start is greater than the length of the input sequence.

group

Added in API level 1
String group (int group)

返回上一次匹配操作期间给定组所捕获的输入子序列。

对于匹配器m ,输入序列s和组索引g ,表达式m。 group( g )s。 substring(米 start( g ), m。 end( g ))是等效的。

Capturing groups从左到右索引,从1开始。 零组表示整个模式,因此表达式m.group(0)等同于m.group()

如果匹配成功但指定的组未能匹配输入序列的任何部分,则返回null 请注意,某些组(例如(a*) )与空字符串匹配。 当这个组成功匹配输入中的空字符串时,此方法将返回空字符串。

Parameters
group int: The index of a capturing group in this matcher's pattern
Returns
String The (possibly empty) subsequence captured by the group during the previous match, or null if the group failed to match part of the input
Throws
IllegalStateException If no match has yet been attempted, or if the previous match operation failed
IndexOutOfBoundsException If there is no capturing group in the pattern with the given index

group

Added in API level 1
String group ()

返回前一次匹配所匹配的输入子序列。

对于具有输入序列s的匹配器m ,表达式m。 group()s。 substring( 米。 start(), m。 end())是等同的。

请注意,某些模式(例如a* )与空字符串匹配。 当模式成功匹配输入中的空字符串时,此方法将返回空字符串。

Returns
String The (possibly empty) subsequence matched by the previous match, in string form
Throws
IllegalStateException If no match has yet been attempted, or if the previous match operation failed

groupCount

Added in API level 1
int groupCount ()

返回此匹配器模式中的捕获组的数量。

零组表示按照惯例的整个模式。 这不包括在这个计数中。

任何小于或等于此方法返回的值的非负整数保证为此匹配器的有效组索引。

Returns
int The number of capturing groups in this matcher's pattern

hasAnchoringBounds

Added in API level 1
boolean hasAnchoringBounds ()

查询该匹配器的区域边界的锚定。

如果此匹配使用 固定的边界,否则 false此方法返回 true。

有关锚定界限的描述,请参阅 useAnchoringBounds

默认情况下,匹配器使用锚定区域边界。

Returns
boolean true iff this matcher is using anchoring bounds, false otherwise.

也可以看看:

hasTransparentBounds

Added in API level 1
boolean hasTransparentBounds ()

查询此匹配器的区域边界的透明度。

如果此匹配使用 透明边界 ,false,如果它使用 不透明边界此方法返回 true。

有关透明和不透明边界的说明,请参见 useTransparentBounds

默认情况下,匹配器使用不透明的区域边界。

Returns
boolean true iff this matcher is using transparent bounds, false otherwise.

也可以看看:

hitEnd

Added in API level 1
boolean hitEnd ()

如果在匹配器执行的最后一次匹配操作中输入的结尾被搜索引擎击中,则返回true。

当此方法返回true时,则可能有更多输入会改变上次搜索的结果。

Returns
boolean true iff the end of input was hit in the last match; false otherwise

lookingAt

Added in API level 1
boolean lookingAt ()

尝试将从区域开始处开始的输入序列与模式匹配。

matches方法一样,这个方法总是从该区域的开始处开始; 不像那种方法,它不需要整个区域匹配。

如果匹配成功可以通过 start,end,group方法来获得,然后更多的信息。

Returns
boolean true if, and only if, a prefix of the input sequence matches this matcher's pattern

matches

Added in API level 1
boolean matches ()

试图将整个区域与该模式进行匹配。

如果匹配成功可以通过 start,end,group方法来获得,然后更多的信息。

Returns
boolean true if, and only if, the entire region sequence matches this matcher's pattern

pattern

Added in API level 1
Pattern pattern ()

返回由此匹配器解释的模式。

Returns
Pattern The pattern for which this matcher was created

quoteReplacement

Added in API level 1
String quoteReplacement (String s)

返回面值替换String指定的String 此方法生成一个String ,它将作为Matcher类的appendReplacement方法中的文字替换s 生成的String将与s作为文字序列处理的字符序列相匹配。 斜线('\')和美元符号('$')将没有特别的含义。

Parameters
s String: The string to be literalized
Returns
String A literal string replacement

region

Added in API level 1
Matcher region (int start, 
                int end)

设置此匹配器区域的限制。 该区域是将被搜索以找到匹配的输入序列的一部分。 调用此方法重置匹配器,然后设置区域由指定的索引处开始start由指定的索引在参数和结束end参数。

根据所使用的透明度和锚定情况(请参阅 useTransparentBoundsuseAnchoringBounds ),某些构造(如锚点)在该区域边界处或附近的行为可能会有所不同。

Parameters
start int: The index to start searching at (inclusive)
end int: The index to end searching at (exclusive)
Returns
Matcher this matcher
Throws
IndexOutOfBoundsException If start or end is less than zero, if start is greater than the length of the input sequence, if end is greater than the length of the input sequence, or if start is greater than end.

regionEnd

Added in API level 1
int regionEnd ()

报告匹配器区域的结束索引(独占)。 匹配者进行的搜索仅限于在regionStart (含)和regionEndregionStart )中找到匹配regionStart

Returns
int the ending point of this matcher's region

regionStart

Added in API level 1
int regionStart ()

报告匹配器区域的开始索引。 此匹配器进行的搜索仅限于在regionStart (含)和regionEndregionStart )中查找匹配regionStart

Returns
int The starting point of this matcher's region

replaceAll

Added in API level 1
String replaceAll (String replacement)

用输入替换字符串替换与模式匹配的输入序列的每个子序列。

该方法首先重置此匹配器。 然后它扫描输入序列以查找模式的匹配。 不属于任何匹配的字符直接附加到结果字符串; 每个匹配在替换字符串的结果中被替换。 替换字符串可能包含对捕获子序列的引用,如appendReplacement方法中所述。

请注意替换字符串中的反斜杠( \ )和美元符号( $ )可能会导致结果与将它视为字面替换字符串时的结果不同。 如上所述,美元符号可以视为对捕获的子序列的引用,而反斜杠用于转义替换字符串中的文字字符。

给定正则表达式 a*b ,输入 "aabfooaabfooabfoob"和替换字符串 "-" ,在该表达式的匹配器上调用此方法将产生字符串 "-foo-foo-foo-"

调用这个方法改变了这个匹配器的状态。 如果匹配器将被用于进一步的匹配操作,那么它应该首先被重置。

Parameters
replacement String: The replacement string
Returns
String The string constructed by replacing each matching subsequence by the replacement string, substituting captured subsequences as needed

replaceFirst

Added in API level 1
String replaceFirst (String replacement)

将输入序列的第一个子序列替换为给定替换字符串的模式。

该方法首先重置此匹配器。 然后它扫描输入序列,寻找模式的匹配。 不属于匹配的字符直接附加到结果字符串; 在替换字符串的结果中匹配被替换。 appendReplacement方法中的替换字符串可能包含对捕获的子序列的appendReplacement

请注意,替换字符串中的反斜杠( \ )和美元符号( $ )可能会导致结果与将它视为字面替换字符串时的结果不同。 如上所述,美元符号可以视为对捕获的子序列的引用,而反斜杠用于转义替换字符串中的文字字符。

给定正则表达式 dog ,输入 "zzzdogzzzdogzzz"和替换字符串 "cat" ,在该表达式的匹配器上调用此方法将产生字符串 "zzzcatzzzdogzzz"

调用这个方法改变了这个匹配器的状态。 如果匹配器将被用于进一步的匹配操作,那么它应该首先被重置。

Parameters
replacement String: The replacement string
Returns
String The string constructed by replacing the first matching subsequence by the replacement string, substituting captured subsequences as needed

requireEnd

Added in API level 1
boolean requireEnd ()

如果有更多输入可以将正匹配变为负匹配,则返回true。

如果此方法返回true,并且找到匹配项,则更多输入可能会导致匹配丢失。 如果此方法返回false并找到匹配项,则更多输入可能会更改匹配,但匹配不会丢失。 如果找不到匹配,那么requireEnd就没有意义。

Returns
boolean true iff more input could change a positive match into a negative one.

reset

Added in API level 1
Matcher reset (CharSequence input)

用新的输入序列重新设置匹配器。

重置匹配器会丢弃其所有显式状态信息,并将其附加位置设置为零。 匹配器的区域被设置为默认区域,这是它的整个字符序列。 匹配器区域边界的锚定和透明度不受影响。

Parameters
input CharSequence: The new input character sequence
Returns
Matcher This matcher

reset

Added in API level 1
Matcher reset ()

重置此匹配器。

重置匹配器会丢弃其所有显式状态信息,并将其附加位置设置为零。 匹配器的区域被设置为默认区域,这是它的整个字符序列。 匹配器区域边界的锚定和透明度不受影响。

Returns
Matcher This matcher

start

Added in API level 1
int start ()

Returns the start index of the previous match.

Returns
int The index of the first character matched
Throws
IllegalStateException If no match has yet been attempted, or if the previous match operation failed

start

Added in API level 1
int start (int group)

返回上一次匹配操作期间给定组捕获的子序列的开始索引。

Capturing groups从左到右索引,从1开始。 零组表示整个模式,所以表达式m。 start(0)等于m。 start()

Parameters
group int: The index of a capturing group in this matcher's pattern
Returns
int The index of the first character captured by the group, or -1 if the match was successful but the group itself did not match anything
Throws
IllegalStateException If no match has yet been attempted, or if the previous match operation failed
IndexOutOfBoundsException If there is no capturing group in the pattern with the given index

toMatchResult

Added in API level 1
MatchResult toMatchResult ()

MatchResult返回此匹配器的匹配状态。 结果不受随后在此匹配器上执行的操作的影响。

Returns
MatchResult a MatchResult with the state of this matcher

toString

Added in API level 1
String toString ()

返回此匹配器的字符串表示形式。 Matcher的字符串表示包含可能对调试有用的信息。 确切的格式是未指定的。

Returns
String The string representation of this matcher

useAnchoringBounds

Added in API level 1
Matcher useAnchoringBounds (boolean value)

设置此匹配器的区域边界的锚定。

调用此方法的参数为true将设置此匹配器以使用锚定边界。 如果布尔参数是false ,则将使用非锚定边界。

使用锚定边界,匹配器的区域的边界匹配诸如^和$的锚点。

如果没有锚定边界,则此匹配器区域的边界将不匹配诸如^和$之类的锚点。

默认情况下,匹配器使用锚定区域边界。

Parameters
value boolean: a boolean indicating whether or not to use anchoring bounds.
Returns
Matcher this matcher

也可以看看:

usePattern

Added in API level 1
Matcher usePattern (Pattern newPattern)

更改 Pattern,Matcher用于查找与匹配。

此方法会导致此匹配程序丢失有关上次发生的匹配组的信息。 匹配器在输入中的位置保持不变,其最后的附加位置不受影响。

Parameters
newPattern Pattern: The new pattern used by this matcher
Returns
Matcher This matcher
Throws
IllegalArgumentException If newPattern is null

useTransparentBounds

Added in API level 1
Matcher useTransparentBounds (boolean value)

设置此匹配器的区域边界的透明度。

用参数true调用此方法将设置此匹配器以使用透明边界。 如果布尔参数是false ,那么将使用不透明边界。

使用透明边界,此匹配器区域的边界对前瞻,后视和边界匹配构造是透明的。 这些结构可以超越区域边界看到比赛是否合适。

使用不透明边界,该匹配器区域的边界对前瞻,后视和边界匹配构造是不透明的,这些构造可能试图超越它们。 这些构造不能超越边界,因此它们将无法匹配区域之外的任何东西。

默认情况下,匹配器使用不透明边界。

Parameters
value boolean: a boolean indicating whether to use opaque or transparent regions
Returns
Matcher this matcher

也可以看看:

Hooray!