OpenJDK 27 · java.util.regex.Matcher · APIdia, the JavaDoc alternative

An engine that performs match operations on a character sequence by interpreting a Pattern.

A matcher is created from a pattern by invoking the pattern's matcher method. Once created, a matcher can be used to perform three different kinds of match operations:

The matches method attempts to match the entire input sequence against the pattern.
The lookingAt method attempts to match the input sequence, starting at the beginning, against the pattern.
The find method scans the input sequence looking for the next subsequence that matches the pattern.

Each of these methods returns a boolean indicating success or failure. More information about a successful match can be obtained by querying the state of the matcher.

A matcher finds matches in a subset of its input called the region. By default, the region contains all of the matcher's input. The region can be modified via the region method and queried via the regionStart and regionEnd methods. The way that the region boundaries interact with some pattern constructs can be changed. See useAnchoringBounds and useTransparentBounds for more details.

This class also defines methods for replacing matched subsequences with new strings whose contents can, if desired, be computed from the match result. The appendReplacement and appendTail methods can be used in tandem in order to collect the result into an existing string buffer or string builder. Alternatively, the more convenient replaceAll method can be used to create a string in which every matching subsequence in the input sequence is replaced.

The explicit state of a matcher includes the start and end indices of the most recent successful match. It also includes the start and end indices of the input subsequence captured by each capturing group in the pattern as well as a total count of such subsequences. As a convenience, methods are also provided for returning these captured subsequences in string form.

The explicit state of a matcher is initially undefined; attempting to query any part of it before a successful match will cause an IllegalStateException to be thrown. The explicit state of a matcher is recomputed by every match operation.

The implicit state of a matcher includes the input character sequence as well as the append position, which is initially zero and is updated by the appendReplacement method.

A matcher may be reset explicitly by invoking its reset() method or, if a new input sequence is desired, its reset(CharSequence) method. Resetting a matcher discards its explicit state information and sets the append position to zero.

Instances of this class are not safe for use by multiple concurrent threads.

Modifier and Type	Class and Description
private static class	Matcher.ImmutableMatchResult

Modifier and Type	Field and Description
pack-priv int	acceptMode
pack-priv boolean	anchoringBounds If anchoringBounds is true then the boundaries of this matcher's region match anchors such as ^ and $.
pack-priv static final int	ENDANCHOR Matcher state used by the last node.
pack-priv int	first The range of string that last matched the pattern.
pack-priv int	from The range within the sequence that is to be matched.
pack-priv int[]	groups The storage used by groups.
pack-priv boolean	hitEnd Boolean indicating whether or not more input could change the results of the last match.
pack-priv int	last The range of string that last matched the pattern.
pack-priv int	lastAppendPosition The index of the last position appended in a substitution.
pack-priv int[]	locals Storage used by nodes to tell what repetition they are on in a pattern, and where groups begin.
pack-priv IntHashSet[]	localsPos Storage used by top greedy Loop node to store a specific hash set to keep the beginning index of the failed repetition match.
pack-priv int	lookbehindTo Lookbehind uses this value to ensure that the subexpression match ends at the point where the lookbehind was encountered.
pack-priv int	modCount Number of times this matcher's state has been modified
private Map<String, Integer>	namedGroups
pack-priv static final int	NOANCHOR
pack-priv int	oldLast The end index of what matched in the last match operation.
pack-priv Pattern	parentPattern The Pattern object that created this Matcher.
pack-priv boolean	requireEnd Boolean indicating whether or not more input could change a positive match into a negative one.
pack-priv CharSequence	text The original string being matched.
pack-priv int	to The range within the sequence that is to be matched.
pack-priv boolean	transparentBounds If transparentBounds is true then the boundaries of this matcher's region are transparent to lookahead, lookbehind, and boundary matching constructs that try to see beyond them.

Access	Constructor and Description
pack-priv	Matcher() No default constructor.
pack-priv	Matcher(Pattern parent, CharSequence text) All matchers have the state used by Pattern during a match.

Method Summary

Modifier and Type	Method and Description
private void	appendExpandedReplacement(Appendable app, String replacement) Processes replacement string to replace group references with groups.
public Matcher	Returns: This matcher appendReplacement(StringBuffer The target string buffer sb, String The replacement string replacement) Implements a non-terminal append-and-replace step.
public Matcher	Returns: This matcher appendReplacement(StringBuilder The target string builder sb, String The replacement string replacement) Implements a non-terminal append-and-replace step.
public StringBuffer	Returns: The target string buffer appendTail(StringBuffer The target string buffer sb) Implements a terminal append-and-replace step.
public StringBuilder	Returns: The target string builder appendTail(StringBuilder The target string builder sb) Implements a terminal append-and-replace step.
pack-priv char	Returns: A char from the specified index charAt(int i) Returns this matcher's input character at index i.
private void	checkGroup(int group)
private void	checkMatch()
public int	Returns: The offset after the last character matched end() Implements java.util.regex.MatchResult.end. Returns the offset after the last character matched.
public int	Returns: The offset after the last character captured by the group, or `-1` if the match was successful but the group itself did not match anything end(int The index of a capturing group in this matcher's pattern group) Implements java.util.regex.MatchResult.end. Returns the offset after the last character of the subsequence captured by the given group during the previous match operation.
public int	Returns: The offset after the last character captured by the group, or `-1` if the match was successful but the group itself did not match anything end(String The name of a named-capturing group in this matcher's pattern name) Overrides default java.util.regex.MatchResult.end. Returns the offset after the last character of the subsequence captured by the given named-capturing group during the previous match operation.
public boolean	Returns: `true` if, and only if, a subsequence of the input sequence matches this matcher's pattern find() Attempts to find the next subsequence of the input sequence that matches the pattern.
public boolean	Returns: `true` if, and only if, a subsequence of the input sequence starting at the given index matches this matcher's pattern find(int the index to start searching for a match start) Resets this matcher and then attempts to find the next subsequence of the input sequence that matches the pattern, starting at the specified index.
pack-priv int	Returns: the index of the named-capturing group getMatchedGroupIndex(String name) Returns the group index of the matched capturing group.
pack-priv CharSequence	Returns: A String generated from this matcher's input getSubSequence(int the beginning index, inclusive beginIndex, int the ending index, exclusive endIndex) Generates a String from this matcher's input in the specified range.
pack-priv int	Returns: the index after the last character in the text getTextLength() Returns the end index of the text.
public String	Returns: The (possibly empty) subsequence matched by the previous match, in string form or `null` if a matcher with a previous match has changed its `java.util.regex.Pattern`, but no new match has yet been attempted group() Implements java.util.regex.MatchResult.group. Returns the input subsequence matched by the previous match.
public String	Returns: The (possibly empty) subsequence captured by the group during the previous match, or `null` if the group failed to match part of the input or if the matcher's `java.util.regex.Pattern` has changed after a successful match, but a new match has not been attempted group(int The index of a capturing group in this matcher's pattern group) Implements java.util.regex.MatchResult.group. Returns the input subsequence captured by the given group during the previous match operation.
public String	Returns: The (possibly empty) subsequence captured by the named group during the previous match, or `null` if the group failed to match part of the input group(String The name of a named-capturing group in this matcher's pattern name) Overrides default java.util.regex.MatchResult.group. Returns the input subsequence captured by the given named-capturing group during the previous match operation.
public int	Returns: The number of capturing groups in this matcher's pattern groupCount() Implements java.util.regex.MatchResult.groupCount. Returns the number of capturing groups in this matcher's pattern.
public boolean	Returns: `true` iff this matcher is using anchoring bounds, `false` otherwise. hasAnchoringBounds() Queries the anchoring of region bounds for this matcher.
public boolean	hasMatch() Overrides default java.util.regex.MatchResult.hasMatch. Returns whether `this` contains a valid match from a previous match or find operation.
public boolean	Returns: `true` iff this matcher is using transparent bounds, `false` otherwise. hasTransparentBounds() Queries the transparency of region bounds for this matcher.
public boolean	Returns: true iff the end of input was hit in the last match; false otherwise hitEnd() Returns true if the end of input was hit by the search engine in the last match operation performed by this matcher.
public boolean	Returns: `true` if, and only if, a prefix of the input sequence matches this matcher's pattern lookingAt() Attempts to match the input sequence, starting at the beginning of the region, against the pattern.
pack-priv boolean	match(int from, int anchor) Initiates a search for an anchored match to a Pattern within the given bounds.
public boolean	Returns: `true` if, and only if, the entire region sequence matches this matcher's pattern matches() Attempts to match the entire region against the pattern.
private int	maxEnd()
private int	minStart()
public Map<String, Integer>	namedGroups() Overrides default java.util.regex.MatchResult.namedGroups. Returns an unmodifiable map from capturing group names to group numbers.
public Pattern	Returns: The pattern for which this matcher was created pattern() Returns the pattern that is interpreted by this matcher.
public static String	Returns: A literal string replacement quoteReplacement(String The string to be literalized s) Returns a literal replacement `String` for the specified `String`.
public Matcher	Returns: this matcher region(int The index to start searching at (inclusive) start, int The index to end searching at (exclusive) end) Sets the limits of this matcher's region.
public int	Returns: the ending point of this matcher's region regionEnd() Reports the end index (exclusive) of this matcher's region.
public int	Returns: The starting point of this matcher's region regionStart() Reports the start index of this matcher's region.
public String	Returns: The string constructed by replacing each matching subsequence by the replacement string, substituting captured subsequences as needed replaceAll(String The replacement string replacement) Replaces every subsequence of the input sequence that matches the pattern with the given replacement string.
public String	Returns: The string constructed by replacing each matching subsequence with the result of applying the replacer function to that matched subsequence, substituting captured subsequences as needed. replaceAll(Function<MatchResult, String> The function to be applied to the match result of this matcher that returns a replacement string. replacer) Replaces every subsequence of the input sequence that matches the pattern with the result of applying the given replacer function to the match result of this matcher corresponding to that subsequence.
public String	Returns: The string constructed by replacing the first matching subsequence by the replacement string, substituting captured subsequences as needed replaceFirst(String The replacement string replacement) Replaces the first subsequence of the input sequence that matches the pattern with the given replacement string.
public String	Returns: The string constructed by replacing the first matching subsequence with the result of applying the replacer function to the matched subsequence, substituting captured subsequences as needed. replaceFirst(Function<MatchResult, String> The function to be applied to the match result of this matcher that returns a replacement string. replacer) Replaces the first subsequence of the input sequence that matches the pattern with the result of applying the given replacer function to the match result of this matcher corresponding to that subsequence.
public boolean	Returns: true iff more input could change a positive match into a negative one. requireEnd() Returns true if more input could change a positive match into a negative one.
public Matcher	Returns: This matcher reset() Resets this matcher.
public Matcher	Returns: This matcher reset(CharSequence The new input character sequence input) Resets this matcher with a new input sequence.
public Stream<MatchResult>	Returns: a sequential stream of match results. results() Returns a stream of match results for each subsequence of the input sequence that matches the pattern.
pack-priv boolean	search(int from) Initiates a search to find a Pattern within the given bounds.
public int	Returns: The index of the first character matched start() Implements java.util.regex.MatchResult.start. Returns the start index of the previous match.
public int	Returns: The index of the first character captured by the group, or `-1` if the match was successful but the group itself did not match anything start(int The index of a capturing group in this matcher's pattern group) Implements java.util.regex.MatchResult.start. Returns the start index of the subsequence captured by the given group during the previous match operation.
public int	Returns: The index of the first character captured by the group, or `-1` if the match was successful but the group itself did not match anything start(String The name of a named-capturing group in this matcher's pattern name) Overrides default java.util.regex.MatchResult.start. Returns the start index of the subsequence captured by the given named-capturing group during the previous match operation.
public MatchResult	Returns: a `MatchResult` with the state of this matcher toMatchResult() Returns the match state of this matcher as a `MatchResult`.
public String	Returns: The string representation of this matcher toString() Overrides java.lang.Object.toString. Returns the string representation of this matcher.
public Matcher	Returns: this matcher useAnchoringBounds(boolean a boolean indicating whether or not to use anchoring bounds. b) Sets the anchoring of region bounds for this matcher.
public Matcher	Returns: This matcher usePattern(Pattern The new pattern used by this matcher newPattern) Changes the `Pattern` that this `Matcher` uses to find matches with.
public Matcher	Returns: this matcher useTransparentBounds(boolean a boolean indicating whether to use opaque or transparent regions b) Sets the transparency of region bounds for this matcher.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

public final Class Matcher

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary