| MatchResult.java |
1 /*
2 * %W% %E%
3 *
4 * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
5 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6 */
7
8 package java.util.regex;
9
10 /**
11 * The result of a match operation.
12 *
13 * <p>This interface contains query methods used to determine the
14 * results of a match against a regular expression. The match boundaries,
15 * groups and group boundaries can be seen but not modified through
16 * a <code>MatchResult</code>.
17 *
18 * @author Michael McCloskey
19 * @version %I% %G%
20 * @see Matcher
21 * @since 1.5
22 */
23 public interface MatchResult {
24
25 /**
26 * Returns the start index of the match.
27 *
28 * @return The index of the first character matched
29 *
30 * @throws IllegalStateException
31 * If no match has yet been attempted,
32 * or if the previous match operation failed
33 */
34 public int start();
35
36 /**
37 * Returns the start index of the subsequence captured by the given group
38 * during this match.
39 *
40 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
41 * to right, starting at one. Group zero denotes the entire pattern, so
42 * the expression <i>m.</i><tt>start(0)</tt> is equivalent to
43 * <i>m.</i><tt>start()</tt>. </p>
44 *
45 * @param group
46 * The index of a capturing group in this matcher's pattern
47 *
48 * @return The index of the first character captured by the group,
49 * or <tt>-1</tt> if the match was successful but the group
50 * itself did not match anything
51 *
52 * @throws IllegalStateException
53 * If no match has yet been attempted,
54 * or if the previous match operation failed
55 *
56 * @throws IndexOutOfBoundsException
57 * If there is no capturing group in the pattern
58 * with the given index
59 */
60 public int start(int group);
61
62 /**
63 * Returns the offset after the last character matched. </p>
64 *
65 * @return @return The offset after the last character matched
66 *
67 * @throws IllegalStateException
68 * If no match has yet been attempted,
69 * or if the previous match operation failed
70 */
71 public int end();
72
73 /**
74 * Returns the offset after the last character of the subsequence
75 * captured by the given group during this match.
76 *
77 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
78 * to right, starting at one. Group zero denotes the entire pattern, so
79 * the expression <i>m.</i><tt>end(0)</tt> is equivalent to
80 * <i>m.</i><tt>end()</tt>. </p>
81 *
82 * @param group
83 * The index of a capturing group in this matcher's pattern
84 *
85 * @return The offset after the last character captured by the group,
86 * or <tt>-1</tt> if the match was successful
87 * but the group itself did not match anything
88 *
89 * @throws IllegalStateException
90 * If no match has yet been attempted,
91 * or if the previous match operation failed
92 *
93 * @throws IndexOutOfBoundsException
94 * If there is no capturing group in the pattern
95 * with the given index
96 */
97 public int end(int group);
98
99 /**
100 * Returns the input subsequence matched by the previous match.
101 *
102 * <p> For a matcher <i>m</i> with input sequence <i>s</i>,
103 * the expressions <i>m.</i><tt>group()</tt> and
104 * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(),</tt> <i>m.</i><tt>end())</tt>
105 * are equivalent. </p>
106 *
107 * <p> Note that some patterns, for example <tt>a*</tt>, match the empty
108 * string. This method will return the empty string when the pattern
109 * successfully matches the empty string in the input. </p>
110 *
111 * @return The (possibly empty) subsequence matched by the previous match,
112 * in string form
113 *
114 * @throws IllegalStateException
115 * If no match has yet been attempted,
116 * or if the previous match operation failed
117 */
118 public String group();
119
120 /**
121 * Returns the input subsequence captured by the given group during the
122 * previous match operation.
123 *
124 * <p> For a matcher <i>m</i>, input sequence <i>s</i>, and group index
125 * <i>g</i>, the expressions <i>m.</i><tt>group(</tt><i>g</i><tt>)</tt> and
126 * <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>
127 * are equivalent. </p>
128 *
129 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
130 * to right, starting at one. Group zero denotes the entire pattern, so
131 * the expression <tt>m.group(0)</tt> is equivalent to <tt>m.group()</tt>.
132 * </p>
133 *
134 * <p> If the match was successful but the group specified failed to match
135 * any part of the input sequence, then <tt>null</tt> is returned. Note
136 * that some groups, for example <tt>(a*)</tt>, match the empty string.
137 * This method will return the empty string when such a group successfully
138 * matches the empty string in the input. </p>
139 *
140 * @param group
141 * The index of a capturing group in this matcher's pattern
142 *
143 * @return The (possibly empty) subsequence captured by the group
144 * during the previous match, or <tt>null</tt> if the group
145 * failed to match part of the input
146 *
147 * @throws IllegalStateException
148 * If no match has yet been attempted,
149 * or if the previous match operation failed
150 *
151 * @throws IndexOutOfBoundsException
152 * If there is no capturing group in the pattern
153 * with the given index
154 */
155 public String group(int group);
156
157 /**
158 * Returns the number of capturing groups in this match result's pattern.
159 *
160 * <p> Group zero denotes the entire pattern by convention. It is not
161 * included in this count.
162 *
163 * <p> Any non-negative integer smaller than or equal to the value
164 * returned by this method is guaranteed to be a valid group index for
165 * this matcher. </p>
166 *
167 * @return The number of capturing groups in this matcher's pattern
168 */
169 public int groupCount();
170
171 }
172