MatchResult


1   /*
2    * @(#)MatchResult.java 1.5 04/06/28
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN 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 1.5 06/28/04
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>&nbsp;<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>&nbsp;<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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags