package Torello.HTML.NodeSearch;

import Torello.HTML.DotPair;
import java.util.Vector;

/**
 * An exception thrown by the {@code HNLI} & {@code HNLIInclusive} iterators when, in the
 * processes of modifying or reading the contents of the most recent {@code Iterator}-Match, a
 * location is specified that's out of the bounds of the {@code Vector} itself.
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>Using this Exception:</B>
 * 
 * <BR />The use of this exception differs slightly from that of the {@link CursorException}, with
 * the primary difference being that a failed cursor-operation resulting in an invalid-cursor is
 * not identical to an "Out of Bounds" exception for that iterator <I>(when the
 * <CODE>Iterator</CODE>, itself, might not have even had a cursor set by the user!)</I>.
 * 
 * @see HNLIInclusive
 * @see HNLI
 */
public class IteratorOutOfBoundsException extends IndexOutOfBoundsException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

    /** Constructs an {@code IteratorOutOfBoundsException} with no detail message. */
    public IteratorOutOfBoundsException()
    { super(); }

    /**
     * Constructs an {@code IteratorOutOfBoundsException} with the specified detail message.
     * 
     * @param message the detail message.
     */
    public IteratorOutOfBoundsException(String message)
    { super(message); }

    /**
     * This method provides a consistently formatted error message when this exception is thrown by
     * the {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} classes.  Mostly, like
     * standard {@code Vector} operations, if the {@code int 'pos'} parameter that was passed is
     * negative or past the end of the {@code Vector}, an {@code IndexOutOfBoundsException} will be
     * thrown.
     * 
     * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by
     * an {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} class.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     * 
     * @param pos This is the position that has been attempted to index that {@code Vector}.
     * 
     * @throws IteratorOutOfBoundsException This will throw if the value passed to parameter 
     * {@code 'pos'} is negative, or greater than the size of the {@code Vector} parameter 
     * {@code 'v'}.
     * 
     * @see HNLI
     * @see HNLIInclusive
     */
    public static void check(Vector<?> v, int pos)
    {
        if (pos < 0) throw new IteratorOutOfBoundsException(
            "An attempt was made to reference the internal-state vector with a negative " +
            "index-value: [" + pos + "]"
        );

        if (pos >= v.size()) throw new IteratorOutOfBoundsException(
            "An attempt was made to reference the internal-state vector with an index that " +
            "is past the end of the Vector.  The attempted operation was made using " +
            "index [" + pos + "], but the internal-state vector has " +
            "vector.size() [" + v.size() + "]."
        );
    }

    /**
     * This method provides a consistently formatted error message for this exception.  This is
     * used by the {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} classes.  Mostly,
     * like standard {@code Vector} operations, if the {@code DotPair 'dp'} provided is not
     * consistent with the dimensions of the input html-{@code Vector}, then an
     * {@code IndexOutOfBoundsException} will be thrown.
     * 
     * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by
     * an {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} class.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     * 
     * @param dp This is the sub-section, or sub-list of the {@code Vector} that is being checked.
     * 
     * @throws IteratorOutOfBoundsException This will throw if the value passed to parameter
     * {@code 'dp'} is negative, or greater than the size of {@code Vector} parameter
     * {@code 'v'}.
     * 
     * @see HNLI
     * @see HNLIInclusive
     */
    public static void check(Vector<?> v, DotPair dp)
    {
        if (dp.end >= v.size()) throw new IteratorOutOfBoundsException(
            "An attempt was made to reference the internal-state vector with an index that " +
            "is past the end of the Vector.  The attempted operation was made using " +
            "DotPair " + dp.toString() + ", but the internal-state vector has " +
            "vector.size() [" + v.size() + "]."
        );
    }

    /**
     * This method provides a consistently formatted error message when this exception is thrown by
     * the {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} classes.  Mostly, like
     * standard {@code Vector} operations, if any of the index-positions that are referenced by the
     * {@code int[] posArr} parameter are negative or past the end of the {@code Vector}, an
     * {@code IndexOutOfBoundsException} will be thrown.
     * 
     * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by
     * an {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} class.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     * 
     * @param posArr This is the {@code array} of position-indices into {@code Vector} parameter 
     * {@code 'v'} that have been requested to update or for replacement.
     * 
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</B></SPAN> In the code that invokes this
     * method, the {@code int[]} position-{@code array} passed to parameter {@code 'posArr'} will
     * <B><I>ALWAYS</I></B> have been sorted before being received here.  As such, only the first
     * and last elements of this array are actually check for validity.  If this {@code array} is
     * not sorted, then the check performed by this method will be thoroughly insufficient.
     * 
     * @throws IteratorOutOfBoundsException This will throw if any of the the values passed to
     * parameter {@code 'posArr'} are negative, or greater than the size of {@code Vector} 
     * parameter {@code 'v'}.
     * 
     * @see HNLI
     * @see HNLIInclusive
     */
    public static void check(Vector<?> v, int[] posArr)
    {
        if (posArr[0] < 0) throw new IteratorOutOfBoundsException(
                "An attempt was made to reference the internal-state vector with a " +
                "negative index-value.  The smallest (most-negative) value " +
                "passed to the vector-index integer-array was [" + posArr[0] + "]."
            );
        if (posArr[posArr.length-1] >= v.size()) throw new IteratorOutOfBoundsException(
                "An attempt was made to reference the internal-state vector with a " +
                "location that is past the end of the Vector.  The largest value passed to " +
                "the vector-index integer-array was [" + posArr[posArr.length-1] + "].  " +
                "The internal-state vector has vector.size() [" + v.size() + "]."
            );
    }
}