/*

 * Copyright 1999-2008 Sun Microsystems, Inc.  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.  Sun designates this

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

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.util.regex;

/**

 * An engine that performs match operations on a {@link java.lang.CharSequence

 * </code>character sequence<code>} by interpreting a {@link Pattern}.

 *

 * <p> A matcher is created from a pattern by invoking the pattern's {@link

 * Pattern#matcher matcher} method.  Once created, a matcher can be used to

 * perform three different kinds of match operations:

 *

 * <ul>

 *

 *   <li><p> The {@link #matches matches} method attempts to match the entire

 *   input sequence against the pattern.  </p></li>

 *

 *   <li><p> The {@link #lookingAt lookingAt} method attempts to match the

 *   input sequence, starting at the beginning, against the pattern.  </p></li>

 *

 *   <li><p> The {@link #find find} method scans the input sequence looking for

 *   the next subsequence that matches the pattern.  </p></li>

 *

 * </ul>

 *

 * <p> Each of these methods returns a boolean indicating success or failure.

 * More information about a successful match can be obtained by querying the

 * state of the matcher.

 *

 * <p> A matcher finds matches in a subset of its input called the

 * <i>region</i>. By default, the region contains all of the matcher's input.

 * The region can be modified via the{@link #region region} method and queried

 * via the {@link #regionStart regionStart} and {@link #regionEnd regionEnd}

 * methods. The way that the region boundaries interact with some pattern

 * constructs can be changed. See {@link #useAnchoringBounds

 * useAnchoringBounds} and {@link #useTransparentBounds useTransparentBounds}

 * for more details.

 *

 * <p> This class also defines methods for replacing matched subsequences with

 * new strings whose contents can, if desired, be computed from the match

 * result.  The {@link #appendReplacement appendReplacement} and {@link

 * #appendTail appendTail} methods can be used in tandem in order to collect

 * the result into an existing string buffer, or the more convenient {@link

 * #replaceAll replaceAll} method can be used to create a string in which every

 * matching subsequence in the input sequence is replaced.

 *

 * <p> The explicit state of a matcher includes the start and end indices of

 * the most recent successful match.  It also includes the start and end

 * indices of the input subsequence captured by each <a

 * href="Pattern.html#cg">capturing group</a> in the pattern as well as a total

 * count of such subsequences.  As a convenience, methods are also provided for

 * returning these captured subsequences in string form.

 *

 * <p> The explicit state of a matcher is initially undefined; attempting to

 * query any part of it before a successful match will cause an {@link

 * IllegalStateException} to be thrown.  The explicit state of a matcher is

 * recomputed by every match operation.

 *

 * <p> The implicit state of a matcher includes the input character sequence as

 * well as the <i>append position</i>, which is initially zero and is updated

 * by the {@link #appendReplacement appendReplacement} method.

 *

 * <p> A matcher may be reset explicitly by invoking its {@link #reset()}

 * method or, if a new input sequence is desired, its {@link

 * #reset(java.lang.CharSequence) reset(CharSequence)} method.  Resetting a

 * matcher discards its explicit state information and sets the append position

 * to zero.

 *

 * <p> Instances of this class are not safe for use by multiple concurrent

 * threads. </p>

 *

 *

 * @author      Mike McCloskey

 * @author      Mark Reinhold

 * @author      JSR-51 Expert Group

 * @since       1.4

 * @spec        JSR-51

 */

public final class Matcher implements MatchResult {

    /**

     * The Pattern object that created this Matcher.

     */

    Pattern parentPattern;

    /**

     * The storage used by groups. They may contain invalid values if

     * a group was skipped during the matching.

     */

    int[] groups;

    /**

     * The range within the sequence that is to be matched. Anchors

     * will match at these "hard" boundaries. Changing the region

     * changes these values.

     */

    int from, to;

    /**

     * Lookbehind uses this value to ensure that the subexpression

     * match ends at the point where the lookbehind was encountered.

     */

    int lookbehindTo;

    /**

     * The original string being matched.

     */

    CharSequence text;

    /**

     * Matcher state used by the last node. NOANCHOR is used when a

     * match does not have to consume all of the input. ENDANCHOR is

     * the mode used for matching all the input.

     */

    static final int ENDANCHOR = 1;

    static final int NOANCHOR = 0;

    int acceptMode = NOANCHOR;

    /**

     * The range of string that last matched the pattern. If the last

     * match failed then first is -1; last initially holds 0 then it

     * holds the index of the end of the last match (which is where the

     * next search starts).

     */

    int first = -1, last = 0;

    /**

     * The end index of what matched in the last match operation.

     */

    int oldLast = -1;

    /**

     * The index of the last position appended in a substitution.

     */

    int lastAppendPosition = 0;

    /**

     * Storage used by nodes to tell what repetition they are on in

     * a pattern, and where groups begin. The nodes themselves are stateless,

     * so they rely on this field to hold state during a match.

     */

    int[] locals;

    /**

     * Boolean indicating whether or not more input could change

     * the results of the last match.

     *

     * If hitEnd is true, and a match was found, then more input

     * might cause a different match to be found.

     * If hitEnd is true and a match was not found, then more

     * input could cause a match to be found.

     * If hitEnd is false and a match was found, then more input

     * will not change the match.

     * If hitEnd is false and a match was not found, then more

     * input will not cause a match to be found.

     */

    boolean hitEnd;

    /**

     * Boolean indicating whether or not more input could change

     * a positive match into a negative one.

     *

     * If requireEnd is true, and a match was found, then more

     * input could cause the match to be lost.

     * If requireEnd is false and a match was found, then more

     * input might change the match but the match won't be lost.

     * If a match was not found, then requireEnd has no meaning.

     */

    boolean requireEnd;

    /**

     * If transparentBounds is true then the boundaries of this

     * matcher's region are transparent to lookahead, lookbehind,

     * and boundary matching constructs that try to see beyond them.

     */

    boolean transparentBounds = false;

    /**

     * If anchoringBounds is true then the boundaries of this

     * matcher's region match anchors such as ^ and $.

     */

    boolean anchoringBounds = true;

    /**

     * No default constructor.

     */

    Matcher() {

    }

    /**

     * All matchers have the state used by Pattern during a match.

     */

    Matcher(Pattern parent, CharSequence text) {

        this.parentPattern = parent;

        this.text = text;

        // Allocate state storage

        int parentGroupCount = Math.max(parent.capturingGroupCount, 10);

        groups = new int[parentGroupCount * 2];

        locals = new int[parent.localCount];

        // Put fields into initial states

        reset();

    }

    /**

     * Returns the pattern that is interpreted by this matcher.

     *

     * @return  The pattern for which this matcher was created

     */

    public Pattern pattern() {

        return parentPattern;

    }

    /**

     * Returns the match state of this matcher as a {@link MatchResult}.

     * The result is unaffected by subsequent operations performed upon this

     * matcher.

     *

     * @return  a <code>MatchResult</code> with the state of this matcher

     * @since 1.5

     */

    public MatchResult toMatchResult() {

        Matcher result = new Matcher(this.parentPattern, text.toString());

        result.first = this.first;

        result.last = this.last;

        result.groups = this.groups.clone();

        return result;

    }

    /**

      * Changes the <tt>Pattern</tt> that this <tt>Matcher</tt> uses to

      * find matches with.

      *

      * <p> This method causes this matcher to lose information

      * about the groups of the last match that occurred. The

      * matcher's position in the input is maintained and its

      * last append position is unaffected.</p>

      *

      * @param  newPattern

      *         The new pattern used by this matcher

      * @return  This matcher

      * @throws  IllegalArgumentException

      *          If newPattern is <tt>null</tt>

      * @since 1.5

      */

    public Matcher usePattern(Pattern newPattern) {

        if (newPattern == null)

            throw new IllegalArgumentException("Pattern cannot be null");

        parentPattern = newPattern;

        // Reallocate state storage

        int parentGroupCount = Math.max(newPattern.capturingGroupCount, 10);

        groups = new int[parentGroupCount * 2];

        locals = new int[newPattern.localCount];

        for (int i = 0; i < groups.length; i++)

            groups[i] = -1;

        for (int i = 0; i < locals.length; i++)

            locals[i] = -1;

        return this;

    }

    /**

     * Resets this matcher.

     *

     * <p> Resetting a matcher discards all of its explicit state information

     * and sets its append position to zero. The matcher's region is set to the

     * default region, which is its entire character sequence. The anchoring

     * and transparency of this matcher's region boundaries are unaffected.

     *

     * @return  This matcher

     */

    public Matcher reset() {

        first = -1;

        last = 0;

        oldLast = -1;

        for(int i=0; i<groups.length; i++)

            groups[i] = -1;

        for(int i=0; i<locals.length; i++)

            locals[i] = -1;

        lastAppendPosition = 0;

        from = 0;

        to = getTextLength();

        return this;

    }

    /**

     * Resets this matcher with a new input sequence.

     *

     * <p> Resetting a matcher discards all of its explicit state information

     * and sets its append position to zero.  The matcher's region is set to

     * the default region, which is its entire character sequence.  The

     * anchoring and transparency of this matcher's region boundaries are

     * unaffected.

     *

     * @param  input

     *         The new input character sequence

     *

     * @return  This matcher

     */

    public Matcher reset(CharSequence input) {

        text = input;

        return reset();

    }

    /**

     * Returns the start index of the previous match.  </p>

     *

     * @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() {

        if (first < 0)

            throw new IllegalStateException("No match available");

        return first;

    }

    /**

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

     * during the previous match operation.

     *

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

        if (first < 0)

            throw new IllegalStateException("No match available");

        if (group > groupCount())

            throw new IndexOutOfBoundsException("No group " + group);

        return groups[group * 2];

    }

    /**

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

     *

     * @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() {

        if (first < 0)

            throw new IllegalStateException("No match available");

        return last;

    }

    /**

     * Returns the offset after the last character of the subsequence

     * captured by the given group during the previous match operation.

     *

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

        if (first < 0)

            throw new IllegalStateException("No match available");

        if (group > groupCount())

            throw new IndexOutOfBoundsException("No group " + group);

        return groups[group * 2 + 1];

    }

    /**

     * 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() {

        return group(0);

    }

    /**

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

        if (first < 0)

            throw new IllegalStateException("No match found");

        if (group < 0 || group > groupCount())

            throw new IndexOutOfBoundsException("No group " + group);

        if ((groups[group*2] == -1) || (groups[group*2+1] == -1))

            return null;

        return getSubSequence(groups[group * 2], groups[group * 2 + 1]).toString();

    }

    /**

     * Returns the number of capturing groups in this matcher'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() {

        return parentPattern.capturingGroupCount - 1;

    }

    /**

     * Attempts to match the entire region against the pattern.

     *

     * <p> If the match succeeds then more information can be obtained via the

     * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods.  </p>

     *

     * @return  <tt>true</tt> if, and only if, the entire region sequence

     *          matches this matcher's pattern

     */

    public boolean matches() {

        return match(from, ENDANCHOR);

    }

    /**

     * Attempts to find the next subsequence of the input sequence that matches

     * the pattern.

     *

     * <p> This method starts at the beginning of this matcher's region, or, if

     * a previous invocation of the method was successful and the matcher has

     * not since been reset, at the first character not matched by the previous