This interface contains query methods used to determine the
* results of a match against a regular expression. The match boundaries,
* groups and group boundaries can be seen but not modified through
* a MatchResult.
*
* @author Michael McCloskey
* @version 1.5 06/28/04
* @see Matcher
* @since 1.5
*/
public interface MatchResult {
/**
* Returns the start index of the match.
*
* @return The index of the first character matched
*
* @throws IllegalStateException
* If no match has yet been attempted,
* or if the previous match operation failed
*/
public int start();
/**
* Returns the start index of the subsequence captured by the given group
* during this match.
*
*
Capturing groups are indexed from left * to right, starting at one. Group zero denotes the entire pattern, so * the expression m.start(0) is equivalent to * m.start().
* * @param group * The index of a capturing group in this matcher's pattern * * @return 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 * * @throws IllegalStateException * If no match has yet been attempted, * or if the previous match operation failed * * @throws IndexOutOfBoundsException * If there is no capturing group in the pattern * with the given index */ public int start(int group); /** * Returns the offset after the last character matched. * * @return @return The offset after the last character matched * * @throws IllegalStateException * If no match has yet been attempted, * or if the previous match operation failed */ public int end(); /** * Returns the offset after the last character of the subsequence * captured by the given group during this match. * *Capturing groups are indexed from left * to right, starting at one. Group zero denotes the entire pattern, so * the expression m.end(0) is equivalent to * m.end().
* * @param group * The index of a capturing group in this matcher's pattern * * @return 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 * * @throws IllegalStateException * If no match has yet been attempted, * or if the previous match operation failed * * @throws IndexOutOfBoundsException * If there is no capturing group in the pattern * with the given index */ public int end(int group); /** * Returns the input subsequence matched by the previous match. * *For a matcher m with input sequence s, * the expressions m.group() and * s.substring(m.start(), m.end()) * are equivalent.
* *Note that some patterns, for example a*, match the empty * string. This method will return the empty string when the pattern * successfully matches the empty string in the input.
* * @return The (possibly empty) subsequence matched by the previous match, * in string form * * @throws IllegalStateException * If no match has yet been attempted, * or if the previous match operation failed */ public String group(); /** * Returns the input subsequence captured by the given group during the * previous match operation. * *For a matcher m, input sequence s, and group index * g, the expressions m.group(g) and * s.substring(m.start(g), m.end(g)) * are equivalent.
* *Capturing groups are indexed from left * to right, starting at one. Group zero denotes the entire pattern, so * the expression m.group(0) is equivalent to m.group(). *
* *If the match was successful but the group specified failed to match * any part of the input sequence, then null is returned. Note * that some groups, for example (a*), match the empty string. * This method will return the empty string when such a group successfully * matches the empty string in the input.
* * @param group * The index of a capturing group in this matcher's pattern * * @return The (possibly empty) subsequence captured by the group * during the previous match, or null if the group * failed to match part of the input * * @throws IllegalStateException * If no match has yet been attempted, * or if the previous match operation failed * * @throws IndexOutOfBoundsException * If there is no capturing group in the pattern * with the given index */ public String group(int group); /** * Returns the number of capturing groups in this match result's pattern. * *Group zero denotes the entire pattern by convention. It is not * included in this count. * *
Any non-negative integer smaller than or equal to the value * returned by this method is guaranteed to be a valid group index for * this matcher.
* * @return The number of capturing groups in this matcher's pattern */ public int groupCount(); }