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 26package 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}. 35 * 36 * @author Michael McCloskey 37 * @see Matcher 38 * @since 1.5 39 */ 40public 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>{@code start(0)} is equivalent to 60 * <i>m.</i>{@code start()}. </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 {@code -1} 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>{@code end(0)} is equivalent to 97 * <i>m.</i>{@code end()}. </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 {@code -1} 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>{@code group()} and 121 * <i>s.</i>{@code substring(}<i>m.</i>{@code start(),} <i>m.</i>{@code end())} 122 * are equivalent. </p> 123 * 124 * <p> Note that some patterns, for example {@code a*}, 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>{@code group(}<i>g</i>{@code )} and 143 * <i>s.</i>{@code substring(}<i>m.</i>{@code start(}<i>g</i>{@code 144 * ),} <i>m.</i>{@code end(}<i>g</i>{@code ))} 145 * are equivalent. </p> 146 * 147 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left 148 * to right, starting at one. Group zero denotes the entire pattern, so 149 * the expression {@code m.group(0)} is equivalent to {@code m.group()}. 150 * </p> 151 * 152 * <p> If the match was successful but the group specified failed to match 153 * any part of the input sequence, then {@code null} is returned. Note 154 * that some groups, for example {@code (a*)}, match the empty string. 155 * This method will return the empty string when such a group successfully 156 * matches the empty string in the input. </p> 157 * 158 * @param group 159 * The index of a capturing group in this matcher's pattern 160 * 161 * @return The (possibly empty) subsequence captured by the group 162 * during the previous match, or {@code null} if the group 163 * failed to match part of the input 164 * 165 * @throws IllegalStateException 166 * If no match has yet been attempted, 167 * or if the previous match operation failed 168 * 169 * @throws IndexOutOfBoundsException 170 * If there is no capturing group in the pattern 171 * with the given index 172 */ 173 public String group(int group); 174 175 /** 176 * Returns the number of capturing groups in this match result's pattern. 177 * 178 * <p> Group zero denotes the entire pattern by convention. It is not 179 * included in this count. 180 * 181 * <p> Any non-negative integer smaller than or equal to the value 182 * returned by this method is guaranteed to be a valid group index for 183 * this matcher. </p> 184 * 185 * @return The number of capturing groups in this matcher's pattern 186 */ 187 public int groupCount(); 188 189} 190