Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Text, Formatting and Regex

The Matcher class

Reference for java.util.regex.Matcher: find, matches, lookingAt, capturing groups, start and end offsets, reset, regions and the IllegalStateException trap.

A java.util.regex.Matcher applies a Pattern to one input string and remembers where it is. It is the stateful half of the regex API: you move it forward with find(), then read what it matched with group(), start() and end(). Create one with pattern.matcher(text).

The most common mistake is reading results before a successful match. group() and friends throw IllegalStateException ("No match found") unless the last find(), matches() or lookingAt() call returned true.

Java
Matcher m = Pattern.compile("(\\w+)@(\\w+)\\.com").matcher("mail [email protected] now");
if (m.find()) {
    System.out.println(m.group(1) + " at " + m.group(2));   // ann at site
}

Try it

Java find(), groups and offsets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java matches vs lookingAt vs find, reset and regions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public final class Matcher implements MatchResult
Matcher matcher = pattern.matcher(CharSequence input);
Method Description
matches() true if the entire region matches.
lookingAt() true if the region starts with a match.
find() Finds the next match, starting after the previous one.
find(int start) Resets, then finds from the given index.
group(), group(int), group(String) Text of the whole match, a numbered group or a named group. null if the group took no part.
start(), end(), start(int), end(int) Offsets of the match or group; -1 for a group that did not match.
groupCount() Number of capturing groups in the pattern (not counting group 0).
reset(), reset(CharSequence) Clear state; optionally attach new input.
region(start, end) Limits matching to part of the input.
hitEnd(), requireEnd() Whether the engine reached the end of input while matching.
toMatchResult() An immutable snapshot of the last match.
results() Stream of MatchResult (Java 9).
replaceAll, replaceFirst, appendReplacement, appendTail Replacement; see replacement.

Throws: IllegalStateException when reading match data without a successful match; IllegalArgumentException for an unknown group name; IndexOutOfBoundsException for a bad group number.

Usage notes

  • Each find() continues where the last stopped. Calling matches() or lookingAt() between find() calls changes that position; call reset() for a clean start.
  • Group numbering follows the opening parentheses, left to right. Non-capturing (?:...) groups are not counted.
  • Zero-length matches are possible (for example \\b or a*). find() advances one position after an empty match, so loops still end.
  • group() returns null for an optional group that did not participate, so check before calling methods on it.
  • Not thread-safe. A matcher keeps mutable state; never share it between threads.
  • A matcher keeps a reference to the input. If you change a mutable CharSequence such as a StringBuilder while matching, results are unspecified.
  • Capture a snapshot with toMatchResult() or results() if you need matches after continuing the search.
  • Named groups: see named capture groups.