java.util.regex
Class Matcher

java.lang.Object
  extended by java.util.regex.Matcher
All Implemented Interfaces:
MatchResult

public final class Matcher
extends Object
implements MatchResult

Instance of a regular expression applied to a char sequence.

Since:
1.4

Method Summary
 Matcher appendReplacement(StringBuffer sb, String replacement)
           
 StringBuffer appendTail(StringBuffer sb)
           
 int end()
          Returns the index just after the last matched character.
 int end(int group)
          Returns the index just after the last matched character of the given sub-match group.
 boolean find()
           
 boolean find(int start)
           
 String group()
          Returns the substring of the input which was matched.
 String group(int group)
          Returns the substring of the input which was matched by the given sub-match group.
 int groupCount()
          Returns the number of sub-match groups in the matching pattern.
 boolean hasAnchoringBounds()
          Returns true if the matcher will honour the use of the anchoring bounds: ^, \A, \Z, \z and $.
 boolean hasTransparentBounds()
          Returns true if the bounds of the region marked by regionStart() and regionEnd() are transparent.
 boolean hitEnd()
           
 boolean lookingAt()
           
 boolean matches()
          Attempts to match the entire input sequence against the pattern.
 Pattern pattern()
          Returns the Pattern that is interpreted by this Matcher
 Matcher region(int start, int end)
           Defines the region of the input on which to match.
 int regionEnd()
          The end of the region on which to perform matches (exclusive).
 int regionStart()
          The start of the region on which to perform matches (inclusive).
 String replaceAll(String replacement)
           
 String replaceFirst(String replacement)
           
 Matcher reset()
          Resets the internal state of the matcher, including resetting the region to its default state of encompassing the whole input.
 Matcher reset(CharSequence input)
          Resets the internal state of the matcher, including resetting the region to its default state of encompassing the whole input.
 int start()
          Returns the index of the first character of the match.
 int start(int group)
          Returns the index of the first character of the given sub-match group.
 MatchResult toMatchResult()
          Returns a read-only snapshot of the current state of the Matcher as a MatchResult.
 String toString()
          Convert this Object to a human-readable String.
 Matcher useAnchoringBounds(boolean useAnchors)
          Enables or disables the use of the anchoring bounds: ^, \A, \Z, \z and $.
 Matcher useTransparentBounds(boolean transparent)
          Sets the transparency of the bounds of the region marked by regionStart() and regionEnd().
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

appendReplacement

public Matcher appendReplacement(StringBuffer sb,
                                 String replacement)
                          throws IllegalStateException
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
Description copied from interface: MatchResult
Returns the index just after the last matched character.

Specified by:
end in interface MatchResult
Throws:
IllegalStateException - If no match has yet been attempted, or if the previous match operation failed

end

public int end(int group)
        throws IllegalStateException
Description copied from interface: MatchResult
Returns the index just after the last matched character of the given sub-match group.

Specified by:
end in interface MatchResult
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()
Description copied from interface: MatchResult
Returns the substring of the input which was matched.

Specified by:
group in interface MatchResult
Throws:
IllegalStateException - If no match has yet been attempted, or if the previous match operation failed

group

public String group(int group)
             throws IllegalStateException
Description copied from interface: MatchResult
Returns the substring of the input which was matched by the given sub-match group.

Specified by:
group in interface MatchResult
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

replaceFirst

public String replaceFirst(String replacement)
Parameters:
replacement - The replacement string

replaceAll

public String replaceAll(String replacement)
Parameters:
replacement - The replacement string

groupCount

public int groupCount()
Description copied from interface: MatchResult
Returns the number of sub-match groups in the matching pattern.

Specified by:
groupCount in interface MatchResult

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


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()
          throws IllegalStateException
Description copied from interface: MatchResult
Returns the index of the first character of the match.

Specified by:
start in interface MatchResult
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)
          throws IllegalStateException
Description copied from interface: MatchResult
Returns the index of the first character of the given sub-match group.

Specified by:
start in interface MatchResult
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

hitEnd

public boolean hitEnd()
Returns:
True if and only if the matcher hit the end of input.
Since:
1.5

toString

public String toString()
Description copied from class: Object
Convert this Object to a human-readable String. There are no limits placed on how long this String should be or what it should contain. We suggest you make it as intuitive as possible to be able to place it into System.out.println() and such.

It is typical, but not required, to ensure that this method never completes abruptly with a RuntimeException.

This method will be called when performing string concatenation with this object. If the result is null, string concatenation will instead use "null".

The default implementation returns getClass().getName() + "@" + Integer.toHexString(hashCode()).

Overrides:
toString in class Object
Returns:
A string expression of this matcher.
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

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 start (inclusive) and 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 useTransparentBounds(boolean)) and whether or not anchors (^ and $) are in use (see useAnchoringBounds(boolean)). 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. useAnchoringBounds(boolean) 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 start or end are less than zero, if either start or end are greater than the length of the input, or if start is greater than end.
Since:
1.5
See Also:
regionStart(), regionEnd(), hasTransparentBounds(), useTransparentBounds(boolean), hasAnchoringBounds(), useAnchoringBounds(boolean)

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()

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:
region(int,int), regionStart()

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:
useTransparentBounds(boolean), region(int,int), regionStart(), regionEnd()

useTransparentBounds

public Matcher useTransparentBounds(boolean transparent)
Sets the transparency of the bounds of the region marked by regionStart() and regionEnd(). A value of true makes the bounds transparent, so the matcher can see beyond them to perform lookahead, lookbehind and boundary matching operations. A value of 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(), region(int,int), regionStart(), regionEnd()

hasAnchoringBounds

public boolean hasAnchoringBounds()
Returns true if the matcher will honour the use of the anchoring bounds: ^, \A, \Z, \z and $. 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:
useAnchoringBounds(boolean), hasTransparentBounds()

useAnchoringBounds

public Matcher useAnchoringBounds(boolean useAnchors)
Enables or disables the use of the anchoring bounds: ^, \A, \Z, \z and $. 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()

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.