Class 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.

    Author:
    rsc@google.com (Russ Cox)
    • 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 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