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.
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
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.
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
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. Callingmatches()orlookingAt()betweenfind()calls changes that position; callreset()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
\\bora*).find()advances one position after an empty match, so loops still end. group()returnsnullfor 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
CharSequencesuch as aStringBuilderwhile matching, results are unspecified. - Capture a snapshot with
toMatchResult()orresults()if you need matches after continuing the search. - Named groups: see named capture groups.