package Torello.Java;

import java.util.*;
import Torello.HTML.*;

/**
 * The Loop-Variable End-Points class is used extensively throughout the Java-HTML Library for
 * throwing properly formatted exception messages <I>vis-a-vis</I> loop variables.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=LV>
 */
public class LV implements java.io.Serializable, Cloneable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;

    /**
     * This integer represents the starting point of a {@code for-loop}.  It is guaranteed to be
     * consistent with the {@code Vector} that was used with the constructor of this class.
     */
    public final int start;

    /**
     * This integer represents the ending point of a {@code for-loop}.  It is guaranteed to be
     * consistent with the {@code Vector} that was used with the constructor of this class.
     */
    public final int end;


    // ********************************************************************************************
    // Standard Java Methods
    // ********************************************************************************************


    /**
     * Implements the standard java {@code 'hashCode()'} method.  This will provide a hash-code 
     * that is very likely to avoid crashes.
     * @return A hash-code that may be used for inserting {@code 'this'} instance into a hashed
     * table, map or list.
     */
    public int hashCode()
    { return this.start + (1000 * this.end); }

    /**
     * Java's {@code toString()} requirement.
     * @return A string representing 'this' instance of LV / Loop-Variables.
     */
    public String toString() { return "[Loop-Start: " + start + ", Loop-Break: " + end + "]"; }

    /**
     * Java's {@code public boolean equals(Object o)} requirements.
     *
     * @param o This may be any Java Object, but only ones of {@code 'this'} type whose
     * internal-values are identical with {@code 'this'} instance will make this method return
     * {@code TRUE}.
     *
     * @return {@code TRUE} if (and only if) parameter {@code 'o'} is an {@code instanceof LV} and,
     * also, has equal {@code 'start'} and {@code 'end'} field values.
     */
    public boolean equals(Object o)
    {
        if (o instanceof LV)
        {
            LV dp = (LV) o;
            return (this.start == dp.start) && (this.end == dp.end);
        }

        else return false;
    }

    /**
     * Java's {@code interface Cloneable} requirements.  This instantiates a new {@code LV} with
     * identical {@code 'start', 'end'} fields.
     * 
     * @return A new {@code LV} instance whose internal fields are identical to this one.
     */
    public LV clone() { return new LV(this.start, this.end); }

    /**
     * Returns the number of elements that would be iterated, if using {@code 'this'} instance of
     * {@code LV} as a loop-control variable.
     * 
     * @return The number of element's that are referenced by {@code 'this'} instance.
     * 
     * @see #start
     * @see #end
     */
    public int size() { return end - start; }

    // ********************************************************************************************
    // ********************************************************************************************
    // Internal Helper Methods
    // ********************************************************************************************
    // ********************************************************************************************


    // Private "Clone Constructor"
    private LV(int start, int end) { this.start=start; this.end=end; }

    private String NOTEV (int size, int sPos, int ePos)
    {
        return
            "Vector.size(): [" + size + "], " +
            "Start-Position: [" + sPos + "], " +
            "End-Position:[" + ePos + ']';
    }

    private String NOTESTR(int length, int sPos, int ePos)
    {
        return
            "String.length(): [" + length + "], " +
            "sPos: [" + sPos + "], " +
            "ePos: [" + ePos + ']';
    }

    private String NOTESTR(int length, int sPos, int ePos, int cmprStrLen)
    {
        return
            "String.length(): [" + length + "], " +
            "sPos: [" + sPos + "], " +
            "ePos: [" + ePos + "], " +
            "cmprStrLen: [" + cmprStrLen + ']';
    }

    private String NOTEA(int length, int sPos, int ePos)
    {
        return
            "Array.length: [" + length + "], " +
            "Start-Position: [" + sPos + "], " +
            "End-Position:[" + ePos + ']';
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Checks input parameters and either throws {@code IndexOutOfBoundsException} or returns
     * proper loop-variable starting &amp; ending values.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=LV_IMPT_NOTE>
     *
     * @param html This is any vectorized-html page {@code Vector}.
     *
     * @param sPos This is the starting position in the {@code Vector} for the loop-variable 
     * counter being created.  This value is <B>inclusive</B>.  This means that the first element
     * searched by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code 'sPos'}</I>.
     *
     * <BR /><BR />If all validity checks are passed, {@code 'this.start'} is assigned the value of
     * {@code 'sPos'}.
     *
     * @param ePos This is the ending position in the {@code Vector} for the loop-variable counter
     * being created.  This value is <B>exclusive</B>.  This means that the last element searched
     * by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code ePos - 1}</I>.
     *
     * <BR /><BR />A negative value may be passed to {@code 'ePos'} - and if so, {@code this.end}
     * shall be set to {@code html.size()}, otherwise {@code this.end} is assigned the value of
     * {@code 'ePos'}.
     *
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     */
    public LV(Vector<? extends HTMLNode> html, int sPos, int ePos)
    {
        int size = html.size();

        if ((size == 0) && (sPos == 0) && (ePos <= 0))
        { this.start = this.end = 0; return; }

        if (sPos >= size) throw new IndexOutOfBoundsException(
            "Starting Vector Position is greater than or equal to the Vector's size:\n" +
            NOTEV(size, sPos, ePos)
        );

        if (sPos < 0) throw new IndexOutOfBoundsException
            ("Starting Vector Position is negative: " + NOTEV(size, sPos, ePos));

        if (ePos > size) throw new IndexOutOfBoundsException(
            "Ending Vector Position is greater than the size of the Vector:\n" +
            NOTEV(size, sPos, ePos)
        );

        if (ePos == 0) throw new IndexOutOfBoundsException
            ("Ending Vector Position is zero.:\n" + NOTEV(size, sPos, ePos));

        this.start  = sPos;
        this.end    = (ePos <= 0) ? size : ePos;

        if (start > end) throw new IllegalArgumentException(
            "The starting and ending Vector Positions are not properly chosen:\n" + 
            NOTEV(size, sPos, ePos)
        );
    }


    /**
     * Explaining the issue of type-checking with java-generics, once a certain point has been
     * reached, is an exercise in futility.  The JDK development team did a lot of work on Java
     * Generics, but didn't not bring them into the "Run-Time" world.  As such, there are a few,
     * details, as we shall call them with names like "CAP#1" that prevent some perfectly
     * reasonable looking code structures that simply will not compile.
     * 
     * <BR /><BR />This constructor is identical to the other constructor in this class, but has
     * had its parameter position inputs reversed in the method signature.  Also, <I><B>it accepts
     * a raw-type {@code Vector} instance.</I></B>  This should not present a problem to users at
     * all, but to the developer of this project / package, it can be disconcerting.  In any case,
     * this constructor checks the input parameters and either throws
     * {@code IndexOutOfBoundsException} or returns a proper loop-variable starting-ending point
     * class-object.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=LV_IMPT_NOTE>
     * 
     * @param v This may be any {@code raw-type Vector}.
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     *
     * @param sPos This is the starting position in the {@code Vector} for the loop-variable 
     * counter being created.  This value is <B>inclusive</B>.  This means that the first element
     * searched by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code 'sPos'}</I>.
     *
     * <BR /><BR />If all validity checks are passed, {@code 'this.start'} is assigned the value of
     * {@code 'sPos'}.
     *
     * @param ePos This is the ending position in the {@code Vector} for the loop-variable counter
     * being created.  This value is <B>exclusive</B>.  This means that the last element searched
     * by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code ePos - 1}</I>.
     *
     * <BR /><BR />A negative value may be passed to {@code 'ePos'} - and if so, {@code this.end}
     * shall be set to {@code html.size()}, otherwise {@code this.end} is assigned the value of
     * {@code 'ePos'}.
     *
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     */
    public LV(int sPos, int ePos, Vector<?> v)
    {
        int size = v.size();

        if ((size == 0) && (sPos == 0) && (ePos <= 0))
        { this.start = this.end = 0; return; }

        if (sPos >= size) throw new IndexOutOfBoundsException(
            "Starting Vector Position is greater than or equal to the Vector's size:\n" +
            NOTEV(size, sPos, ePos)
        );

        if (sPos < 0) throw new IndexOutOfBoundsException
            ("Starting Vector Position is negative: " + NOTEV(size, sPos, ePos));

        if (ePos > size) throw new IndexOutOfBoundsException(
            "Ending Vector Position is greater than the size of the Vector:\n" +
            NOTEV(size, sPos, ePos)
        );

        if (ePos == 0) throw new IndexOutOfBoundsException
            ("Ending Vector Position is zero.:\n" + NOTEV(size, sPos, ePos));

        this.start  = sPos;
        this.end    = (ePos <= 0) ? size : ePos;

        if (start > end) throw new IllegalArgumentException(
            "The starting and ending Vector Positions are not properly chosen:\n" +
            NOTEV(size, sPos, ePos)
        );
    }

    /**
     * Checks input parameters and either throws {@code StringIndexOutOfBoundsException} or returns
     * proper loop-variable starting &amp; ending values.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=LV_IMPT_NOTE>
     *
     * @param s This may be any {@code String}.
     *
     * @param sPos This is the starting position in the {@code String} for the loop-variable 
     * counter being created.  This value is <B>inclusive</B>.  This means that the first element
     * searched by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code 'sPos'}</I>.
     *
     * <BR /><BR />If all validity checks are passed, {@code 'this.start'} is assigned the value of
     * {@code 'sPos'}.
     *
     * @param ePos This is the ending position in the {@code String} for the loop-variable counter
     * being created.  This value is <B>exclusive</B>.  This means that the last element searched
     * by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code ePos - 1}</I>.
     *
     * <BR /><BR />A negative value may be passed to {@code 'ePos'} - and if so, {@code this.end}
     * shall be set to {@code s.size()}, otherwise {@code this.end} is assigned the value of
     * {@code 'ePos'}.
     *
     * @throws StringIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=SIOOB_EX>
     */
    public LV(String s, int sPos, int ePos)
    {
        int length = s.length();

        if ((length == 0) && (sPos == 0) && (ePos <= 0))
        { this.start = this.end = 0; return; }

        if (sPos >= length) throw new StringIndexOutOfBoundsException(
            "Starting String Position is greater than or equal to the String's length:\n" +
            NOTESTR(length, sPos, ePos)
        );

        if (sPos < 0) throw new StringIndexOutOfBoundsException
            ("Starting String Position is negative:\n" + NOTESTR(length, sPos, ePos));

        if (ePos > length) throw new StringIndexOutOfBoundsException(
            "Ending String Position is greater than the length of the String:\n" +
            NOTESTR(length, sPos, ePos)
        );

        if (ePos == 0) throw new StringIndexOutOfBoundsException
            ("Ending String Position is zero:\n" + NOTESTR(length, sPos, ePos));

        this.start  = sPos;
        this.end    = (ePos <= 0) ? length : ePos;

        if (start > end) throw new IllegalArgumentException(
            "The starting and ending String positions are not properly chosen:\n" +
            NOTESTR(length, sPos, ePos)
        );
    }

    /**
     * Checks input parameters and either throws {@code StringIndexOutOfBoundsException} or returns
     * proper loop-variable starting &amp; ending values.  In this constructor, the length of a
     * second, comparing-{@code String}, substring is expected as a parameter.  This version of the
     * {@code LV} constructor is used by {@code class StrIndexOf}.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=LV_IMPT_NOTE>
     *
     * @param s This may be any {@code String}.
     *
     * @param sPos This is the starting position in the {@code String} for the loop-variable 
     * counter being created.  This value is <B>inclusive</B>.  This means that the first element
     * searched by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code 'sPos'}</I>.
     *
     * <BR /><BR />If all validity checks are passed, {@code 'this.start'} is assigned the value of
     * {@code 'sPos'}.
     *
     * @param ePos This is the ending position in the {@code String} for the loop-variable counter
     * being created.  This value is <B>exclusive</B>.  This means that the last element searched
     * by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code ePos - 1}</I>.
     *
     * <BR /><BR />A negative value may be passed to {@code 'ePos'} - and if so, {@code this.end}
     * shall be set to {@code s.length() - cmprStrLen + 1}, otherwise {@code this.end} is assigned
     * the value of {@code 'ePos'}.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">MEANING:</B></SPAN> Since the {@code String}-Search
     * and {@code String-Loops} should be as optimized as possible - due to the fact there is a
     * possibility they could be invoked many, many times - Setting the value of {@code this.end}
     * to be 'less the value of a compare-{@code String} length' means that many fewer comparison's 
     * need to be performed.  The compare-{@code String} cannot possibly fit between {@code ePos} 
     * and 'the end of the source-{@code String}' if {@code ePos} is closer to the end of the 
     * source-{@code String} than the total size of {@code 'cmprStrLen'}.  Primarily, if this does
     * not make sense, this constructor is an optimization on the standard {@code String} loop
     * variable constructor that allows to shorted {@code this.end} in order to eliminate
     * extraneous {@code for-loop} comparison's in {@code class StrCmpr}.
     *
     * @param cmprStrLen This is just an integer that represents the length of a comparison
     * {@code String}.  When looping through the contents of one {@code String}, and comparing
     * those contents to another {@code String} - <I><B>the length of that second
     * {@code String}</I></B> should be subtracted from the value that is stored in the field
     * {@code public final int end}  This is because one {@code String} cannot be a substring of
     * another with a beginning matching index that does not accommodate a match before the
     * {@code String}, itself, runs out.
     * @throws StringIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=SIOOB_EX>
     */
    public LV(String s, int sPos, int ePos, int cmprStrLen)
    {
        int length         = s.length();

        if ((length == 0) && (sPos == 0) && (ePos <= 0))
        { this.start = this.end = 0; return; }

         if (sPos >= length) throw new StringIndexOutOfBoundsException(
             "Starting String Position is greater than or equal to the String's length:\n"  +
            NOTESTR(length, sPos, ePos, cmprStrLen)
        );

        if (sPos < 0) throw new StringIndexOutOfBoundsException
            ("Starting String position is negative:\n" + NOTESTR(length, sPos, ePos, cmprStrLen));

        if (ePos > length) throw new StringIndexOutOfBoundsException(
            "Ending String Position is greater than the length of the String:\n" +
            NOTESTR(length, sPos, ePos, cmprStrLen)
        );

        if (ePos == 0) throw new StringIndexOutOfBoundsException
            ("Ending String Position is zero:\n" + NOTESTR(length, sPos, ePos, cmprStrLen));

        this.start  = sPos;
        int endTEMP = (ePos <= 0) ? length : ePos;

        if (start > endTEMP) throw new IllegalArgumentException(
            "The starting and ending String positions are not properly chosen:\n" +
            NOTESTR(length, sPos, ePos, cmprStrLen)
        );

        endTEMP     = endTEMP - cmprStrLen + 1;
        this.end    = (endTEMP < sPos) ? sPos : endTEMP;
    }


    /**
     * Checks input parameters and either throws {@code ArrayIndexOutOfBoundsException} or returns
     * proper loop-variable starting &amp; ending values.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LV_IMPT_NOTE>
     *
     * @param arr This may be an array of any type {@code Object}
     *
     * @param sPos This is the starting position in the {@code 'array'} for the loop-variable 
     * counter being created.  This value is <B>inclusive</B>.  This means that the first element
     * searched by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code 'sPos'}</I>.
     *
     * <BR /><BR />If all validity checks are passed, {@code 'this.start'} is assigned the value of
     * {@code 'sPos'}.
     *
     * @param ePos This is the ending position in the {@code 'array'} for the loop-variable counter
     * being created.  This value is <B>exclusive</B>.  This means that the last element searched
     * by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code ePos - 1}</I>.
     *
     * <BR /><BR />A negative value may be passed to {@code 'ePos'} - and if so, {@code this.end}
     * shall be set to {@code array.length}, otherwise {@code this.end} is assigned the value of
     * {@code 'ePos'}.
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     */
    public <T> LV(T[] arr, int sPos, int ePos)
    {
        int length = arr.length;

        if ((length == 0) && (sPos == 0) && (ePos <= 0))
        { this.start = this.end = 0; return; }

        if (sPos >= length) throw new ArrayIndexOutOfBoundsException(
            "Starting Array Position is greater than or equal to the Array's length:\n" +
            NOTEA(length, sPos, ePos)
        );

        if (sPos < 0) throw new ArrayIndexOutOfBoundsException
            ("Starting Array Position is negative: " + NOTEA(length, sPos, ePos));

        if (ePos > length) throw new IndexOutOfBoundsException(
            "Ending Array Position is greater than the length of the Array:\n" +
            NOTEA(length, sPos, ePos)
        );

        if (ePos == 0) throw new ArrayIndexOutOfBoundsException
            ("Ending Array Position is zero.:\n" + NOTEA(length, sPos, ePos));

        this.start  = sPos;
        this.end    = (ePos <= 0) ? length : ePos;

        if (start > end) throw new IllegalArgumentException(
            "The starting and ending Array Positions are not properly chosen:\n" +
            NOTEA(length, sPos, ePos)
        );
    }

    /**
     * Checks input parameters and either throws {@code ArrayIndexOutOfBoundsException} or returns
     * proper loop-variable starting &amp; ending values.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=LV_IMPT_NOTE>
     * 
     * <BR /><BR />In this particular method, when {@code 'ePos'} is passed a Negative-Value, the
     * length of the input-array parameter {@code 'primitiveArray'} (the value assigned to
     * {@link #end}) is computed using a heuristic from {@code java.lang.reflect}.
     *
     * @param primitiveArray This may be an array of any <B>primitive</B> type. {@code int[],
     * float[], boolean[]}, etc...
     *
     * @param sPos This is the starting position in the {@code 'array'} for the loop-variable 
     * counter being created.  This value is <B>inclusive</B>.  This means that the first element
     * searched by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code 'sPos'}</I>.
     *
     * <BR /><BR />If all validity checks are passed, {@code 'this.start'} is assigned the value of
     * {@code 'sPos'}.
     *
     * @param ePos This is the ending position in the {@code 'array'} for the loop-variable counter
     * being created.  This value is <B>exclusive</B>.  This means that the last element searched
     * by {@code 'this'} loop-variable counter instance <I>shall be at the index 
     * {@code ePos - 1}</I>.
     *
     * <BR /><BR />A negative value may be passed to {@code 'ePos'} - and if so, {@code this.end}
     * shall be set to {@code primitiveArray.length}, otherwise {@code this.end} is assigned the
     * value of {@code 'ePos'}.
     *
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * 
     * @throws ArrayExpectedError This error is thrown if the reference passed to parameter
     * {@code 'primitiveArray'} is not actually a reference to a {@code byte[], short[], int[]}
     * etc... primitive array.  An error is used because the whole purpose of the class {@code LV}
     * is to help reduce programming errors with automatic for-loop bounds checking.  If, in the
     * course of exception checking, another exception is thrown it signals a more fundamental
     * mistake has been made.
     */
    public LV(int sPos, int ePos, Object primitiveArray)
    {
        if (! primitiveArray.getClass().isArray()) throw new ArrayExpectedError(
            "The Object passed to 'primitiveArray' is not an actually an array, but " +
            "rather an instance of [" + primitiveArray.getClass().getName() + ']'
        );

        int length = java.lang.reflect.Array.getLength(primitiveArray);

        if ((length == 0) && (sPos == 0) && (ePos <= 0))
        { this.start = this.end = 0; return; }

        if (sPos >= length) throw new ArrayIndexOutOfBoundsException(
            "Starting Array Position is greater than or equal to the Array's length:\n" +
            NOTEA(length, sPos, ePos)
        );

        if (sPos < 0) throw new ArrayIndexOutOfBoundsException
            ("Starting Array Position is negative: " + NOTEA(length, sPos, ePos));

        if (ePos > length) throw new ArrayIndexOutOfBoundsException(
            "Ending Array Position is greater than the length of the Array:\n" +
            NOTEA(length, sPos, ePos)
        );

        if (ePos == 0) throw new ArrayIndexOutOfBoundsException
            ("Ending Array Position is zero.:\n" + NOTEA(length, sPos, ePos));

        this.start  = sPos;
        this.end    = (ePos <= 0) ? length : ePos;

        if (start > end) throw new IllegalArgumentException(
            "The starting and ending Array Positions are not properly chosen:\n" +
            NOTEA(length, sPos, ePos)
        );
    }
}