public final class Matcher
extends java.lang.Object
Pattern on a specific input. Its interface
mimics the JDK 1.4.2 java.util.regex.Matcher.
Conceptually, a Matcher consists of four parts:
Pattern, set at construction and fixed for the lifetime
of the matcher.reset() and advanced by
each match operation such as find(), matches() or lookingAt().start(), end(), and
group(), and updated by each match operation.appendReplacement(java.lang.StringBuffer, java.lang.String) and appendTail(java.lang.StringBuffer)
if performing a search and replace from the input to an external StringBuffer.
See the package-level documentation for an overview of how to use this API.
| Modifier and Type | Method and Description |
|---|---|
Matcher |
appendReplacement(java.lang.StringBuffer sb,
java.lang.String replacement)
Appends to
sb two strings: the text from the append position up to the beginning of the
most recent match, and then the replacement with submatch groups substituted for references of
the form $n, where n is the group number in decimal. |
Matcher |
appendReplacement(java.lang.StringBuilder sb,
java.lang.String replacement)
Appends to
sb two strings: the text from the append position up to the beginning of the
most recent match, and then the replacement with submatch groups substituted for references of
the form $n, where n is the group number in decimal. |
java.lang.StringBuffer |
appendTail(java.lang.StringBuffer sb)
Appends to
sb the substring of the input from the append position to the end of the
input. |
java.lang.StringBuilder |
appendTail(java.lang.StringBuilder sb)
Appends to
sb the substring of the input from the append position to the end of the
input. |
int |
end()
Returns the end position of the most recent match.
|
int |
end(int group)
Returns the end position of a subgroup of the most recent match.
|
int |
end(java.lang.String group)
Returns the end of the named group of the most recent match, or -1 if the group was not
matched.
|
boolean |
find()
Matches the input against the pattern (unanchored).
|
boolean |
find(int start)
Matches the input against the pattern (unanchored), starting at a specified position.
|
java.lang.String |
group()
Returns the most recent match.
|
java.lang.String |
group(int group)
Returns the subgroup of the most recent match.
|
java.lang.String |
group(java.lang.String group)
Returns the named group of the most recent match, or
null if the group was not matched. |
int |
groupCount()
Returns the number of subgroups in this pattern.
|
boolean |
lookingAt()
Matches the beginning of input against the pattern (anchored start).
|
boolean |
matches()
Matches the entire input against the pattern (anchored start and end).
|
Pattern |
pattern()
Returns the
Pattern associated with this Matcher. |
static java.lang.String |
quoteReplacement(java.lang.String s)
Quotes '\' and '$' in
s, so that the returned string could be used in
appendReplacement(java.lang.StringBuffer, java.lang.String) as a literal replacement of s. |
java.lang.String |
replaceAll(java.lang.String replacement)
Returns the input with all matches replaced by
replacement, interpreted as for
appendReplacement. |
java.lang.String |
replaceFirst(java.lang.String replacement)
Returns the input with the first match replaced by
replacement, interpreted as for
appendReplacement. |
Matcher |
reset()
Resets the
Matcher, rewinding input and discarding any match information. |
Matcher |
reset(byte[] bytes)
Resets the
Matcher and changes the input. |
Matcher |
reset(java.lang.CharSequence input)
Resets the
Matcher and changes the input. |
int |
start()
Returns the start position of the most recent match.
|
int |
start(int group)
Returns the start position of a subgroup of the most recent match.
|
int |
start(java.lang.String group)
Returns the start of the named group of the most recent match, or -1 if the group was not
matched.
|
public Pattern pattern()
Pattern associated with this Matcher.public Matcher reset()
Matcher, rewinding input and discarding any match information.Matcher itself, for chained method callspublic Matcher reset(java.lang.CharSequence input)
Matcher and changes the input.input - the new input stringMatcher itself, for chained method callspublic Matcher reset(byte[] bytes)
Matcher and changes the input.bytes - utf8 bytes of the input string.Matcher itself, for chained method callspublic int start()
java.lang.IllegalStateException - if there is no matchpublic int end()
java.lang.IllegalStateException - if there is no matchpublic int start(int group)
group - the group index; 0 is the overall matchjava.lang.IllegalStateException - if there is no matchjava.lang.IndexOutOfBoundsException - if group < 0 or group > groupCount()public int start(java.lang.String group)
group - the group namejava.lang.IllegalArgumentException - if no group with that name existspublic int end(int group)
group - the group index; 0 is the overall matchjava.lang.IllegalStateException - if there is no matchjava.lang.IndexOutOfBoundsException - if group < 0 or group > groupCount()public int end(java.lang.String group)
group - the group namejava.lang.IllegalArgumentException - if no group with that name existspublic java.lang.String group()
java.lang.IllegalStateException - if there is no matchpublic java.lang.String group(int group)
java.lang.IllegalStateException - if there is no matchjava.lang.IndexOutOfBoundsException - if group < 0 or group > groupCount()public java.lang.String group(java.lang.String group)
null if the group was not matched.group - the group namejava.lang.IllegalArgumentException - if no group with that name existspublic int groupCount()
public boolean matches()
matches sets the match state to describe it.public boolean lookingAt()
lookingAt sets the match state to describe it.public boolean find()
find sets the match
state to describe it.public boolean find(int start)
find sets the match state to describe it.start - the input position where the search beginsjava.lang.IndexOutOfBoundsException - if start is not a valid input positionpublic static java.lang.String quoteReplacement(java.lang.String s)
s, so that the returned string could be used in
appendReplacement(java.lang.StringBuffer, java.lang.String) as a literal replacement of s.s - the string to be quotedpublic Matcher appendReplacement(java.lang.StringBuffer sb, java.lang.String replacement)
sb two strings: the text from the append position up to the beginning of the
most recent match, and then the replacement with submatch groups substituted for references of
the form $n, where n is the group number in decimal. It advances the append
position to where the most recent match ended.
To embed a literal $, use \$ (actually "\\$" with string escapes). The escape
is only necessary when $ is followed by a digit, but it is always allowed. Only
$ and \ need escaping, but any character can be escaped.
The group number n in $n is always at least one digit and expands to use more
digits as long as the resulting number is a valid group number for this pattern. To cut it off
earlier, escape the first digit that should not be used.
sb - the StringBuffer to append toreplacement - the replacement stringMatcher itself, for chained method callsjava.lang.IllegalStateException - if there was no most recent matchjava.lang.IndexOutOfBoundsException - if replacement refers to an invalid grouppublic Matcher appendReplacement(java.lang.StringBuilder sb, java.lang.String replacement)
sb two strings: the text from the append position up to the beginning of the
most recent match, and then the replacement with submatch groups substituted for references of
the form $n, where n is the group number in decimal. It advances the append
position to where the most recent match ended.
To embed a literal $, use \$ (actually "\\$" with string escapes). The escape
is only necessary when $ is followed by a digit, but it is always allowed. Only
$ and \ need escaping, but any character can be escaped.
The group number n in $n is always at least one digit and expands to use more
digits as long as the resulting number is a valid group number for this pattern. To cut it off
earlier, escape the first digit that should not be used.
sb - the StringBuilder to append toreplacement - the replacement stringMatcher itself, for chained method callsjava.lang.IllegalStateException - if there was no most recent matchjava.lang.IndexOutOfBoundsException - if replacement refers to an invalid grouppublic java.lang.StringBuffer appendTail(java.lang.StringBuffer sb)
sb the substring of the input from the append position to the end of the
input.sb - the StringBuffer to append tosb, for method chainingpublic java.lang.StringBuilder appendTail(java.lang.StringBuilder sb)
sb the substring of the input from the append position to the end of the
input.sb - the StringBuilder to append tosb, for method chainingpublic java.lang.String replaceAll(java.lang.String replacement)
replacement, interpreted as for
appendReplacement.replacement - the replacement stringjava.lang.IndexOutOfBoundsException - if replacement refers to an invalid grouppublic java.lang.String replaceFirst(java.lang.String replacement)
replacement, interpreted as for
appendReplacement.replacement - the replacement stringjava.lang.IndexOutOfBoundsException - if replacement refers to an invalid group