package Torello.HTML;

import java.util.stream.*;
import java.util.*;

import Torello.Java.LV;
import Torello.Java.StrCSV;
import Torello.Java.ExceptionCheckError;

/**
 * A simple utility class that, used ubiquitously throughout Java HTML, which maintains two integer
 * fields - <CODE><B><A HREF='#start'>DotPai&#46;start</A></B></CODE> and
 * <CODE><B><A HREF='#end'>DotPai&#46;end</A></B></CODE> , for demarcating the begining and ending
 * of a sub-list within an HTML web-page.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=DOT_PAIR>
 * 
 * @see NodeIndex
 * @see SubSection
 */
public final class DotPair
implements java.io.Serializable, Comparable<DotPair>, Cloneable, Iterable<Integer>
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;

    /**
     * This is intended to be the "starting index" into an sub-array of an HTML {@code Vector} of
     * {@code HTMLNode} elements.
     */
    public final int start;

    /**
     * This is intended to be the "ending index" into a sub-array of an HTML {@code Vector} of 
     * {@code HTMLNode} elements.
     */
    public final int end;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This constructor takes two integers and saves them into the {@code public} member fields.
     * 
     * @param start This is intended to store the starting position of a vectorized-webpage
     * sub-list or subpage.
     * 
     * @param end This will store the ending position of a vectorized-html webpage or subpage.
     * 
     * @throws IndexOutOfBoundsException A negative {@code 'start'} or {@code 'end'}
     * parameter-value will cause this exception throw.
     * 
     * @throws IllegalArgumentException A {@code 'start'} parameter-value that is larger than the
     * {@code 'end'} parameter will cause this exception throw.
     * 
     * @see NodeIndex
     * @see SubSection
     */
    public DotPair(int start, int end)
    {
        if (start < 0) throw new IndexOutOfBoundsException
            ("Negative start value passed to DotPair constructor: start = " + start);

        if (end < 0) throw new IndexOutOfBoundsException
            ("Negative ending value passed to DotPair constructor: end = " + end);

        if (end < start) throw new IllegalArgumentException(
            "Start-parameter value passed to constructor is greater than ending-parameter: " +
            "start: [" + start + "], end: [" + end + ']'
        );

        this.start  = start;
        this.end    = end;
    }

    /**
     * Creates a new instance that has been shifted by {@code 'delta'}.
     * 
     * @param delta The number of array indices to shift {@code 'this'} intance.  This parameter
     * may be negative, and if so, {@code 'this'} will be shifted left, instead of right.
     * 
     * @return A new, shifted, instance of {@code 'this'}
     */
    public DotPair shift(int delta)
    { return new DotPair(this.start + delta, this.end + delta); }


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


    /**
     * Implements the standard java {@code 'hashCode()'} method.  This will provide a hash-code
     * that is 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); }

    /**
     * The purpose of this is to remind the user that the array bounds are inclusive at <B>BOTH</B>
     * ends of the sub-list.  
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Inclusive &amp; Exclusive:</B>
     * 
     * <BR />For an instance of {@code 'DotPair'}, the intention is to include both the
     * characters located at the {@code Vector}-index positions {@link #start} and the one at
     * {@link #end}.  Specifically,  (and unlike many of the {@code Node-Search} package methods)
     * both of the internal fields to this class are <B STYLE='color: red'><I>inclusive</I></B>,
     * rather than exclusive.
     * 
     * <BR /><BR />For many of the search methods in package {@link Torello.HTML.NodeSearch}, the
     * {@code 'ePos'} parameters are always <B STYLE='color: red'><I>exclusive</I></B> - meaning
     * the character at {@code Vector}=index {@code 'ePos'} is not included in the search.
     * 
     * @return The length of a sub-array that would be indicated by this dotted pair.
     */
    public int size() { return this.end - this.start + 1; }

    /**
     * Java's {@code toString()} requirement.
     * 
     * @return A string representing 'this' instance of DotPair.
     */
    public String toString() { return "[" + start + ", " + end + "]"; }

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

        else return false;
    }

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

    /**
     * Java's {@code interface Comparable<T>} requirements.  <I>This is not the only comparison4
     * operation possible,</I> but it does satisfy one reasonable requirement -
     * <I>SPECIFICALLY:</I> which of two separate instances of {@code DotPair} start first.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Comparator Heuristic:</B>
     * 
     * <BR />If two {@code DotPair} instances begin at the same {@code Vector}-index, then the
     * shorter of the two shall come first.
     * 
     * @param other Any other {@code DotPair} to be compared to {@code 'this' DotPair}
     * 
     * @return An integer that fulfils Java's
     * {@code interface Comparable<T> public boolean compareTo(T t)} method requirements.
     */
    public int compareTo(DotPair other)
    {
        int ret = this.start - other.start;

        return (ret != 0) ? ret : (this.size() - other.size());
    }

    /**
     * This is an "alternative Comparitor" that can be used for sorting instances of this class.
     * It should work with the {@code Collections.sort(List, Comparator)} method in the standard
     * JDK package {@code java.util.*;}
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Comparator Heuristic:</B>
     * 
     * <BR />This "extra <CODE>Comparitor</CODE>" simply compares the size of one {@code DotPair}
     * to a second.  The smaller shall be sorted first, and the larger (longer-in-length)
     * {@code DotPair} shall be sorted later.  If they are of equal size, whichever of the two has
     * an earlier {@link #start} position in the {@code Vector} is considered first.
     * 
     * @see CommentNode#body
     */
    public static Comparator<DotPair> comp2 = (DotPair dp1, DotPair dp2) ->
    {
        int ret = dp1.size() - dp2.size();

        return (ret != 0) ? ret : (dp1.start - dp2.start);
    };

    /**
     * This shall return an {@code int Iterator} (which is properly named
     * {@code class java.util.PrimitiveIterator.OfInt}) that iterates integers beginning with the
     * value in {@code this.start} and ending with the value in {@code this.end}.
     * 
     * @return An {@code Iterator} that iterates {@code 'this'} instance of {@code DotPair} from
     * the beginning of the range, to the end of the range.  The {@code Iterator} returned will
     * produce Java's primitive type {@code int}.
     * 
     * <BR /><BR /><B STYLE='color:red;'>NOTE:</B> The elements returned by the {@code Iterator}
     * are integers, and this is, in effect, nothing more than one which counts from {@link #start}
     * to {@link #end}.
     */
    public PrimitiveIterator.OfInt iterator()
    { 
        return new PrimitiveIterator.OfInt()
        {
            private int cursor = start;

            public boolean hasNext()    { return this.cursor <= end; }

            public int nextInt()
            {
                if (cursor == end) throw new NoSuchElementException
                    ("Cursor has reached the value stored in 'end' [" + end + "]");

                return cursor++;
            }
        };
    }

    /**
     * A simple {@code Iterator} that will iterate elements on an input page, using {@code 'this'}
     * intance of {@code DotPair's} indices, {@link #start}, and {@link #end}.
     * 
     * @param page This may be any HTML page or sub-page.  This page should correspond to 
     * {@code 'this'} instance of {@code DotPair}.
     * 
     * @return An {@code Iterator} that will iterate each node in the page, beginning with the
     * node at {@code page.elementAt(this.start)}, and ending with {@code page.elementAt(this.end)}
     * 
     * @throws IndexOutOfBoundsException This throws if {@code 'this'} instance does not have a
     * range that adheres to the size of the input {@code 'page'} parameter.
     */
    public <T extends HTMLNode> Iterator<T> iterator(Vector<T> page)
    {
        if (this.start >= page.size()) throw new IndexOutOfBoundsException(
            "This instance of DotPair points to elements that are outside of the range of the" +
            "input 'page' Vector.\n" +
            "'page' parameter size: " + page.size() + ", this.start: [" + this.start + "]"
        );

        if (this.end >= page.size()) throw new IndexOutOfBoundsException(
            "This instance of DotPair points to elements that are outside of the range of the" +
            "input 'page' Vector.\n" +
            "'page' parameter size: " + page.size() + ", this.end: [" + this.end + "]"
        );

        return new Iterator<T>()
        {
            private int cursor          = start;    // a.k.a. 'this.start'
            private int expectedSize    = page.size();
            private int last            = end;      // a.k.a. 'this.end'

            public boolean hasNext() { return cursor < last; }

            public T next()
            {
                if (++cursor > last) throw new NoSuchElementException(
                    "This iterator's cursor has run past the end of the DotPaiar instance that " +
                    "formed this Iterator.  No more elements to iterate.  Did you call hasNext() ?"
                );

                if (page.size() != expectedSize) throw new ConcurrentModificationException(
                    "The expected size of the underlying vector has changed." +
                    "\nCurrent-Size " +
                    "[" + page.size() + "], Expected-Size [" + expectedSize + "]\n" +
                    "\nCursor location: [" + cursor + "]"
                );

                return page.elementAt(cursor);
            }

            // Removes the node from the underlying {@code Vector at the cursor's location.
            public void remove()
            { page.removeElementAt(cursor); expectedSize--; cursor--; last--; }
        };
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Simple Boolean tests
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This will test whether a specific index is contained (between {@code this.start} and
     * {@code this.end}, inclusively.
     * 
     * @param index This is any integer index value.  It must be greater than zero.
     * 
     * @return {@code TRUE} If the value of index is greater-than-or-equal-to the value stored in
     * field {@code 'start'} and furthermore is less-than-or-equal-to the value of field
     * {@code 'end'}
     * 
     * @throws IndexOutOfBoundsException If the value is negative, this exception will throw.
     */
    public boolean isInside(int index)
    {
        if (index < 0) throw new IndexOutOfBoundsException
            ("You have passed a negative index [" + index + "] here, but this is not allowed.");

        return (index >= start) && (index <= end);
    }

    /**
     * Tests whether {@code 'this' DotPair} is fully enclosed by {@code DotPair} parameter
     * {@code 'other'}
     * 
     * @param other Another {@code DotPair}.  This parameter is expected to be a descriptor of the
     * same vectorized-webpage as {@code 'this' DotPair} is.  It is not mandatory, but if not, the
     * comparison is likely meaningless.
     * 
     * @return {@code TRUE} If (and only if) parameter {@code 'other'} encloses {@code 'this'}.
     */
    public boolean enclosedBy(DotPair other)
    { return (other.start <= this.start) && (other.end >= this.end); }

    /**
     * Tests whether {@code 'this' DotPair} is enclosed, completely, by parameter {@code DotPair}
     * parameter {@code 'other'}
     * 
     * @param other Another {@code DotPair}.  This parameter is expected to be a descriptor of the
     * same vectorized-webpage as {@code 'this' DotPair} is.  It is not mandatory, but if not, the
     * comparison is likely meaningless.
     * 
     * @return {@code TRUE} If (and only if) parameter {@code 'other'} is enclosed completely by
     * {@code 'this'}.
     */
    public boolean encloses(DotPair other)
    { return (this.start <= other.start) && (this.end >= other.end); }

    /**
     * Tests whether parameter {@code 'other'} has any overlapping {@code Vector}-indices with
     * {@code 'this' DotPair}
     * 
     * @param other Another {@code DotPair}.  This parameter is expected to be a descriptor of the
     * same vectorized-webpage as {@code 'this' DotPair} is.  It is not mandatory, but if not, the
     * comparison is likely meaningless.
     * 
     * @return {@code TRUE} If (and only if) parameter {@code 'other'} and {@code 'this'} have any
     * overlap.
     */
    public boolean overlaps(DotPair other)
    {
        return
            ((this.start >= other.start)    && (this.start <= other.end)) ||
            ((this.end >= other.start)      && (this.end <= other.end));
    }

    /**
     * Tests whether {@code 'this'} lays, <I>completely</I>, before {@code DotPair} parameter
     * {@code 'other'}.
     * 
     * @param other Another {@code DotPair}.  This parameter is expected to be a descriptor of the
     * same vectorized-webpage as {@code 'this' DotPair} is.  It is not mandatory, but if not, the
     * comparison is likely meaningless.
     * 
     * @return {@code TRUE} if <I>every index</I> of {@code 'this'} has a value that is less than
     * every index of {@code 'other'}
     */
    public boolean isBefore(DotPair other)
    { return this.end < other.start; }

    /**
     * Tests whether {@code 'this'} begins before {@code DotPair} parameter {@code 'other'}.
     * 
     * @param other Another {@code DotPair}.  This parameter is expected to be a descriptor of the
     * same vectorized-webpage as {@code 'this' DotPair} is.  It is not mandatory, but if not, the
     * comparison is likely meaningless.
     * 
     * @return {@code TRUE} if {@code this.start} is less than {@code other.start}, and
     * {@code FALSE} otherwise.
     */
    public boolean startsBefore(DotPair other)
    { return this.start < other.start; }

    /**
     * Tests whether {@code 'this'} lays, <I>completely</I>, after {@code DotPair} parameter
     * {@code 'other'}.
     * 
     * @param other Another {@code DotPair}.  This parameter is expected to be a descriptor of the
     * same vectorized-webpage as {@code 'this' DotPair} is.  It is not mandatory, but if not, the
     * comparison is likely meaningless.
     * 
     * @return {@code TRUE} if <I>every index</I> of {@code 'this'} has a value that is greater
     * than every index of {@code 'other'}
     */
    public boolean isAfter(DotPair other)
    { return this.start > other.end; }

    /**
     * Tests whether {@code 'this'} ends after {@code DotPair} parameter {@code 'other'}.
     * 
     * @param other Another {@code DotPair}.  This parameter is expected to be a descriptor of the
     * same vectorized-webpage as {@code 'this' DotPair} is.  It is not mandatory, but if not, the
     * comparison is likely meaningless.
     * 
     * @return {@code TRUE} if {@code this.end} is greater than {@code other.end}, and
     * {@code FALSE} otherwise.
     */
    public boolean endsAfter(DotPair other)
    { return this.end > other.end; }




    // ********************************************************************************************
    // ********************************************************************************************
    // Exception Check
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * A method that will do a fast check that {@code 'this'} intance holds index-pointers to
     * an opening and closing HTML-Tag pair.  Note, though these mistakes may seem trivial, when
     * parsing Internet Web-Pages, these are exactly the type of basic mistakes that users will
     * make when their level of 'concentration' is low.  This is no different that checking an
     * array-index or {@code String}-index for an {@code IndexOutOfBoundsException}.
     * 
     * <BR /><BR />This type of detailed exception message can make analyzing web-pages more
     * direct and less error-prone.  The 'cost' incurred includes only a few {@code if}-statement
     * comparisons, and <I>this check should be performed immediatley <B>before a loop is
     * entered.</B></I>
     * 
     * @param page Any web-page, or sub-page.  It needs to be the page from whence {@code 'this'}
     * instance of {@code DotPair} was retrieved.
     * 
     * @throws TagNodeExpectedException If {@code 'this'} instance' {@link #start} or {@link #end}
     * fields do not point to {@code TagNode} elements on the {@code 'page'}.
     * 
     * @throws HTMLTokException If {@link #start} or {@link #end} do not point to a {@code TagNode}
     * whose {@link TagNode#tok} field equals the {@code String} contained by parameter
     * {@code 'token'}.
     * 
     * @throws OpeningTagNodeExpectedException If {@link #start} does not point to an opening
     * {@code TagNode}.
     * 
     * @throws ClosingTagNodeExpectedException If {@link #end} does not point to a closing
     * {@code TagNode}.
     * 
     * @throws NullPointerException If the {@code 'page'} parameter is null.
     * 
     * @throws ExceptionCheckError <B STYLE='color:red;'>IMPORTANT</B> Since this method is,
     * indubuitably, a method for performing error checking, the presumption is that the programmer
     * is trying to check for <I>his users input</I>.  If in the processes of checking for user
     * error, another mistake is made that would generate an exception, this must thought of as a
     * more serious error.
     * 
     * <BR /><BR />The purpose of the {@code 'possibleTokens'} array is to check that those tokens
     * match the tokens that are contained by the {@code TagNode's} on the page at index 
     * {@code this.start}, and {@code this.end}.  If invalid HTML tokens, null tokens, or even
     * HTML Singleton tokens are passed <B>this exception-check, itself, is flawed!</B>  If there
     * are problems with this var-args array, this error is thrown.
     * 
     * <BR /><BR />It is more serious because it indicates that the programmer has made a mistake
     * in attempting to check for user-errors.
     */
    public void exceptionCheck(Vector<HTMLNode> page, String... possibleTokens)
    {
        if (page == null) throw new NullPointerException
            ("HTML-Vector parameter was passed a null reference.");

        if (possibleTokens == null) throw new ExceptionCheckError
            ("HTML tags string-list was passed a null reference.");

        for (String token : possibleTokens)
        {
            if (token == null) throw new ExceptionCheckError
                ("One of the HTML Tag's in the tag-list String-array was null.");

            if (! HTMLTags.isTag(token)) throw new ExceptionCheckError
                ("One of the passed tokens [" + token +"] is not a valid HTML token.");

            if (HTMLTags.isSingleton(token)) throw new ExceptionCheckError
                ("One of the passed tokens [" + token +"] is an HTML Singleton.");
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Check the DotPair.start
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (this.start >= page.size()) throw new IndexOutOfBoundsException(
            "DotPair's 'start' field [" + this.start + "], is greater than or equal to the " +
            "size of the HTML-Vector [" + page.size() + "]."
        );

        if (! (page.elementAt(this.start) instanceof TagNode))
            throw new TagNodeExpectedException(this.start);

        TagNode t1 = (TagNode) page.elementAt(this.start);

        if (t1.isClosing) throw new OpeningTagNodeExpectedException(
            "The TagNode at index [" + this.start + "] was a closing " +
            "</" + t1.tok.toUpperCase() + ">, but an opening tag was expected here."
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Now Check the DotPair.end
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (this.end >= page.size()) throw new IndexOutOfBoundsException(
            "DotPair's 'end' field [" + this.end + "], is greater than or equal to the " +
            "size of the HTML-Vector [" + page.size() + "]."
        );

        if (! (page.elementAt(this.end) instanceof TagNode))
            throw new TagNodeExpectedException(this.end);

        TagNode t2 = (TagNode) page.elementAt(this.end);

        if (! t2.isClosing) throw new ClosingTagNodeExpectedException(
            "The TagNode at index [" + this.start + "] was an opening " +
            "<" + t2.tok.toUpperCase() + ">, but a closing tag was expected here."
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Token Check
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (! t1.tok.equalsIgnoreCase(t2.tok)) throw new HTMLTokException(
            "The opening TagNode was the [" + t1.tok.toLowerCase() + "] HTML Tag, while the " +
            "closing Tag was the [" + t2.tok.toLowerCase() + "].  These two tag's must be an " +
            "opening and closing pair, and therefore must match each-other."
        );

        for (String possibleToken : possibleTokens)
            if (possibleToken.equalsIgnoreCase(t1.tok))
                return;

        String t = t1.tok.toUpperCase();

        throw new HTMLTokException(
            "The opening and closing tags were: <" + t + ">, and </" + t + ">, but " +
            "unfortunately this Tag is not included among the list of expected tags:\n" +
            "    [" + StrCSV.toCSV(possibleTokens, false, false, 60) + "]."
        );
    }

    /**
     * Performs an exception check, using {@code 'this'} instance of {@code DotPair}, and throws
     * an {@code IndexOutOfBoundsException} if {@code 'this'} contains end-points that do not fit
     * inside the {@code 'page'} Vector Parameter.
     * 
     * @param page Any HTML Page, or subpage.  {@code page.size()} must return a value that is
     * larger than <B STYLE='color: red;'>BOTH</B> {@link #start}
     * <B STYLE='color:red;'>AND</B> {@link #end}.
     * 
     * @throws IndexOutOfBoundsException A value for {@link #start} or {@link #end} which
     * are larger than the size of the {@code Vector} parameter {@code 'page'} will cause this
     * exception throw.
     */
    public void exceptionCheck(Vector<HTMLNode> page)
    {
        if (this.end >= page.size()) throw new IndexOutOfBoundsException(
            "The value of this.end [" + this.end + "] is greater than the size of Vector " +
            "parameter 'page' [" + page.size() + "]"
        );

        // This is actually unnecessary.  If 'end' is fine, then 'start' must be fine.  If 'end' is
        // out of bounds, then it is irrelevant whether 'start' is out of bounds.  "They" play with
        // your brain when you are coding.

        /*
        if (this.start >= page.size()) throw new IndexOutOfBoundsException(
            "The value of this.start [" + this.start + "] is greater than the size of Vector " +
            "parameter 'page' [" + page.size() + "]"
        );
        */
    }
}