/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * particular file as subject to the "Classpath" exception as provided

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 */

package java.util.regex;

/**

 * The result of a match operation.

 *

 * <p>This interface contains query methods used to determine the

 * results of a match against a regular expression. The match boundaries,

 * groups and group boundaries can be seen but not modified through

 * a <code>MatchResult</code>.

 *

 * @author  Michael McCloskey

 * @see Matcher

 * @since 1.5

 */

public interface MatchResult {

    /**

     * Returns the start index of the match.

     *

     * @return  The index of the first character matched

     *

     * @throws  IllegalStateException

     *          If no match has yet been attempted,

     *          or if the previous match operation failed

     */

    public int start();

    /**

     * Returns the start index of the subsequence captured by the given group

     * during this match.

     *

     * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left

     * to right, starting at one.  Group zero denotes the entire pattern, so

     * the expression <i>m.</i><tt>start(0)</tt> is equivalent to

     * <i>m.</i><tt>start()</tt>.  </p>

     *

     * @param  group

     *         The index of a capturing group in this matcher's pattern

     *

     * @return  The index of the first character captured by the group,

     *          or <tt>-1</tt> if the match was successful but the group

     *          itself did not match anything

     *

     * @throws  IllegalStateException

     *          If no match has yet been attempted,

     *          or if the previous match operation failed

     *

     * @throws  IndexOutOfBoundsException

     *          If there is no capturing group in the pattern

     *          with the given index

     */

    public int start(int group);

    /**

     * Returns the offset after the last character matched.  </p>

     *

     * @return  @return  The offset after the last character matched

     *

     * @throws  IllegalStateException

     *          If no match has yet been attempted,

     *          or if the previous match operation failed

     */

    public int end();

    /**

     * Returns the offset after the last character of the subsequence

     * captured by the given group during this match.

     *

     * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left

     * to right, starting at one.  Group zero denotes the entire pattern, so

     * the expression <i>m.</i><tt>end(0)</tt> is equivalent to

     * <i>m.</i><tt>end()</tt>.  </p>

     *

     * @param  group

     *         The index of a capturing group in this matcher's pattern

     *

     * @return  The offset after the last character captured by the group,

     *          or <tt>-1</tt> if the match was successful

     *          but the group itself did not match anything

     *

     * @throws  IllegalStateException

     *          If no match has yet been attempted,

     *          or if the previous match operation failed

     *

     * @throws  IndexOutOfBoundsException

     *          If there is no capturing group in the pattern

     *          with the given index

     */

    public int end(int group);

    /**

     * Returns the input subsequence matched by the previous match.

     *

     * <p> For a matcher <i>m</i> with input sequence <i>s</i>,

     * the expressions <i>m.</i><tt>group()</tt> and

     * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(),</tt>&nbsp;<i>m.</i><tt>end())</tt>

     * are equivalent.  </p>

     *

     * <p> Note that some patterns, for example <tt>a*</tt>, match the empty

     * string.  This method will return the empty string when the pattern

     * successfully matches the empty string in the input.  </p>

     *

     * @return The (possibly empty) subsequence matched by the previous match,

     *         in string form

     *

     * @throws  IllegalStateException

     *          If no match has yet been attempted,

     *          or if the previous match operation failed

     */

    public String group();

    /**

     * Returns the input subsequence captured by the given group during the

     * previous match operation.

     *

     * <p> For a matcher <i>m</i>, input sequence <i>s</i>, and group index

     * <i>g</i>, the expressions <i>m.</i><tt>group(</tt><i>g</i><tt>)</tt> and

     * <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>

     * are equivalent.  </p>

     *

     * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left

     * to right, starting at one.  Group zero denotes the entire pattern, so

     * the expression <tt>m.group(0)</tt> is equivalent to <tt>m.group()</tt>.

     * </p>

     *

     * <p> If the match was successful but the group specified failed to match

     * any part of the input sequence, then <tt>null</tt> is returned. Note

     * that some groups, for example <tt>(a*)</tt>, match the empty string.

     * This method will return the empty string when such a group successfully

     * matches the empty string in the input.  </p>

     *

     * @param  group

     *         The index of a capturing group in this matcher's pattern

     *

     * @return  The (possibly empty) subsequence captured by the group

     *          during the previous match, or <tt>null</tt> if the group

     *          failed to match part of the input

     *

     * @throws  IllegalStateException

     *          If no match has yet been attempted,

     *          or if the previous match operation failed

     *

     * @throws  IndexOutOfBoundsException

     *          If there is no capturing group in the pattern

     *          with the given index

     */

    public String group(int group);

    /**

     * Returns the number of capturing groups in this match result's pattern.

     *

     * <p> Group zero denotes the entire pattern by convention. It is not

     * included in this count.

     *

     * <p> Any non-negative integer smaller than or equal to the value

     * returned by this method is guaranteed to be a valid group index for

     * this matcher.  </p>

     *

     * @return The number of capturing groups in this matcher's pattern

     */

    public int groupCount();

}