Matcher

public final class Matcher extends Object
implements MatchResult

An engine that performs match operations on a character sequence by interpreting a Pattern.

A matcher is created from a pattern by invoking the pattern's matcher method. Once created, a matcher can be used to perform three different kinds of match operations:

  • The matches method attempts to match the entire input sequence against the pattern.

  • The lookingAt method attempts to match the input sequence, starting at the beginning, against the pattern.

  • The find method scans the input sequence looking for the next subsequence that matches the pattern.

Each of these methods returns a boolean indicating success or failure. More information about a successful match can be obtained by querying the state of the matcher.

A matcher finds matches in a subset of its input called the region. By default, the region contains all of the matcher's input. The region can be modified via theregion method and queried via the regionStart and regionEnd methods. The way that the region boundaries interact with some pattern constructs can be changed. See useAnchoringBounds and useTransparentBounds for more details.

This class also defines methods for replacing matched subsequences with new strings whose contents can, if desired, be computed from the match result. The appendReplacement and appendTail methods can be used in tandem in order to collect the result into an existing string buffer, or the more convenient replaceAll method can be used to create a string in which every matching subsequence in the input sequence is replaced.

The explicit state of a matcher includes the start and end indices of the most recent successful match. It also includes the start and end indices of the input subsequence captured by each capturing group in the pattern as well as a total count of such subsequences. As a convenience, methods are also provided for returning these captured subsequences in string form.

The explicit state of a matcher is initially undefined; attempting to query any part of it before a successful match will cause an IllegalStateException to be thrown. The explicit state of a matcher is recomputed by every match operation.

The implicit state of a matcher includes the input character sequence as well as the append position, which is initially zero and is updated by the appendReplacement method.

A matcher may be reset explicitly by invoking its reset() method or, if a new input sequence is desired, its reset(CharSequence) method. Resetting a matcher discards its explicit state information and sets the append position to zero.

Instances of this class are not safe for use by multiple concurrent threads.

Public Method Summary

Matcher
appendReplacement(StringBuilder buffer, String replacement)
Appends a literal part of the input plus a replacement for the current match to a given StringBuilder.
Matcher
appendReplacement(StringBuffer sb, String replacement)
Implements a non-terminal append-and-replace step.
StringBuffer
appendTail(StringBuffer sb)
Implements a terminal append-and-replace step.
StringBuilder
appendTail(StringBuilder buffer)
Appends the (unmatched) remainder of the input to the given StringBuilder.
int
end(int group)
Returns the offset after the last character of the subsequence captured by the given group during the previous match operation.
int
end()
Returns the offset after the last character matched.
boolean
find()
Attempts to find the next subsequence of the input sequence that matches the pattern.
boolean
find(int start)
Resets this matcher and then attempts to find the next subsequence of the input sequence that matches the pattern, starting at the specified index.
String
group(int group)
Returns the input subsequence captured by the given group during the previous match operation.
String
group()
Returns the input subsequence matched by the previous match.
int
groupCount()
Returns the number of capturing groups in this matcher's pattern.
boolean
hasAnchoringBounds()
Queries the anchoring of region bounds for this matcher.
boolean
hasTransparentBounds()
Queries the transparency of region bounds for this matcher.
boolean
hitEnd()

Returns true if the end of input was hit by the search engine in the last match operation performed by this matcher.

boolean
lookingAt()
Attempts to match the input sequence, starting at the beginning of the region, against the pattern.
boolean
matches()
Attempts to match the entire region against the pattern.
Pattern
pattern()
Returns the pattern that is interpreted by this matcher.
static String
quoteReplacement(String s)
Returns a literal replacement String for the specified String.
Matcher
region(int start, int end)
Sets the limits of this matcher's region.
int
regionEnd()
Reports the end index (exclusive) of this matcher's region.
int
regionStart()
Reports the start index of this matcher's region.
String
replaceAll(String replacement)
Replaces every subsequence of the input sequence that matches the pattern with the given replacement string.
String
replaceFirst(String replacement)
Replaces the first subsequence of the input sequence that matches the pattern with the given replacement string.
boolean
requireEnd()

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

Matcher
reset(CharSequence input)
Resets this matcher with a new input sequence.
Matcher
reset()
Resets this matcher.
int
start()
Returns the start index of the previous match.
int
start(int group)
Returns the start index of the subsequence captured by the given group during the previous match operation.
MatchResult
toMatchResult()
Returns the match state of this matcher as a MatchResult.
String
toString()

Returns the string representation of this matcher.

Matcher
useAnchoringBounds(boolean value)
Sets the anchoring of region bounds for this matcher.
Matcher
usePattern(Pattern newPattern)
Changes the Pattern that this Matcher uses to find matches with.
Matcher
useTransparentBounds(boolean value)
Sets the transparency of region bounds for this matcher.