1 /* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.util.regex; 27 28 /** 29 * The result of a match operation. 30 * 31 * <p>This interface contains query methods used to determine the 32 * results of a match against a regular expression. The match boundaries, 33 * groups and group boundaries can be seen but not modified through 34 * a <code>MatchResult</code>. 35 * 36 * @author Michael McCloskey 37 * @see Matcher 38 * @since 1.5 39 */ 40 public interface MatchResult { 41 42 /** 43 * Returns the start index of the match. 44 * 45 * @return The index of the first character matched 46 * 47 * @throws IllegalStateException 48 * If no match has yet been attempted, 49 * or if the previous match operation failed 50 */ 51 public int start(); 52 53 /** 54 * Returns the start index of the subsequence captured by the given group 55 * during this match. 56 * 57 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left 58 * to right, starting at one. Group zero denotes the entire pattern, so 59 * the expression <i>m.</i><tt>start(0)</tt> is equivalent to 60 * <i>m.</i><tt>start()</tt>. </p> 61 * 62 * @param group 63 * The index of a capturing group in this matcher's pattern 64 * 65 * @return The index of the first character captured by the group, 66 * or <tt>-1</tt> if the match was successful but the group 67 * itself did not match anything 68 * 69 * @throws IllegalStateException 70 * If no match has yet been attempted, 71 * or if the previous match operation failed 72 * 73 * @throws IndexOutOfBoundsException 74 * If there is no capturing group in the pattern 75 * with the given index 76 */ 77 public int start(int group); 78 79 /** 80 * Returns the offset after the last character matched. 81 * 82 * @return The offset after the last character matched 83 * 84 * @throws IllegalStateException 85 * If no match has yet been attempted, 86 * or if the previous match operation failed 87 */ 88 public int end(); 89 90 /** 91 * Returns the offset after the last character of the subsequence 92 * captured by the given group during this match. 93 * 94 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left 95 * to right, starting at one. Group zero denotes the entire pattern, so 96 * the expression <i>m.</i><tt>end(0)</tt> is equivalent to 97 * <i>m.</i><tt>end()</tt>. </p> 98 * 99 * @param group 100 * The index of a capturing group in this matcher's pattern 101 * 102 * @return The offset after the last character captured by the group, 103 * or <tt>-1</tt> if the match was successful 104 * but the group itself did not match anything 105 * 106 * @throws IllegalStateException 107 * If no match has yet been attempted, 108 * or if the previous match operation failed 109 * 110 * @throws IndexOutOfBoundsException 111 * If there is no capturing group in the pattern 112 * with the given index 113 */ 114 public int end(int group); 115 116 /** 117 * Returns the input subsequence matched by the previous match. 118 * 119 * <p> For a matcher <i>m</i> with input sequence <i>s</i>, 120 * the expressions <i>m.</i><tt>group()</tt> and 121 * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(),</tt> <i>m.</i><tt>end())</tt> 122 * are equivalent. </p> 123 * 124 * <p> Note that some patterns, for example <tt>a*</tt>, match the empty 125 * string. This method will return the empty string when the pattern 126 * successfully matches the empty string in the input. </p> 127 * 128 * @return The (possibly empty) subsequence matched by the previous match, 129 * in string form 130 * 131 * @throws IllegalStateException 132 * If no match has yet been attempted, 133 * or if the previous match operation failed 134 */ 135 public String group(); 136 137 /** 138 * Returns the input subsequence captured by the given group during the 139 * previous match operation. 140 * 141 * <p> For a matcher <i>m</i>, input sequence <i>s</i>, and group index 142 * <i>g</i>, the expressions <i>m.</i><tt>group(</tt><i>g</i><tt>)</tt> and 143 * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(</tt><i>g</i><tt>),</tt> <i>m.</i><tt>end(</tt><i>g</i><tt>))</tt> 144 * are equivalent. </p> 145 * 146 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left 147 * to right, starting at one. Group zero denotes the entire pattern, so 148 * the expression <tt>m.group(0)</tt> is equivalent to <tt>m.group()</tt>. 149 * </p> 150 * 151 * <p> If the match was successful but the group specified failed to match 152 * any part of the input sequence, then <tt>null</tt> is returned. Note 153 * that some groups, for example <tt>(a*)</tt>, match the empty string. 154 * This method will return the empty string when such a group successfully 155 * matches the empty string in the input. </p> 156 * 157 * @param group 158 * The index of a capturing group in this matcher's pattern 159 * 160 * @return The (possibly empty) subsequence captured by the group 161 * during the previous match, or <tt>null</tt> if the group 162 * failed to match part of the input 163 * 164 * @throws IllegalStateException 165 * If no match has yet been attempted, 166 * or if the previous match operation failed 167 * 168 * @throws IndexOutOfBoundsException 169 * If there is no capturing group in the pattern 170 * with the given index 171 */ 172 public String group(int group); 173 174 /** 175 * Returns the number of capturing groups in this match result's pattern. 176 * 177 * <p> Group zero denotes the entire pattern by convention. It is not 178 * included in this count. 179 * 180 * <p> Any non-negative integer smaller than or equal to the value 181 * returned by this method is guaranteed to be a valid group index for 182 * this matcher. </p> 183 * 184 * @return The number of capturing groups in this matcher's pattern 185 */ 186 public int groupCount(); 187 188 } 189
