1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.util.regex;
19
20/**
21 * Holds the results of a successful match of a {@link Pattern} against a
22 * given string. The result is divided into groups, with one group for each
23 * pair of parentheses in the regular expression and an additional group for
24 * the whole regular expression. The start, end, and contents of each group
25 * can be queried.
26 *
27 * @see Matcher
28 * @see Matcher#toMatchResult()
29 */
30public interface MatchResult {
31
32    /**
33     * Returns the index of the first character following the text that matched
34     * the whole regular expression.
35     *
36     * @return the character index.
37     */
38    int end();
39
40    /**
41     * Returns the index of the first character following the text that matched
42     * a given group.
43     *
44     * @param group
45     *            the group, ranging from 0 to groupCount() - 1, with 0
46     *            representing the whole pattern.
47     *
48     * @return the character index.
49     */
50    int end(int group);
51
52    /**
53     * Returns the text that matched the whole regular expression.
54     *
55     * @return the text.
56     */
57    String group();
58
59    /**
60     * Returns the text that matched a given group of the regular expression.
61     *
62     * @param group
63     *            the group, ranging from 0 to groupCount() - 1, with 0
64     *            representing the whole pattern.
65     *
66     * @return the text that matched the group.
67     */
68    String group(int group);
69
70    /**
71     * Returns the number of groups in the result, which is always equal to
72     * the number of groups in the original regular expression.
73     *
74     * @return the number of groups.
75     */
76    int groupCount();
77
78    /**
79     * Returns the index of the first character of the text that matched
80     * the whole regular expression.
81     *
82     * @return the character index.
83     */
84    int start();
85
86    /**
87     * Returns the index of the first character of the text that matched a given
88     * group.
89     *
90     * @param group
91     *            the group, ranging from 0 to groupCount() - 1, with 0
92     *            representing the whole pattern.
93     *
94     * @return the character index.
95     */
96    int start(int group);
97}
98