1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package java.util.regex; 19 20/** 21 * Holds the results of a successful match of a {@link Pattern} against a 22 * given string. Typically this is an instance of {@link Matcher}, but 23 * since that's a mutable class it's also possible to freeze its current 24 * state using {@link Matcher#toMatchResult}. 25 */ 26public interface MatchResult { 27 28 /** 29 * Returns the index of the first character following the text that matched 30 * the whole regular expression. 31 */ 32 int end(); 33 34 /** 35 * Returns the index of the first character following the text that matched 36 * a given group. See {@link #group} for an explanation of group indexes. 37 */ 38 int end(int group); 39 40 /** 41 * Returns the text that matched the whole regular expression. 42 */ 43 String group(); 44 45 /** 46 * Returns the text that matched a given group of the regular expression. 47 * 48 * <p>Explicit capturing groups in the pattern are numbered left to right in order 49 * of their <i>opening</i> parenthesis, starting at 1. 50 * The special group 0 represents the entire match (as if the entire pattern is surrounded 51 * by an implicit capturing group). 52 * For example, "a((b)c)" matching "abc" would give the following groups: 53 * <pre> 54 * 0 "abc" 55 * 1 "bc" 56 * 2 "b" 57 * </pre> 58 * 59 * <p>An optional capturing group that failed to match as part of an overall 60 * successful match (for example, "a(b)?c" matching "ac") returns null. 61 * A capturing group that matched the empty string (for example, "a(b?)c" matching "ac") 62 * returns the empty string. 63 */ 64 String group(int group); 65 66 /** 67 * Returns the number of groups in the results, which is always equal to 68 * the number of groups in the original regular expression. 69 */ 70 int groupCount(); 71 72 /** 73 * Returns the index of the first character of the text that matched the 74 * whole regular expression. 75 */ 76 int start(); 77 78 /** 79 * Returns the index of the first character of the text that matched a given 80 * group. See {@link #group} for an explanation of group indexes. 81 */ 82 int start(int group); 83} 84