View Javadoc
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>&nbsp;<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>&nbsp;<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 }