Class Matcher
Pattern
on a specific input. Its interface
mimics the JDK 1.4.2 java.util.regex.Matcher
.
Conceptually, a Matcher consists of four parts:
- A compiled regular expression
Pattern
, set at construction and fixed for the lifetime of the matcher. - The remainder of the input string, set at construction or
reset()
and advanced by each match operation such asfind()
,matches()
orlookingAt()
. - The current match information, accessible via
start()
,end()
, andgroup()
, and updated by each match operation. - The append position, used and advanced by
appendReplacement(java.lang.StringBuffer, java.lang.String)
andappendTail(java.lang.StringBuffer)
if performing a search and replace from the input to an externalStringBuffer
.
See the package-level documentation for an overview of how to use this API.
- Author:
- rsc@google.com (Russ Cox)
-
Method Summary
Modifier and TypeMethodDescriptionappendReplacement
(StringBuffer sb, String replacement) Appends tosb
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
, wheren
is the group number in decimal.appendReplacement
(StringBuilder sb, String replacement) Appends tosb
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
, wheren
is the group number in decimal.Appends tosb
the substring of the input from the append position to the end of the input.Appends tosb
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
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.group()
Returns the most recent match.group
(int group) Returns the subgroup of the most recent match.Returns the named group of the most recent match, ornull
if the group was not matched.int
Returns the number of subgroups in this pattern.boolean
Matches the beginning of input against the pattern (anchored start).boolean
matches()
Matches the entire input against the pattern (anchored start and end).pattern()
Returns thePattern
associated with thisMatcher
.static String
Quotes '\' and '$' ins
, so that the returned string could be used inappendReplacement(java.lang.StringBuffer, java.lang.String)
as a literal replacement ofs
.replaceAll
(String replacement) Returns the input with all matches replaced byreplacement
, interpreted as forappendReplacement
.replaceFirst
(String replacement) Returns the input with the first match replaced byreplacement
, interpreted as forappendReplacement
.reset()
Resets theMatcher
, rewinding input and discarding any match information.reset
(byte[] bytes) Resets theMatcher
and changes the input.reset
(CharSequence input) Resets theMatcher
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
Returns the start of the named group of the most recent match, or -1 if the group was not matched.
-
Method Details
-
pattern
Returns thePattern
associated with thisMatcher
. -
reset
Resets theMatcher
, rewinding input and discarding any match information.- Returns:
- the
Matcher
itself, for chained method calls
-
reset
Resets theMatcher
and changes the input.- Parameters:
input
- the new input string- Returns:
- the
Matcher
itself, for chained method calls
-
reset
Resets theMatcher
and changes the input.- Parameters:
bytes
- utf8 bytes of the input string.- Returns:
- the
Matcher
itself, for chained method calls
-
start
public int start()Returns the start position of the most recent match.- Throws:
IllegalStateException
- if there is no match
-
end
public int end()Returns the end position of the most recent match.- Throws:
IllegalStateException
- if there is no match
-
start
public int start(int group) Returns the start position of a subgroup of the most recent match.- Parameters:
group
- the group index; 0 is the overall match- Throws:
IllegalStateException
- if there is no matchIndexOutOfBoundsException
- ifgroup < 0
orgroup > groupCount()
-
start
Returns the start of the named group of the most recent match, or -1 if the group was not matched.- Parameters:
group
- the group name- Throws:
IllegalArgumentException
- if no group with that name exists
-
end
public int end(int group) Returns the end position of a subgroup of the most recent match.- Parameters:
group
- the group index; 0 is the overall match- Throws:
IllegalStateException
- if there is no matchIndexOutOfBoundsException
- ifgroup < 0
orgroup > groupCount()
-
end
Returns the end of the named group of the most recent match, or -1 if the group was not matched.- Parameters:
group
- the group name- Throws:
IllegalArgumentException
- if no group with that name exists
-
group
Returns the most recent match.- Throws:
IllegalStateException
- if there is no match
-
group
Returns the subgroup of the most recent match.- Throws:
IllegalStateException
- if there is no matchIndexOutOfBoundsException
- ifgroup < 0
orgroup > groupCount()
-
group
Returns the named group of the most recent match, ornull
if the group was not matched.- Parameters:
group
- the group name- Throws:
IllegalArgumentException
- if no group with that name exists
-
groupCount
public int groupCount()Returns the number of subgroups in this pattern.- Returns:
- the number of subgroups; the overall match (group 0) does not count
-
matches
public boolean matches()Matches the entire input against the pattern (anchored start and end). If there is a match,matches
sets the match state to describe it.- Returns:
- true if the entire input matches the pattern
-
lookingAt
public boolean lookingAt()Matches the beginning of input against the pattern (anchored start). If there is a match,lookingAt
sets the match state to describe it.- Returns:
- true if the beginning of the input matches the pattern
-
find
public boolean find()Matches the input against the pattern (unanchored). The search begins at the end of the last match, or else the beginning of the input. If there is a match,find
sets the match state to describe it.- Returns:
- true if it finds a match
-
find
public boolean find(int start) Matches the input against the pattern (unanchored), starting at a specified position. If there is a match,find
sets the match state to describe it.- Parameters:
start
- the input position where the search begins- Returns:
- true if it finds a match
- Throws:
IndexOutOfBoundsException
- if start is not a valid input position
-
quoteReplacement
Quotes '\' and '$' ins
, so that the returned string could be used inappendReplacement(java.lang.StringBuffer, java.lang.String)
as a literal replacement ofs
.- Parameters:
s
- the string to be quoted- Returns:
- the quoted string
-
appendReplacement
Appends tosb
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
, wheren
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.- Parameters:
sb
- theStringBuffer
to append toreplacement
- the replacement string- Returns:
- the
Matcher
itself, for chained method calls - Throws:
IllegalStateException
- if there was no most recent matchIndexOutOfBoundsException
- if replacement refers to an invalid group
-
appendReplacement
Appends tosb
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
, wheren
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.- Parameters:
sb
- theStringBuilder
to append toreplacement
- the replacement string- Returns:
- the
Matcher
itself, for chained method calls - Throws:
IllegalStateException
- if there was no most recent matchIndexOutOfBoundsException
- if replacement refers to an invalid group
-
appendTail
Appends tosb
the substring of the input from the append position to the end of the input.- Parameters:
sb
- theStringBuffer
to append to- Returns:
- the argument
sb
, for method chaining
-
appendTail
Appends tosb
the substring of the input from the append position to the end of the input.- Parameters:
sb
- theStringBuilder
to append to- Returns:
- the argument
sb
, for method chaining
-
replaceAll
Returns the input with all matches replaced byreplacement
, interpreted as forappendReplacement
.- Parameters:
replacement
- the replacement string- Returns:
- the input string with the matches replaced
- Throws:
IndexOutOfBoundsException
- if replacement refers to an invalid group
-
replaceFirst
Returns the input with the first match replaced byreplacement
, interpreted as forappendReplacement
.- Parameters:
replacement
- the replacement string- Returns:
- the input string with the first match replaced
- Throws:
IndexOutOfBoundsException
- if replacement refers to an invalid group
-