* * A MatchResult instance contains a pattern match and its saved groups. * You can access the entire match directly using the * {@link #group(int)} method with an argument of 0, * or by the {@link #toString()} method which is * defined to return the same thing. It is also possible to obtain * the beginning and ending offsets of a match relative to the input * producing the match by using the * {@link #beginOffset(int)} and {@link #endOffset(int)} methods. The * {@link #begin(int)} and {@link #end(int)} are useful in some * circumstances and return the begin and end offsets of the subgroups * of a match relative to the beginning of the match. *
* * You might use a MatchResult as follows: *
* int groups;
* PatternMatcher matcher;
* PatternCompiler compiler;
* Pattern pattern;
* PatternMatcherInput input;
* MatchResult result;
*
* compiler = new Perl5Compiler();
* matcher = new Perl5Matcher();
*
* try {
* pattern = compiler.compile(somePatternString);
* } catch(MalformedPatternException e) {
* System.out.println("Bad pattern.");
* System.out.println(e.getMessage());
* return;
* }
*
* input = new PatternMatcherInput(someStringInput);
*
* while(matcher.contains(input, pattern)) {
* result = matcher.getMatch();
* // Perform whatever processing on the result you want.
* // Here we just print out all its elements to show how its
* // methods are used.
*
* System.out.println("Match: " + result.toString());
* System.out.println("Length: " + result.length());
* groups = result.groups();
* System.out.println("Groups: " + groups);
* System.out.println("Begin offset: " + result.beginOffset(0));
* System.out.println("End offset: " + result.endOffset(0));
* System.out.println("Saved Groups: ");
*
* // Start at 1 because we just printed out group 0
* for(int group = 1; group < groups; group++) {
* System.out.println(group + ": " + result.group(group));
* System.out.println("Begin: " + result.begin(group));
* System.out.println("End: " + result.end(group));
* }
* }
* *
** int length = -1; // Use -1 to indicate group doesn't exist * MatchResult result; * String subgroup; * * // Initialization of result omitted * * subgroup = result.group(1); * if(subgroup != null) * length = subgroup.length(); * *
* * The length() method serves as a more a more efficient way to do: *
*
** length = result.group(0).length(); *
*
* @return The length of the match.
*/
public int length();
/**
* @return The number of groups contained in the result. This number
* includes the 0th group. In other words, the result refers
* to the number of parenthesized subgroups plus the entire match
* itself.
*/
public int groups();
/**
* Returns the contents of the parenthesized subgroups of a match,
* counting parentheses from left to right and starting from 1.
* Group 0 always refers to the entire match. For example, if the
* pattern foo(\d+) is used to extract a match
* from the input abfoo123 , then group(0)
* will return foo123 and group(1) will return
* 123 . group(2) will return
* null because there is only one subgroup in the original
* pattern.
*
* @param group The pattern subgroup to return. * @return A string containing the indicated pattern subgroup. Group * 0 always refers to the entire match. If a group was never * matched, it returns null. This is not to be confused with * a group matching the null string, which will return a String * of length 0. */ public String group(int group); /** * @param group The pattern subgroup. * @return The offset into group 0 of the first token in the indicated * pattern subgroup. If a group was never matched or does * not exist, returns -1. Be aware that a group that matches * the null string at the end of a match will have an offset * equal to the length of the string, so you shouldn't blindly * use the offset to index an array or String. */ public int begin(int group); /** * @param group The pattern subgroup. * @return Returns one plus the offset into group 0 of the last token in * the indicated pattern subgroup. If a group was never matched * or does not exist, returns -1. A group matching the null * string will return its start offset. */ public int end(int group); /** * Returns an offset marking the beginning of the pattern match * relative to the beginning of the input from which the match * was extracted. *
* @param group The pattern subgroup. * @return The offset of the first token in the indicated * pattern subgroup. If a group was never matched or does * not exist, returns -1. */ public int beginOffset(int group); /** * Returns an offset marking the end of the pattern match * relative to the beginning of the input from which the match was * extracted. *
* @param group The pattern subgroup. * @return Returns one plus the offset of the last token in * the indicated pattern subgroup. If a group was never matched * or does not exist, returns -1. A group matching the null * string will return its start offset. */ public int endOffset(int group); /** * Returns the same as group(0). * * @return A string containing the entire match. */ public String toString(); }