java.util.regex

Class Matcher

public final class Matcher extends Object implements MatchResult

Instance of a regular expression applied to a char sequence.

Since: 1.4

Method Summary
MatcherappendReplacement(StringBuffer sb, String replacement)
StringBufferappendTail(StringBuffer sb)
intend()
intend(int group)
booleanfind()
booleanfind(int start)
Stringgroup()
Stringgroup(int group)
intgroupCount()
booleanhasAnchoringBounds()
Returns true if the matcher will honour the use of the anchoring bounds: {@code ^}, {@code \A}, {@code \Z}, {@code \z} and {@code $}.
booleanhasTransparentBounds()
Returns true if the bounds of the region marked by regionStart and regionEnd are transparent.
booleanhitEnd()
booleanlookingAt()
booleanmatches()
Attempts to match the entire input sequence against the pattern.
Patternpattern()
Returns the Pattern that is interpreted by this Matcher
Matcherregion(int start, int end)

Defines the region of the input on which to match.

intregionEnd()
The end of the region on which to perform matches (exclusive).
intregionStart()
The start of the region on which to perform matches (inclusive).
StringreplaceAll(String replacement)
StringreplaceFirst(String replacement)
Matcherreset()
Resets the internal state of the matcher, including resetting the region to its default state of encompassing the whole input.
Matcherreset(CharSequence input)
Resets the internal state of the matcher, including resetting the region to its default state of encompassing the whole input.
intstart()
intstart(int group)
MatchResulttoMatchResult()
Returns a read-only snapshot of the current state of the Matcher as a MatchResult.
StringtoString()
MatcheruseAnchoringBounds(boolean useAnchors)
Enables or disables the use of the anchoring bounds: {@code ^}, {@code \A}, {@code \Z}, {@code \z} and {@code $}.
MatcheruseTransparentBounds(boolean transparent)
Sets the transparency of the bounds of the region marked by regionStart and regionEnd.

Method Detail

appendReplacement

public Matcher appendReplacement(StringBuffer sb, String replacement)

Parameters: sb The target string buffer replacement The replacement string

Throws: IllegalStateException If no match has yet been attempted, or if the previous match operation failed IndexOutOfBoundsException If the replacement string refers to a capturing group that does not exist in the pattern

appendTail

public StringBuffer appendTail(StringBuffer sb)

Parameters: sb The target string buffer

end

public int end()

Throws: IllegalStateException If no match has yet been attempted, or if the previous match operation failed

end

public int end(int group)

Parameters: group The index of a capturing group in this matcher's pattern

Throws: IllegalStateException If no match has yet been attempted, or if the previous match operation failed IndexOutOfBoundsException If the replacement string refers to a capturing group that does not exist in the pattern

find

public boolean find()

find

public boolean find(int start)

Parameters: start The index to start the new pattern matching

Throws: IndexOutOfBoundsException If the replacement string refers to a capturing group that does not exist in the pattern

group

public String group()

Throws: IllegalStateException If no match has yet been attempted, or if the previous match operation failed

group

public String group(int group)

Parameters: group The index of a capturing group in this matcher's pattern

Throws: IllegalStateException If no match has yet been attempted, or if the previous match operation failed IndexOutOfBoundsException If the replacement string refers to a capturing group that does not exist in the pattern

groupCount

public int groupCount()

hasAnchoringBounds

public boolean hasAnchoringBounds()
Returns true if the matcher will honour the use of the anchoring bounds: {@code ^}, {@code \A}, {@code \Z}, {@code \z} and {@code $}. By default, the anchors are used. Note that the effect of the anchors is also affected by hasTransparentBounds.

Returns: true if the matcher will attempt to match the anchoring bounds.

Since: 1.5

See Also: Matcher hasTransparentBounds

hasTransparentBounds

public boolean hasTransparentBounds()
Returns true if the bounds of the region marked by regionStart and regionEnd are transparent. When these bounds are transparent, the matching process can look beyond them to perform lookahead, lookbehind and boundary matching operations. By default, the bounds are opaque.

Returns: true if the bounds of the matching region are transparent.

Since: 1.5

See Also: Matcher Matcher regionStart regionEnd

hitEnd

public boolean hitEnd()

Returns: True if and only if the matcher hit the end of input.

Since: 1.5

lookingAt

public boolean lookingAt()

matches

public boolean matches()
Attempts to match the entire input sequence against the pattern. If the match succeeds then more information can be obtained via the start, end, and group methods.

See Also: start end group

pattern

public Pattern pattern()
Returns the Pattern that is interpreted by this Matcher

region

public Matcher region(int start, int end)

Defines the region of the input on which to match. By default, the Matcher attempts to match the whole string (from 0 to the length of the input), but a region between {@code start} (inclusive) and {@code end} (exclusive) on which to match may instead be defined using this method.

The behaviour of region matching is further affected by the use of transparent or opaque bounds (see Matcher) and whether or not anchors ({@code ^} and {@code $}) are in use (see Matcher). With transparent bounds, the matcher is aware of input outside the bounds set by this method, whereas, with opaque bounds (the default) only the input within the bounds is used. The use of anchors are affected by this setting; with transparent bounds, anchors will match the beginning of the real input, while with opaque bounds they match the beginning of the region. Matcher can be used to turn on or off the matching of anchors.

Parameters: start the start of the region (inclusive). end the end of the region (exclusive).

Returns: a reference to this matcher.

Throws: IndexOutOfBoundsException if either {@code start} or {@code end} are less than zero, if either {@code start} or {@code end} are greater than the length of the input, or if {@code start} is greater than {@code end}.

Since: 1.5

See Also: regionStart regionEnd hasTransparentBounds Matcher hasAnchoringBounds Matcher

regionEnd

public int regionEnd()
The end of the region on which to perform matches (exclusive).

Returns: the end index of the region.

Since: 1.5

See Also: Matcher regionStart

regionStart

public int regionStart()
The start of the region on which to perform matches (inclusive).

Returns: the start index of the region.

Since: 1.5

See Also: #see #regionEnd()

replaceAll

public String replaceAll(String replacement)

Parameters: replacement The replacement string

replaceFirst

public String replaceFirst(String replacement)

Parameters: replacement The replacement string

reset

public Matcher reset()
Resets the internal state of the matcher, including resetting the region to its default state of encompassing the whole input. The state of hasTransparentBounds and hasAnchoringBounds are unaffected.

Returns: a reference to this matcher.

See Also: regionStart regionEnd hasTransparentBounds hasAnchoringBounds

reset

public Matcher reset(CharSequence input)
Resets the internal state of the matcher, including resetting the region to its default state of encompassing the whole input. The state of hasTransparentBounds and hasAnchoringBounds are unaffected.

Parameters: input The new input character sequence.

Returns: a reference to this matcher.

See Also: regionStart regionEnd hasTransparentBounds hasAnchoringBounds

start

public int start()

Returns: the index of a capturing group in this matcher's pattern

Throws: IllegalStateException If no match has yet been attempted, or if the previous match operation failed

start

public int start(int group)

Parameters: group The index of a capturing group in this matcher's pattern

Throws: IllegalStateException If no match has yet been attempted, or if the previous match operation failed IndexOutOfBoundsException If the replacement string refers to a capturing group that does not exist in the pattern

toMatchResult

public MatchResult toMatchResult()
Returns a read-only snapshot of the current state of the Matcher as a MatchResult. Any subsequent changes to this instance are not reflected in the returned MatchResult.

Returns: a MatchResult instance representing the current state of the Matcher.

toString

public String toString()

Returns: A string expression of this matcher.

useAnchoringBounds

public Matcher useAnchoringBounds(boolean useAnchors)
Enables or disables the use of the anchoring bounds: {@code ^}, {@code \A}, {@code \Z}, {@code \z} and {@code $}. By default, their use is enabled. When disabled, the matcher will not attempt to match the anchors.

Parameters: useAnchors true if anchoring bounds should be used.

Returns: a reference to this matcher.

Since: 1.5

See Also: hasAnchoringBounds

useTransparentBounds

public Matcher useTransparentBounds(boolean transparent)
Sets the transparency of the bounds of the region marked by regionStart and regionEnd. A value of {@code true} makes the bounds transparent, so the matcher can see beyond them to perform lookahead, lookbehind and boundary matching operations. A value of {@code false} (the default) makes the bounds opaque, restricting the match to the input region denoted by regionStart and regionEnd.

Parameters: transparent true if the bounds should be transparent.

Returns: a reference to this matcher.

Since: 1.5

See Also: hasTransparentBounds Matcher regionStart regionEnd