Package com.orbit.api

Class Matcher

java.lang.Object
com.orbit.api.Matcher
public class Matcher extends Object
Matches a compiled Pattern against an input sequence.

Drop-in compatible with Matcher. Supports indexed and named capture group access via group(int), group(String), start(int), end(int), start(String), and end(String).

Instances are not thread-safe. Create one instance per thread or per match operation.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Matcher(Pattern pattern, CharSequence input)
    Creates a new Matcher for the given pattern and input.

  • Method Summary

    Modifier and Type
    Method
    Description
    Matcher
    appendReplacement(StringBuffer sb, String replacement)
    Appends the input between lastAppendPos and start() to sb, then appends the processed replacement string.
    Matcher
    appendReplacement(StringBuilder sb, String replacement)
    Appends the input between lastAppendPos and start() to sb, then appends replacement.
    StringBuffer
    appendTail(StringBuffer sb)
    Appends the remaining input from lastAppendPos to the end of the input to sb.
    StringBuilder
    appendTail(StringBuilder sb)
    Appends the remaining input from lastAppendPos to the end of the input to sb.
    int
    end()
    Returns the end index (exclusive) of the previous match.
    int
    end(int group)
    Returns the end index (exclusive) of the subsequence captured by the given group during the previous match operation.
    int
    end(String name)
    Returns the end index (exclusive) of the subsequence captured by the named group during the previous match operation.
    boolean
    find()
    Attempts to find the next subsequence of the input sequence that matches the pattern.
    boolean
    find(int start)
    Resets this matcher and then attempts to find a match starting no earlier than character position start.
    String
    group()
    Returns the input subsequence matched by the previous match operation.
    String
    group(int group)
    Returns the input subsequence captured by the given group during the previous match operation.
    String
    group(String name)
    Returns the input subsequence captured by the named group during the previous match operation.
    int
    groupCount()
    Returns the number of capturing groups in this matcher's pattern.
    boolean
    hasAnchoringBounds()
    Returns whether this matcher uses anchoring bounds.
    boolean
    hasMatch()
    Returns whether the last match operation succeeded.
    boolean
    hasTransparentBounds()
    Returns whether this matcher uses transparent bounds.
    boolean
    hitEnd()
    Returns true if the end of input was hit by the search engine in the last match operation performed by this matcher.
    boolean
    lookingAt()
    Attempts to match the input sequence, starting at the beginning of the region (from), against the pattern.
    boolean
    matches()
    Attempts to match the entire region against the pattern.
    Map<String,Integer>
    namedGroups()
    Returns an unmodifiable map from named capturing group names to their 1-based indices.
    static String
    quoteReplacement(String s)
    Returns a string in which each metacharacter (\ and $) in s is escaped, producing a replacement string that is treated as entirely literal by appendReplacement(StringBuilder, String), replaceAll(String), and replaceFirst(String).
    Matcher
    region(int start, int end)
    Sets the limits of this matcher's region.
    int
    regionEnd()
    Returns the end (exclusive) of this matcher's region.
    int
    regionStart()
    Returns the start (inclusive) of this matcher's region.
    String
    replaceAll(String replacement)
    Replaces every subsequence of the input sequence that matches the pattern with the given replacement string.
    String
    replaceAll(Function<MatchResult,String> replacer)
    Replaces every subsequence of the input that matches the pattern with the string produced by applying replacer to each MatchResult.
    String
    replaceFirst(String replacement)
    Resets the matcher, finds the first match, replaces it with replacement, and returns the result.
    String
    replaceFirst(Function<MatchResult,String> replacer)
    Resets the matcher, finds the first match, applies replacer to produce a replacement string, and returns the result.
    Matcher
    reset()
    Resets this matcher.
    Stream<MatchResult>
    results()
    Returns a lazily-evaluated stream of all non-overlapping matches in the input from the current position.
    int
    start()
    Returns the start index of the previous match.
    int
    start(int group)
    Returns the start index of the subsequence captured by the given group during the previous match operation.
    int
    start(String name)
    Returns the start index of the subsequence captured by the named group during the previous match operation.
    MatchResult
    toMatchResult()
    Returns the MatchResult for the last match operation.
    Matcher
    useAnchoringBounds(boolean b)
    Sets whether anchors (^, $, \A, \z) treat the region boundaries as the start/end of input.
    Matcher
    usePattern(Pattern newPattern)
    Changes the pattern used by this matcher to find matches in the input.
    Matcher
    useTransparentBounds(boolean b)
    Sets whether lookahead and lookbehind assertions can see characters outside the region.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Matcher

      public Matcher(Pattern pattern, CharSequence input)
      Creates a new Matcher for the given pattern and input.

      The initial region covers the full input [0, input.length()), anchoring bounds are enabled, and transparent bounds are disabled — matching JDK defaults.

      Parameters:
      pattern - the compiled pattern; must not be null
      input - the character sequence to match; must not be null

  • Method Details

    • matches

      public boolean matches()
      Attempts to match the entire region against the pattern.
      Returns:
      true if the entire region matches

    • find

      public boolean find()
      Attempts to find the next subsequence of the input sequence that matches the pattern.

      After a zero-length match the search position is advanced by one character so that subsequent calls do not return the same zero-length match and so that the method terminates. This matches the behaviour of Matcher.find().

      Returns:
      true if a subsequent match is found

    • find

      public boolean find(int start)
      Resets this matcher and then attempts to find a match starting no earlier than character position start.

      Performs a full reset (equivalent to calling reset()) before beginning the search. The search starts at position start within the input and proceeds forward. After a zero-length match the search position is advanced by one character.

      After a successful call, invoking find() continues the search from where this call left off.

      Parameters:
      start - the character index at which to begin the search; must be in [0, input.length()]
      Returns:
      true if a match is found starting at or after start
      Throws:
      IndexOutOfBoundsException - if start < 0 or start > input.length()

    • lookingAt

      public boolean lookingAt()
      Attempts to match the input sequence, starting at the beginning of the region (from), against the pattern.

      Unlike matches(), the entire region does not need to match; the pattern must only match a prefix of the region starting exactly at from. Unlike find(), the match must start at from exactly.

      This method does not modify from, to, lastAppendPos, or findFromStart. A subsequent find() call will resume from whatever from was before this call.

      After a successful return, group(), start(), end(), and group accessors all work as after a successful find() or matches().

      Returns:
      true if the pattern matches a prefix of the region starting at from

    • reset

      public Matcher reset()
      Resets this matcher. The region is restored to [0, input.length()), anchoringBounds is set to true, and transparentBounds is set to false — matching JDK reset() semantics.
      Returns:
      this matcher

    • region

      public Matcher region(int start, int end)
      Sets the limits of this matcher's region.

      All subsequent match operations search only within [start, end) of the full input. The search cursor is reset to start, and all previous match state is cleared. The anchoring and transparent bounds flags are not changed.

      Parameters:
      start - the inclusive start of the new region; must satisfy 0 <= start <= input.length()
      end - the exclusive end of the new region; must satisfy start <= end <= input.length()
      Returns:
      this matcher
      Throws:
      IndexOutOfBoundsException - if any bound is outside the valid range

    • regionStart

      public int regionStart()
      Returns the start (inclusive) of this matcher's region.
      Returns:
      the region start; 0 by default

    • regionEnd

      public int regionEnd()
      Returns the end (exclusive) of this matcher's region.
      Returns:
      the region end; input.length() by default

    • useAnchoringBounds

      public Matcher useAnchoringBounds(boolean b)
      Sets whether anchors (^, $, \A, \z) treat the region boundaries as the start/end of input.

      When b is true (the default), anchors are evaluated relative to the current region. When false, anchors are evaluated against the full input string.

      Parameters:
      b - true to enable anchoring bounds, false to disable
      Returns:
      this matcher

    • hasAnchoringBounds

      public boolean hasAnchoringBounds()
      Returns whether this matcher uses anchoring bounds.
      Returns:
      true if anchoring bounds are enabled; true by default

    • useTransparentBounds

      public Matcher useTransparentBounds(boolean b)
      Sets whether lookahead and lookbehind assertions can see characters outside the region.

      When b is false (the default), lookahead is blocked at regionEnd and lookbehind is blocked at regionStart. When true, assertions see the full input.

      Parameters:
      b - true to enable transparent bounds, false to disable
      Returns:
      this matcher

    • hasTransparentBounds

      public boolean hasTransparentBounds()
      Returns whether this matcher uses transparent bounds.
      Returns:
      true if transparent bounds are enabled; false by default

    • hitEnd

      public boolean hitEnd()
      Returns true if the end of input was hit by the search engine in the last match operation performed by this matcher.

      Returns true when:

      • the last operation was matches() (any result — the engine always spans [from, to]);
      • the last operation returned true and the match end equals the region boundary to (more input could extend the match); or
      • the last operation returned false and the engine scanned input up to the region boundary before concluding no match exists (more input could produce one).

      Returns false when:

      • no match operation has been performed since the last reset();
      • the last operation returned true and the match end is strictly inside the region (more input cannot change the found match); or
      • the last operation returned false and the engine determined no match was possible without reaching the region end — for example, a start-anchored pattern like ^abc applied to "xyz" fails at position 0.
      Returns:
      true if the end of input was hit during the last operation

    • hasMatch

      public boolean hasMatch()
      Returns whether the last match operation succeeded.

      Returns false if no match has been attempted or the last attempt failed. Mirrors Java 21's MatchResult.hasMatch().

      Returns:
      true if the last find or matches call found a match

    • start

      public int start()
      Returns the start index of the previous match.
      Returns:
      the start index
      Throws:
      IllegalStateException - if no match has been attempted yet

    • end

      public int end()
      Returns the end index (exclusive) of the previous match.
      Returns:
      the end index
      Throws:
      IllegalStateException - if no match has been attempted yet

    • start

      public int start(int group)
      Returns the start index of the subsequence captured by the given group during the previous match operation.
      Parameters:
      group - the 1-based capturing group index; 0 returns the match start
      Returns:
      the start index of the captured group, or -1 if the group did not match
      Throws:
      IllegalStateException - if no match has been attempted or no match found
      IndexOutOfBoundsException - if group is out of range

    • end

      public int end(int group)
      Returns the end index (exclusive) of the subsequence captured by the given group during the previous match operation.
      Parameters:
      group - the 1-based capturing group index; 0 returns the match end
      Returns:
      the end index (exclusive) of the captured group, or -1 if the group did not match
      Throws:
      IllegalStateException - if no match has been attempted or no match found
      IndexOutOfBoundsException - if group is out of range

    • group

      public String group()
      Returns the input subsequence matched by the previous match operation.
      Returns:
      the matched subsequence; never null
      Throws:
      IllegalStateException - if no match has been attempted yet

    • group

      public String group(int group)
      Returns the input subsequence captured by the given group during the previous match operation.
      Parameters:
      group - the 1-based group index; 0 returns the whole match
      Returns:
      the captured substring, or null if the group did not participate in the match
      Throws:
      IllegalStateException - if no match has been performed or no match found
      IndexOutOfBoundsException - if group is out of range

    • group

      public String group(String name)
      Returns the input subsequence captured by the named group during the previous match operation.
      Parameters:
      name - the capturing group name; must not be null
      Returns:
      the captured substring, or null if the group did not participate in the match
      Throws:
      IllegalStateException - if no match has been performed or no match found
      IllegalArgumentException - if name does not correspond to a named group

    • start

      public int start(String name)
      Returns the start index of the subsequence captured by the named group during the previous match operation.
      Parameters:
      name - the capturing group name; must not be null
      Returns:
      the start index of the named group, or -1 if the group did not participate
      Throws:
      IllegalStateException - if no match has been performed or no match found
      IllegalArgumentException - if name does not correspond to a named group

    • end

      public int end(String name)
      Returns the end index (exclusive) of the subsequence captured by the named group during the previous match operation.
      Parameters:
      name - the capturing group name; must not be null
      Returns:
      the end index (exclusive) of the named group, or -1 if the group did not participate
      Throws:
      IllegalStateException - if no match has been performed or no match found
      IllegalArgumentException - if name does not correspond to a named group

    • groupCount

      public int groupCount()
      Returns the number of capturing groups in this matcher's pattern.

      This value is determined solely by the compiled pattern and does not depend on whether a match has been found. This mirrors the contract of java.util.regex.Matcher#groupCount().

      Returns:
      the number of capturing groups; zero if the pattern has none

    • namedGroups

      public Map<String,Integer> namedGroups()
      Returns an unmodifiable map from named capturing group names to their 1-based indices.

      Derived from the pattern's metadata. Returns an empty map if the pattern has no named groups.

      Returns:
      an unmodifiable map of group name to 1-based index; never null

    • usePattern

      public Matcher usePattern(Pattern newPattern)
      Changes the pattern used by this matcher to find matches in the input.

      This is a partial reset. The last match result is discarded and the append position is reset to zero. The input, the current region (regionStart, regionEnd), the region bounds flags (anchoringBounds, transparentBounds), the current search cursor (from), and the last-match-end position (lastMatchEnd) are all preserved. The next find() call continues from wherever the cursor was.

      This matches the contract of java.util.regex.Matcher#usePattern(Pattern).

      Parameters:
      newPattern - the new pattern; must not be null
      Returns:
      this matcher
      Throws:
      NullPointerException - if newPattern is null

    • replaceAll

      public String replaceAll(String replacement)
      Replaces every subsequence of the input sequence that matches the pattern with the given replacement string.

      Resets the matcher before searching, mirroring JDK semantics.

      Parameters:
      replacement - the replacement string; must not be null
      Returns:
      the resulting string with all matches replaced
      Throws:
      NullPointerException - if replacement is null

    • replaceAll

      public String replaceAll(Function<MatchResult,String> replacer)
      Replaces every subsequence of the input that matches the pattern with the string produced by applying replacer to each MatchResult.

      Resets the matcher before searching, mirroring JDK semantics.

      Parameters:
      replacer - a function mapping each match result to a replacement string; must not be null
      Returns:
      the resulting string with all matches replaced
      Throws:
      NullPointerException - if replacer is null

    • replaceFirst

      public String replaceFirst(String replacement)
      Resets the matcher, finds the first match, replaces it with replacement, and returns the result. Returns the input unchanged if no match is found.
      Parameters:
      replacement - the replacement string; must not be null
      Returns:
      the resulting string with the first match replaced, or the original input if no match
      Throws:
      NullPointerException - if replacement is null

    • replaceFirst

      public String replaceFirst(Function<MatchResult,String> replacer)
      Resets the matcher, finds the first match, applies replacer to produce a replacement string, and returns the result. Returns the input unchanged if no match.
      Parameters:
      replacer - a function mapping the match result to a replacement string; must not be null
      Returns:
      the resulting string with the first match replaced, or the original input if no match
      Throws:
      NullPointerException - if replacer is null

    • appendReplacement

      public Matcher appendReplacement(StringBuilder sb, String replacement)
      Appends the input between lastAppendPos and start() to sb, then appends replacement. Advances lastAppendPos to end().

      Intended for use in a loop with appendTail(StringBuilder).

      Parameters:
      sb - the string builder to append to; must not be null
      replacement - the replacement string to append; must not be null
      Returns:
      this matcher
      Throws:
      NullPointerException - if sb or replacement is null
      IllegalStateException - if no match has been found

    • appendReplacement

      public Matcher appendReplacement(StringBuffer sb, String replacement)
      Appends the input between lastAppendPos and start() to sb, then appends the processed replacement string. Advances lastAppendPos to end().

      Group references ($1, ${name}) and escape sequences (\\, \$) in the replacement are expanded by applyReplacement(String).

      Parameters:
      sb - the string buffer to append to; must not be null
      replacement - the replacement string; must not be null
      Returns:
      this matcher
      Throws:
      NullPointerException - if sb or replacement is null
      IllegalStateException - if no match has been found
      IllegalArgumentException - if replacement contains an illegal group reference syntax
      IndexOutOfBoundsException - if replacement references a group that does not exist

    • appendTail

      public StringBuilder appendTail(StringBuilder sb)
      Appends the remaining input from lastAppendPos to the end of the input to sb.
      Parameters:
      sb - the string builder to append to; must not be null
      Returns:
      sb
      Throws:
      NullPointerException - if sb is null

    • appendTail

      public StringBuffer appendTail(StringBuffer sb)
      Appends the remaining input from lastAppendPos to the end of the input to sb.
      Parameters:
      sb - the string buffer to append to; must not be null
      Returns:
      sb
      Throws:
      NullPointerException - if sb is null

    • quoteReplacement

      public static String quoteReplacement(String s)
      Returns a string in which each metacharacter (\ and $) in s is escaped, producing a replacement string that is treated as entirely literal by appendReplacement(StringBuilder, String), replaceAll(String), and replaceFirst(String).

      This is the inverse of applyReplacement(String) for pure-literal input: applyReplacement(quoteReplacement(s)) returns s for any string s and any match state.

      This method is a static utility and has no effect on matcher state.

      Parameters:
      s - the string to quote; must not be null
      Returns:
      the quoted string; never null
      Throws:
      NullPointerException - if s is null

    • results

      public Stream<MatchResult> results()
      Returns a lazily-evaluated stream of all non-overlapping matches in the input from the current position.

      Resets the matcher first to ensure consistent behaviour, then produces one MatchResult snapshot per match. The stream terminates when find() returns false.

      Returns:
      a stream of match results; never null

    • toMatchResult

      public MatchResult toMatchResult()
      Returns the MatchResult for the last match operation.

      The returned snapshot is immutable: subsequent find/matches calls do not affect it. Groups 0 through groupCount() are accessible via start(n), end(n), and group(n).

      If no match has been attempted, the returned result reports hasMatch() == false and all start/end/group accessors return -1 or null. This mirrors the behaviour of java.util.regex.Matcher#toMatchResult() in Java 20+.

      Returns:
      an immutable MatchResult; never null