Package com.google.re2j

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(io.airlift.slice.SliceOutput, io.airlift.slice.Slice) and appendTail(io.airlift.slice.SliceOutput) 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
    Matcher
    appendReplacement(io.airlift.slice.SliceOutput so, io.airlift.slice.Slice replacement)
    Appends to so two slices: 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.
    io.airlift.slice.SliceOutput
    appendTail(io.airlift.slice.SliceOutput so)
    Appends to so the subslice 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.
    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.
    io.airlift.slice.Slice
    group()
    Returns the most recent match.
    io.airlift.slice.Slice
    group(int group)
    Returns the subgroup of the most recent match.
    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.
    io.airlift.slice.Slice
    replaceAll(io.airlift.slice.Slice replacement)
    Returns the input with all matches replaced by replacement, interpreted as for appendReplacement.
    io.airlift.slice.Slice
    replaceFirst(io.airlift.slice.Slice 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(io.airlift.slice.Slice 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.

    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(io.airlift.slice.Slice input)
      Resets the Matcher and changes the input.
      Parameters:
      input - the new input Slice
      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()

    • 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()

    • group

      public io.airlift.slice.Slice group()
      Returns the most recent match.
      Throws:
      IllegalStateException - if there is no match

    • group

      public io.airlift.slice.Slice 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()

    • 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

    • appendReplacement

      public Matcher appendReplacement(io.airlift.slice.SliceOutput so, io.airlift.slice.Slice replacement)
      Appends to so two slices: 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 the position 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:
      so - the SliceOutput to append to
      replacement - the replacement Slice
      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
      IllegalArgumentException - if replacement has incorrect format

    • appendTail

      public io.airlift.slice.SliceOutput appendTail(io.airlift.slice.SliceOutput so)
      Appends to so the subslice of the input from the append position to the end of the input.
      Parameters:
      so - the SliceOutput to append to
      Returns:
      the argument so, for method chaining

    • replaceAll

      public io.airlift.slice.Slice replaceAll(io.airlift.slice.Slice replacement)
      Returns the input with all matches replaced by replacement, interpreted as for appendReplacement.
      Parameters:
      replacement - the replacement Slice
      Returns:
      the input Slice with the matches replaced
      Throws:
      IndexOutOfBoundsException - if replacement refers to an invalid group

    • replaceFirst

      public io.airlift.slice.Slice replaceFirst(io.airlift.slice.Slice replacement)
      Returns the input with the first match replaced by replacement, interpreted as for appendReplacement.
      Parameters:
      replacement - the replacement Slice
      Returns:
      the input Slice with the first match replaced
      Throws:
      IndexOutOfBoundsException - if replacement refers to an invalid group