Matcher (re2j 1.7 API)

java.lang.Object
- com.google.re2j.Matcher

```
public final class Matcher
extends java.lang.Object
```
A stateful iterator that interprets a regex Pattern on a specific input. Its interface mimics the JDK 1.4.2 java.util.regex.Matcher.
Conceptually, a Matcher consists of four parts:
1. A compiled regular expression Pattern, set at construction and fixed for the lifetime of the matcher.
2. The remainder of the input string, set at construction or reset() and advanced by each match operation such as find(), matches() or lookingAt().
3. The current match information, accessible via start(), end(), and group(), and updated by each match operation.
4. The append position, used and advanced by 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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - pattern
```
public Pattern pattern()
```
    Returns the Pattern associated with this Matcher.
  - reset
```
public Matcher reset()
```
    Resets the Matcher, rewinding input and discarding any match information.
    
    Returns:
    
    the Matcher itself, for chained method calls
  - reset
```
public Matcher reset(java.lang.CharSequence input)
```
    Resets the Matcher 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 the Matcher 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 match
    
    java.lang.IndexOutOfBoundsException - if group < 0 or group > 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 match
    
    java.lang.IndexOutOfBoundsException - if group < 0 or group > 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 match
    
    java.lang.IndexOutOfBoundsException - if group < 0 or group > groupCount()
  - group
```
public 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.
    
    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 '$' in s, so that the returned string could be used in appendReplacement(java.lang.StringBuffer, java.lang.String) as a literal replacement of s.
    
    Parameters:
    
    s - the string to be quoted
    
    Returns:
    
    the quoted string
  - appendReplacement
```
public 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. 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 - the StringBuffer to append to
    
    replacement - the replacement string
    
    Returns:
    
    the Matcher itself, for chained method calls
    
    Throws:
    
    java.lang.IllegalStateException - if there was no most recent match
    
    java.lang.IndexOutOfBoundsException - if replacement refers to an invalid group
  - appendReplacement
```
public 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. 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 - the StringBuilder to append to
    
    replacement - the replacement string
    
    Returns:
    
    the Matcher itself, for chained method calls
    
    Throws:
    
    java.lang.IllegalStateException - if there was no most recent match
    
    java.lang.IndexOutOfBoundsException - if replacement refers to an invalid group
  - appendTail
```
public 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.
    
    Parameters:
    
    sb - the StringBuffer to append to
    
    Returns:
    
    the argument sb, for method chaining
  - appendTail
```
public 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.
    
    Parameters:
    
    sb - the StringBuilder 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 by replacement, interpreted as for appendReplacement.
    
    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 by replacement, interpreted as for appendReplacement.
    
    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

Class Matcher

Method Summary

Methods inherited from class java.lang.Object

Method Detail

pattern

reset

reset

reset

start

end

start

start

end

end

group

group

group

groupCount

matches

lookingAt

find

find

quoteReplacement

appendReplacement

appendReplacement

appendTail

appendTail

replaceAll

replaceFirst