Class Matcher
- java.lang.Object
-
- com.google.re2j.Matcher
-
public final class Matcher extends java.lang.Object
A stateful iterator that interprets a regexPattern
on a specific input. Its interface mimics the JDK 1.4.2java.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)
- A compiled regular expression
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Matcher
appendReplacement(java.lang.StringBuffer sb, java.lang.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.Matcher
appendReplacement(java.lang.StringBuilder sb, java.lang.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.java.lang.StringBuffer
appendTail(java.lang.StringBuffer sb)
Appends tosb
the substring of the input from the append position to the end of the input.java.lang.StringBuilder
appendTail(java.lang.StringBuilder sb)
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
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, ornull
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 thePattern
associated with thisMatcher
.static java.lang.String
quoteReplacement(java.lang.String s)
Quotes '\' and '$' ins
, so that the returned string could be used inappendReplacement(java.lang.StringBuffer, java.lang.String)
as a literal replacement ofs
.java.lang.String
replaceAll(java.lang.String replacement)
Returns the input with all matches replaced byreplacement
, interpreted as forappendReplacement
.java.lang.String
replaceFirst(java.lang.String replacement)
Returns the input with the first match replaced byreplacement
, interpreted as forappendReplacement
.Matcher
reset()
Resets theMatcher
, rewinding input and discarding any match information.Matcher
reset(byte[] bytes)
Resets theMatcher
and changes the input.Matcher
reset(java.lang.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
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.
-
-
-
Method Detail
-
pattern
public Pattern pattern()
Returns thePattern
associated with thisMatcher
.
-
reset
public Matcher reset()
Resets theMatcher
, rewinding input and discarding any match information.- Returns:
- the
Matcher
itself, for chained method calls
-
reset
public Matcher reset(java.lang.CharSequence input)
Resets theMatcher
and changes the input.- Parameters:
input
- the new input string- Returns:
- the
Matcher
itself, for chained method calls
-
reset
public Matcher reset(byte[] bytes)
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:
java.lang.IllegalStateException
- if there is no match
-
end
public int end()
Returns the end position of the most recent match.- Throws:
java.lang.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:
java.lang.IllegalStateException
- if there is no matchjava.lang.IndexOutOfBoundsException
- ifgroup < 0
orgroup > groupCount()
-
start
public 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.- Parameters:
group
- the group name- Throws:
java.lang.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:
java.lang.IllegalStateException
- if there is no matchjava.lang.IndexOutOfBoundsException
- ifgroup < 0
orgroup > groupCount()
-
end
public 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.- Parameters:
group
- the group name- Throws:
java.lang.IllegalArgumentException
- if no group with that name exists
-
group
public java.lang.String group()
Returns the most recent match.- Throws:
java.lang.IllegalStateException
- if there is no match
-
group
public java.lang.String group(int group)
Returns the subgroup of the most recent match.- Throws:
java.lang.IllegalStateException
- if there is no matchjava.lang.IndexOutOfBoundsException
- ifgroup < 0
orgroup > groupCount()
-
group
public java.lang.String group(java.lang.String group)
Returns the named group of the most recent match, ornull
if the group was not matched.- Parameters:
group
- the group name- Throws:
java.lang.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:
java.lang.IndexOutOfBoundsException
- if start is not a valid input position
-
quoteReplacement
public static java.lang.String quoteReplacement(java.lang.String s)
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
public Matcher appendReplacement(java.lang.StringBuffer sb, java.lang.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. 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:
java.lang.IllegalStateException
- if there was no most recent matchjava.lang.IndexOutOfBoundsException
- if replacement refers to an invalid group
-
appendReplacement
public Matcher appendReplacement(java.lang.StringBuilder sb, java.lang.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. 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:
java.lang.IllegalStateException
- if there was no most recent matchjava.lang.IndexOutOfBoundsException
- if replacement refers to an invalid group
-
appendTail
public java.lang.StringBuffer appendTail(java.lang.StringBuffer sb)
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
public java.lang.StringBuilder appendTail(java.lang.StringBuilder sb)
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
public java.lang.String replaceAll(java.lang.String replacement)
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:
java.lang.IndexOutOfBoundsException
- if replacement refers to an invalid group
-
replaceFirst
public java.lang.String replaceFirst(java.lang.String replacement)
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:
java.lang.IndexOutOfBoundsException
- if replacement refers to an invalid group
-
-