com.google.code.regexp
Class Matcher

java.lang.Object
  com.google.code.regexp.Matcher

All Implemented Interfaces:

MatchResult

public class Matcher
extends Object
implements MatchResult

An engine that performs match operations on a character sequence by interpreting a Pattern. This is a wrapper for Matcher.

Since:

0.1.9

Method Summary

Matcher	appendReplacement(StringBuffer sb, String replacement) Implements a non-terminal append-and-replace step.
StringBuffer	appendTail(StringBuffer sb) Implements a terminal append-and-replace step.
int	end() Returns the offset after the last character matched.
int	end(int group) Returns the offset after the last character of the subsequence captured by the given group during the previous match operation.
int	end(String groupName) Returns the offset after the last character of the subsequence captured by the given named group during the previous match operation.
boolean	equals(Object obj)
boolean	find() Attempts to find the next subsequence of the input sequence that matches the pattern.
boolean	find(int 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.
String	group() Returns the input subsequence matched by the previous match.
String	group(int group) Returns the input subsequence captured by the given group during the previous match operation.
String	group(String groupName) Returns the input subsequence captured by the named group during the previous match operation.
int	groupCount() Returns the number of capturing groups in this matcher's pattern.
boolean	hasAnchoringBounds() Queries the anchoring of region bounds for this matcher.
int	hashCode()
boolean	hasTransparentBounds() Queries the transparency of region bounds for this matcher.
boolean	hitEnd() Returns true if the end of input was hit by the search engine in the last match operation performed by this matcher.
boolean	lookingAt() Attempts to match the input sequence, starting at the beginning of the region, against the pattern.
boolean	matches() Attempts to match the entire region against the pattern.
Map<String,String>	namedGroups() Finds all named groups that exist in the input string.
Pattern	namedPattern() Returns the named pattern that is interpreted by this matcher.
List<String>	orderedGroups() Gets a list of the matches in the order in which they occur in a matching input string
Matcher	region(int start, int end) Sets the limits of this matcher's region.
int	regionEnd() Reports the end index (exclusive) of this matcher's region.
int	regionStart() Reports the start index of this matcher's region.
String	replaceAll(String replacement) Replaces every subsequence of the input sequence that matches the pattern with the given replacement string.
String	replaceFirst(String replacement) Replaces the first subsequence of the input sequence that matches the pattern with the given replacement string.
boolean	requireEnd() Returns true if more input could change a positive match into a negative one.
Matcher	reset() Resets this matcher
Matcher	reset(CharSequence input) Resets this matcher with a new input sequence
Pattern	standardPattern() Returns the pattern that is interpreted by this matcher.
int	start() Returns the start index of the previous match.
int	start(int group) Returns the start index of the subsequence captured by the given group during the previous match operation.
int	start(String groupName) Returns the start index of the subsequence captured by the given named group during the previous match operation.
MatchResult	toMatchResult() Returns the match state of this matcher as a NamedMatchResult.
String	toString()
Matcher	useAnchoringBounds(boolean b) Sets the anchoring of region bounds for this matcher.
Matcher	usePattern(Pattern newPattern) Changes the Pattern that this Matcher uses to find matches with
Matcher	useTransparentBounds(boolean b) Sets the transparency of region bounds for this matcher.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

standardPattern

public Pattern standardPattern()

Returns the pattern that is interpreted by this matcher.

Returns:

the pattern

namedPattern

public Pattern namedPattern()

Returns the named pattern that is interpreted by this matcher.

Returns:

the pattern

usePattern

public Matcher usePattern(Pattern newPattern)

Changes the Pattern that this Matcher uses to find matches with

Parameters:

newPattern - the new pattern

Returns:

this Matcher

reset

public Matcher reset()

Resets this matcher

Returns:

this Matcher

reset

public Matcher reset(CharSequence input)

Resets this matcher with a new input sequence

Resetting a matcher discards all of its explicit state information and sets its append position to zero. The matcher's region is set to the default region, which is its entire character sequence. The anchoring and transparency of this matcher's region boundaries are unaffected

Parameters:

input - The new input character sequence

Returns:

this Matcher

matches

public boolean matches()

Attempts to match the entire region against the pattern.

If the match succeeds then more information can be obtained via the start, end, and group methods.

Returns:

true if, and only if, the entire region sequence matches this matcher's pattern

toMatchResult

public MatchResult toMatchResult()

Returns the match state of this matcher as a NamedMatchResult. The result is unaffected by subsequent operations performed upon this matcher.

Returns:

a NamedMatchResult with the state of this matcher

find

public boolean find()

Attempts to find the next subsequence of the input sequence that matches the pattern.

This method starts at the beginning of this matcher's region, or, if a previous invocation of the method was successful and the matcher has not since been reset, at the first character not matched by the previous match.

If the match succeeds then more information can be obtained via the start, end, and group methods.

Returns:

find

public boolean find(int 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.

If the match succeeds then more information can be obtained via the start, end, and group methods, and subsequent invocations of the find() method will start at the first character not matched by this match.

Parameters:

start - the starting index

Returns:

true if, and only if, a subsequence of the input sequence starting at the given index matches this matcher's pattern

Throws:

IndexOutOfBoundsException - If start is less than zero or if start is greater than the length of the input sequence.

lookingAt

public boolean lookingAt()

Attempts to match the input sequence, starting at the beginning of the region, against the pattern.

Like the matches method, this method always starts at the beginning of the region; unlike that method, it does not require that the entire region be matched.

If the match succeeds then more information can be obtained via the start, end, and group methods.

Returns:

true if, and only if, a prefix of the input sequence matches this matcher's pattern

appendReplacement

public Matcher appendReplacement(StringBuffer sb,
                                 String replacement)

Implements a non-terminal append-and-replace step.

Parameters:

sb - The target string buffer

replacement - The replacement string

Returns:

The target string buffer

appendTail

public StringBuffer appendTail(StringBuffer sb)

Implements a terminal append-and-replace step.

Parameters:

sb - The target string buffer

Returns:

The target string buffer

group

public String group()

Returns the input subsequence matched by the previous match.

Specified by:

group in interface MatchResult

Returns:

The (possibly empty) subsequence matched by the previous match, in string form

group

public String group(int group)

Returns the input subsequence captured by the given group during the previous match operation.

Specified by:

group in interface MatchResult

Parameters:

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

Returns:

the subsequence

Throws:

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

groupCount

public int groupCount()

Returns the number of capturing groups in this matcher's pattern.

Specified by:

groupCount in interface MatchResult

Returns:

The number of capturing groups in this matcher's pattern

orderedGroups

public List<String> orderedGroups()

Gets a list of the matches in the order in which they occur in a matching input string

Returns:

the matches

group

public String group(String groupName)

Returns the input subsequence captured by the named group during the previous match operation.

Parameters:

groupName - name of the capture group

Returns:

the subsequence

Throws:

IndexOutOfBoundsException - if group name not found

namedGroups

public Map<String,String> namedGroups()

Finds all named groups that exist in the input string. This resets the matcher and attempts to match the input against the pre-specified pattern.

Returns:

a map of the group named and matched values (empty if no match found)

start

public int start()

Returns the start index of the previous match.

Specified by:

start in interface MatchResult

Returns:

the start index

start

public int start(int group)

Returns the start index of the subsequence captured by the given group during the previous match operation.

Specified by:

start in interface MatchResult

Parameters:

group - the index of the capture group

Returns:

the index

start

public int start(String groupName)

Returns the start index of the subsequence captured by the given named group during the previous match operation.

Parameters:

groupName - the name of the capture group

Returns:

the index

end

public int end()

Returns the offset after the last character matched.

Specified by:

end in interface MatchResult

Returns:

the offset

end

public int end(int group)

Returns the offset after the last character of the subsequence captured by the given group during the previous match operation.

Specified by:

end in interface MatchResult

Parameters:

group - the index of the capture group

Returns:

the offset

end

public int end(String groupName)

Returns the offset after the last character of the subsequence captured by the given named group during the previous match operation.

Parameters:

group - the name of the capture group

Returns:

the offset

region

public Matcher region(int start,
                      int end)

Sets the limits of this matcher's region.

Parameters:

start - The index to start searching at (inclusive)

end - The index to end searching at (exclusive)

Returns:

this Matcher

regionEnd

public int regionEnd()

Reports the end index (exclusive) of this matcher's region. The searches this matcher conducts are limited to finding matches within regionStart (inclusive) and regionEnd (exclusive).

Returns:

the ending point of this matcher's region

regionStart

public int regionStart()

Reports the start index of this matcher's region. The searches this matcher conducts are limited to finding matches within regionStart (inclusive) and regionEnd (exclusive).

Returns:

The starting point of this matcher's region

hitEnd

public boolean hitEnd()

Returns true if the end of input was hit by the search engine in the last match operation performed by this matcher.

Returns:

true iff the end of input was hit in the last match; false otherwise

requireEnd

public boolean requireEnd()

Returns true if more input could change a positive match into a negative one.

Returns:

true iff more input could change a positive match into a negative one.

hasAnchoringBounds

public boolean hasAnchoringBounds()

Queries the anchoring of region bounds for this matcher.

Returns:

true iff this matcher is using anchoring bounds, false otherwise.

hasTransparentBounds

public boolean hasTransparentBounds()

Queries the transparency of region bounds for this matcher.

Returns:

true iff this matcher is using transparent bounds, false otherwise

replaceAll

public String replaceAll(String replacement)

Replaces every subsequence of the input sequence that matches the pattern with the given replacement string.

Parameters:

replacement - The replacement string

Returns:

The string constructed by replacing each matching subsequence by the replacement string, substituting captured subsequences as needed

replaceFirst

public String replaceFirst(String replacement)

Replaces the first subsequence of the input sequence that matches the pattern with the given replacement string.

Parameters:

replacement - The replacement string

Returns:

The string constructed by replacing the first matching subsequence by the replacement string, substituting captured subsequences as needed

useAnchoringBounds

public Matcher useAnchoringBounds(boolean b)

Sets the anchoring of region bounds for this matcher.

Parameters:

b - a boolean indicating whether or not to use anchoring bounds.

Returns:

this Matcher

useTransparentBounds

public Matcher useTransparentBounds(boolean b)

Sets the transparency of region bounds for this matcher.

Parameters:

b - a boolean indicating whether to use opaque or transparent regions

Returns:

this Matcher

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object