/*

  * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.

  * 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

  * published by the Free Software Foundation.  Oracle designates this

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

  * by Oracle in the LICENSE file that accompanied this code.

  *

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

  *

  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

  * or visit www.oracle.com if you need additional information or have any

  * questions.

  */

 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();

 }