java.util.regex
public
final
class
java.util.regex.Matcher
Provides a means of matching regular expressions against a given input,
finding occurrences of regular expressions in a given input, or replacing
parts of a given input. A Matcher
instance has an associated Pattern instance and an input text. A typical use case is to
iteratively find all occurrences of the Pattern
, until the end of
the input is reached, as the following example illustrates:
Pattern p = Pattern.compile("[A-Za-z]+");
Matcher m = p.matcher("Hello, Android!");
while (m.find()) {
System.out.println(m.group()); // prints "Hello" and "Android"
}
The
Matcher
has a state that results from the previous operations.
For example, it knows whether the most recent attempt to find the
Pattern
was successful and at which position the next attempt would
resume the search. Depending on the application's needs, it may become
necessary to explicitly
reset() this state from time to time.
Summary
Public Methods
Protected Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Public Methods
Appends a literal part of the input plus a replacement for the current
match to a given
StringBuffer. The literal part is exactly the
part of the input between the previous match and the current match. The
method can be used in conjunction with
find() and
appendTail(StringBuffer) to walk through the input and replace
all occurrences of the
Pattern
with something else.
Parameters
buffer
| the StringBuffer to append to. |
replacement
| the replacement text. |
Appends the (unmatched) remainder of the input to the given
StringBuffer. The method can be used in conjunction with
find() and
appendReplacement(StringBuffer, String) to
walk through the input and replace all matches of the
Pattern
with something else.
Parameters
buffer
| the StringBuffer to append to. |
public
int
end()
Returns the index of the first character following the text that matched
the whole regular expression.
public
int
end(int group)
Returns the index of the first character following the text that matched
a given group.
Parameters
group
| the group, ranging from 0 to groupCount() - 1, with 0
representing the whole pattern. |
public
boolean
find(int start)
Returns the next occurrence of the
Pattern in the input. The
method starts the search from the given character in the input.
Parameters
start
| The index in the input at which the find operation is to
begin. If this is less than the start of the region, it is
automatically adjusted to that value. If it is beyond the end
of the region, the method will fail. |
Returns
- true if (and only if) a match has been found.
public
boolean
find()
Returns the next occurrence of the
Pattern in the input. If a
previous match was successful, the method continues the search from the
first character following that match in the input. Otherwise it searches
either from the region start (if one has been set), or from position 0.
Returns
- true if (and only if) a match has been found.
public
String
group(int group)
Returns the text that matched a given group of the regular expression.
Parameters
group
| the group, ranging from 0 to groupCount() - 1, with 0
representing the whole pattern. |
Returns
- the text that matched the group.
public
String
group()
Returns the text that matched the whole regular expression.
public
int
groupCount()
Returns the number of groups in the results, which is always equal to
the number of groups in the original regular expression.
public
boolean
hasAnchoringBounds()
Indicates whether this matcher has anchoring bounds enabled. When
anchoring bounds are enabled, the start and end of the input match the
'^' and '$' meta-characters, otherwise not. Anchoring bounds are enabled
by default.
Returns
- true if (and only if) the
Matcher
uses anchoring bounds.
public
boolean
hasTransparentBounds()
Indicates whether this matcher has transparent bounds enabled. When
transparent bounds are enabled, the parts of the input outside the region
are subject to lookahead and lookbehind, otherwise they are not.
Transparent bounds are disabled by default.
Returns
- true if (and only if) the
Matcher
uses anchoring bounds.
public
boolean
hitEnd()
Indicates whether the last match hit the end of the input.
Returns
- true if (and only if) the last match hit the end of the input.
public
boolean
lookingAt()
Tries to match the
Pattern, starting from the beginning of the
region (or the beginning of the input, if no region has been set).
Doesn't require the
Pattern
to match against the whole region.
Returns
- true if (and only if) the
Pattern
matches.
public
boolean
matches()
Tries to match the
Pattern against the entire region (or the
entire input, if no region has been set).
Returns
- true if (and only if) the
Pattern
matches the entire
region.
public
Pattern
pattern()
Returns the
Pattern instance used inside this matcher.
public
static
String
quoteReplacement(String s)
Returns a replacement string for the given one that has all backslashes
and dollar signs escaped.
Returns
- the input string, with all backslashes and dollar signs having
been escaped.
public
Matcher
region(int start, int end)
Resets this matcher and sets a region. Only characters inside the region
are considered for a match.
Parameters
start
| the first character of the region. |
end
| the first character after the end of the region. |
public
int
regionEnd()
Returns this matcher's region end, that is, the first character that is
not considered for a match.
public
int
regionStart()
Returns this matcher's region start, that is, the first character that is
considered for a match.
public
String
replaceAll(String replacement)
Replaces all occurrences of this matcher's pattern in the input with a
given string.
Parameters
replacement
| the replacement text. |
Returns
- the modified input string.
public
String
replaceFirst(String replacement)
Replaces the first occurrence of this matcher's pattern in the input with
a given string.
Parameters
replacement
| the replacement text. |
Returns
- the modified input string.
public
boolean
requireEnd()
Indicates whether more input might change a successful match into an
unsuccessful one.
Returns
- true if (and only if) more input might change a successful match
into an unsuccessful one.
public
Matcher
reset()
Resets the
Matcher
. This results in the region being set to the
whole input. Results of a previous find get lost. The next attempt to
find an occurrence of the
Pattern in the string will start at the
beginning of the input.
Provides a new input and resets the
Matcher
. This results in the
region being set to the whole input. Results of a previous find get lost.
The next attempt to find an occurrence of the
Pattern in the
string will start at the beginning of the input.
Parameters
input
| the new input sequence. |
public
int
start(int group)
Returns the index of the first character of the text that matched a given
group.
Parameters
group
| the group, ranging from 0 to groupCount() - 1, with 0
representing the whole pattern. |
public
int
start()
Returns the index of the first character of the text that matched the
whole regular expression.
public
MatchResult
toMatchResult()
Converts the current match into a separate
MatchResult instance
that is independent from this matcher. The new object is unaffected when
the state of this matcher changes.
public
Matcher
useAnchoringBounds(boolean value)
Determines whether this matcher has anchoring bounds enabled or not. When
anchoring bounds are enabled, the start and end of the input match the
'^' and '$' meta-characters, otherwise not. Anchoring bounds are enabled
by default.
Parameters
value
| the new value for anchoring bounds. |
Sets a new pattern for the
Matcher
. Results of a previous find
get lost. The next attempt to find an occurrence of the
Pattern
in the string will start at the beginning of the input.
public
Matcher
useTransparentBounds(boolean value)
Determines whether this matcher has transparent bounds enabled or not.
When transparent bounds are enabled, the parts of the input outside the
region are subject to lookahead and lookbehind, otherwise they are not.
Transparent bounds are disabled by default.
Parameters
value
| the new value for transparent bounds. |
Protected Methods
protected
void
finalize()
Called by the virtual machine when there are no longer any (non-weak)
references to the receiver. Subclasses can use this facility to guarantee
that any associated resources are cleaned up before the receiver is
garbage collected. Uncaught exceptions which are thrown during the
running of the method cause it to terminate immediately, but are
otherwise ignored.
Note: The virtual machine assumes that the implementation in class Object
is empty.