Class Matcher

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

public final class Matcher extends 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.

Author:
rsc@google.com (Russ Cox)
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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.
    Appends to sb the substring of the input from the append position to the end of the input.
    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(String group)
    Returns the end of the named group of the most recent match, or -1 if the group was not matched.
    boolean
    Matches the input against the pattern (unanchored).
    boolean
    find(int start)
    Matches the input against the pattern (unanchored), starting at a specified position.
    Returns the most recent match.
    group(int group)
    Returns the subgroup of the most recent match.
    group(String group)
    Returns the named group of the most recent match, or null 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 the entire input against the pattern (anchored start and end).
    Returns the Pattern associated with this Matcher.
    static String
    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.
    replaceAll(String replacement)
    Returns the input with all matches replaced by replacement, interpreted as for appendReplacement.
    replaceFirst(String replacement)
    Returns the input with the first match replaced by replacement, interpreted as for appendReplacement.
    Resets the Matcher, rewinding input and discarding any match information.
    reset(byte[] bytes)
    Resets the Matcher and changes the input.
    Resets the Matcher and changes the input.
    int
    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(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 Details

    • 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(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:
      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 match
      IndexOutOfBoundsException - if group < 0 or group > groupCount()
    • start

      public int start(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:
      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 match
      IndexOutOfBoundsException - if group < 0 or group > groupCount()
    • end

      public int end(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:
      IllegalArgumentException - if no group with that name exists
    • group

      public String group()
      Returns the most recent match.
      Throws:
      IllegalStateException - if there is no match
    • group

      public String group(int group)
      Returns the subgroup of the most recent match.
      Throws:
      IllegalStateException - if there is no match
      IndexOutOfBoundsException - if group < 0 or group > groupCount()
    • group

      public String group(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:
      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

      public static String quoteReplacement(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(StringBuffer sb, 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:
      IllegalStateException - if there was no most recent match
      IndexOutOfBoundsException - if replacement refers to an invalid group
    • appendReplacement

      public Matcher appendReplacement(StringBuilder sb, 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:
      IllegalStateException - if there was no most recent match
      IndexOutOfBoundsException - if replacement refers to an invalid group
    • appendTail

      public StringBuffer appendTail(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 StringBuilder appendTail(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 String replaceAll(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:
      IndexOutOfBoundsException - if replacement refers to an invalid group
    • replaceFirst

      public String replaceFirst(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:
      IndexOutOfBoundsException - if replacement refers to an invalid group