MatchResult类(JAVA JDK源代码)

Posted 2022-05-25 zhangyishu

  1 /*
  2  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
  3  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  4  *
  5  *
  6  *
  7  *
  8  *
  9  *
 10  *
 11  *
 12  *
 13  *
 14  *
 15  *
 16  *
 17  *
 18  *
 19  *
 20  *
 21  *
 22  *
 23  *
 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.
 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>@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(),&nbsp;<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      * ),&nbsp;<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