Overview Package Class Use Source Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

java.util.regex

Class Matcher

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()
int
end(int group)
boolean
find()
boolean
find(int start)
String
group()
String
group(int 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
static String
quoteReplacement(String s)
Returns a literalized string of s where characters $ and \\ are escaped.
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()
int
start(int group)
MatchResult
toMatchResult()
Returns a read-only snapshot of the current state of the Matcher as a MatchResult.
String
toString()
Matcher
useAnchoringBounds(boolean useAnchors)
Enables or disables the use of the anchoring bounds: ^, \A, \Z, \z and $.
Matcher
usePattern(Pattern newPattern)
Changes the pattern used by the Matcher to the one specified.
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, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

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

groupCount

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

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

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

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

quoteReplacement

public static String quoteReplacement(String s)
Returns a literalized string of s where characters $ and \\ are escaped.
Parameters:
s - the string to literalize.
Returns:
the literalized string.
Since:
1.5

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)

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

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

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()
Overrides:
toString in interface Object
Returns:
A string expression of this matcher.

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

usePattern

public Matcher usePattern(Pattern newPattern)
Changes the pattern used by the Matcher to the one specified. Existing match information is lost, but the input and the matcher's position within it is retained.
Parameters:
newPattern - the new pattern to use.
Returns:
this matcher.
Throws:
IllegalArgumentException - if newPattern is null.
Since:
1.5

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()
Matcher.java -- Instance of a regular expression applied to a char sequence. Copyright (C) 2002, 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About