package Torello.HTML.NodeSearch;

import java.util.*;

import java.util.function.Predicate;

import Torello.HTML.*;

import Torello.Java.LV;
import Torello.HTML.Util.Inclusive;

/**
 * Iterates <B>'Inclusive'</B> {@link TagNode} sublist-matches, which would be similar to iterating
 * the <CODE>'&#46;innerHTML'</cODE> fields of elements in a JavaScript DOM-Tree.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_EXTENDS_LITER>
 * <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_EASY_TO_USE>
 */
@SuppressWarnings("unchecked")
@Torello.JavaDoc.JDHeaderBackgroundImg
public class HNLIInclusive extends AbstractHNLI<TagNode, Vector<HTMLNode>> 
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Private, Non-Static, Fields
    // ********************************************************************************************
    // ********************************************************************************************


    private DotPair hasNextDP       = null;
    private DotPair hasPrevDP       = null;
    private DotPair lastReturned    = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // Only Constructor **AND** Package-Private Abstract-Method Implementations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This will produce an P@code Iterator} with generic type {@code 'E'}.  The last parameter to
     * this constructor {@code Class<E> c} is required since as per Java's Erasure "Feature" -
     * there is no way to identify what the Variable-Type Parameter {@code 'E'} evaluates at
     * Run-Time.
     * 
     * <BR /><BR /><B><SPAN STYLE="color: red;">PROTECTED NOTE:</B></SPAN> This method is, by
     * necessity kept {@code 'protected'} because of the nature of what constitutes an match for a
     * {@code TagNode} when <B>'Inclusive'</B> Sublists are to be returned.
     * 
     * @param html This may be any HTML {@code Vector} or sub-section.
     *
     * @param p This is a {@code java.util.function.Predicate} that identifies when the
     * {@code Iterator} should consider a {@code TagNode} a "Match."
     */
    HNLIInclusive (Vector<? extends HTMLNode> html, Predicate<TagNode> p)
    { super(html, p, TagNode.class); }

    void RESET_MATCHES() { hasNextDP = hasPrevDP = lastReturned = null; }

    int REMOVE() { return Util.Remove.range(v, lastReturned); }


    // ********************************************************************************************
    // ********************************************************************************************
    // HELPER
    // ********************************************************************************************
    // ********************************************************************************************


    private DotPair TEST_CURSOR_INCLUSIVE()
    {
        Object o = v.elementAt(cursor);

        if (! (o instanceof TagNode)) return null;

        TagNode tn = (TagNode) o;

        if (tn.isClosing) return null;

        if (! p.test(tn)) return null;

        if (maxCursor == -1)    return Inclusive.dotPairOPT(v, cursor);
        else                    return Inclusive.dotPairOPT(v, cursor, maxCursor);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // "Previous" - Retrieval Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Use this method to find out whether the underlying {@code Vector} and current {@code cursor}
     * position would retrieve another match if {@code 'previous'} or {@code 'previousIndex'} were
     * called.
     * 
     * @return This shall return {@code TRUE} if calling the {@code previous()}, or 
     * {@code previousIndex()} methods would return another inclusive / sub-list node-match.  This
     * method shall return {@code FALSE} if calling {@code previous()} would generate / throw a 
     * {@code 'NoSuchElementException'} - <I>because there are no more sub-list matches in the
     * underlying {@code Vector}, given the current {@code cursor} position.</I>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public boolean hasPrevious()
    {
        CHECK_CME();

        if (hasPrevDP != null) return true;

        int LOOP_BOUNDARY = (minCursor == -1) ? 0 : minCursor;

        if (cursor == -1) cursor = LOOP_BOUNDARY;  // will return false

        while (--cursor >= LOOP_BOUNDARY)

            if ((hasPrevDP = TEST_CURSOR_INCLUSIVE()) != null)
                return true;

        return false;
    }

    /**
     * Returns the nearest sub-list match in the underlying {@code Vector}, given the current
     * {@code cursor} position - <I>when searching in the left-direction, or in the direction of
     * decreasing {@code Vector}-indices.</I>
     * 
     * @return This shall return the sub-list match that is directly previous to the current
     * {@code cursor} position.
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @throws NoSuchElementException If there are not more matches, this exception shall throw.  
     * Avoid having to catch this exception by always calling method {@code 'hasPrevious'}, and
     * only invoking {@code 'previous'} if that method returned <B>TRUE.</B>
     */
    public Vector<HTMLNode> previous()
    { return Util.cloneRange(v, previousDotPair()); }

    /**
     * <EMBED CLASS="defs" DATA-NEXT_PREV=previous>
     * <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_NEXT_PREV_DP>
     *
     * @return The previous integer-pointer pair to the starting-index and ending-index of the
     * previous "inclusive-sublist match" found on the vectorized-html webpage.
     *
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     */
    public DotPair previousDotPair()
    {
        CHECK_CME();

        lastReturned    = hasPrevDP;
        hasNextDP       = hasPrevDP = null;
        modifiedSince   = false;

        if (lastReturned != null) return lastReturned;

        int LOOP_BOUNDARY = (minCursor == -1) ? 0 : minCursor;

        if (cursor == -1) cursor = LOOP_BOUNDARY; // Will throw exception

        while (--cursor >= LOOP_BOUNDARY)

            if ((lastReturned = TEST_CURSOR_INCLUSIVE()) != null)
                return lastReturned;

        throw new NoSuchElementException("There are no more previous elements available.");
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // "Next" - Retrieval Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Use this method to find out whether the underlying {@code Vector} and current {@code cursor}
     * position would retrieve another match if {@code 'next'} or {@code 'nextIndex'} were called.
     * 
     * @return This shall return {@code TRUE} if calling the {@code next()}, or {@code nextIndex()}
     * methods would return another inclusive / sub-list match.  This method shall return
     * {@code FALSE} if calling {@code 'next'} would generate / throw a
     * {@code 'NoSuchElementException'} - <I>because there are no more sub-list matches in the
     * underlying {@code Vector}, given the current {@code cursor} position.</I>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see #CHECK_CME()
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public boolean hasNext()
    {
        CHECK_CME();

        if (hasNextDP != null) return true;

        int LOOP_BOUNDARY = (maxCursor == -1) ? (v.size() - 1) : maxCursor;

        if (cursor == -1) cursor = (minCursor == -1) ? -1 : (minCursor-1);

        while (++cursor <= LOOP_BOUNDARY)

            if ((hasNextDP = TEST_CURSOR_INCLUSIVE()) != null)
                return true;

        return false;
    }

    /**
     * Returns the nearest node-match in the underlying {@code Vector}, given the current
     * {@code cursor} position - <I>when searching in the right-direction, or in the direction of
     * increasing {@code Vector}-indices.</I>
     * 
     * @return This shall return the sub-list match that is directly next to the current
     * {@code cursor} position.
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @throws NoSuchElementException If there are not more matches, this exception shall throw.  
     * Avoid having to catch this exception by always calling method {@code 'hasNext'}, and only
     * invoking {@code 'next'} if that method returned <B>TRUE.</B>
     * 
     * @see #CHECK_CME()
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public Vector<HTMLNode> next()
    { return Util.cloneRange(v, nextDotPair()); }

    /**
     * <EMBED CLASS="defs" DATA-NEXT_PREV=next>
     * <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_NEXT_PREV_DP>
     *
     * @return The next integer-pointer pair to the starting-index and ending-index of the next
     * "inclusive-sublist match" found on the vectorized-html webpage.
     *
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see #CHECK_CME()
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public DotPair nextDotPair()
    {
        CHECK_CME();

        lastReturned    = hasNextDP;
        hasNextDP       = hasPrevDP = null;
        modifiedSince   = false;

        if (lastReturned != null) return lastReturned;

        int LOOP_BOUNDARY = (maxCursor == -1) ? (v.size() - 1) : maxCursor;

        if (cursor == -1) cursor = (minCursor == -1) ? -1 : (minCursor-1);

        while (++cursor <= LOOP_BOUNDARY)

            if ((lastReturned = TEST_CURSOR_INCLUSIVE()) != null)
                return lastReturned;

        throw new NoSuchElementException("There are no more next elements available.");
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // "First" and "Last" - Retrieval Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This adds method {@code public DotPair firstIDotPair()} to the java
     * {@code public interface ListIterator<E>.}
     * This, actually, returns an instance of {@code DotPair}.  Because this {@code Iterator}
     * iterates {@code Vector}-sublists, not individual HTML nodes, the first-index of the first
     * match will be a {@code DotPair}, <I>not an integer.</I>  This (hopefully-obvious) is because
     * the {@code public class DotPair} encapsulates two needed numbers (a {@code Vector}-position
     * start-index, and an ending-index) into a single-data-class.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     *
     * @return Out of the entire vectorized-html webpage, this method resets the internal
     * {@code cursor}, and returns the first {@code 'DotPair'} match - the starting-index and
     * ending-index - of the first "inclusive-sublist match"
     * 
     * @see #nextDotPair()
     * @see #lastDotPair()
     */
    public DotPair firstDotPair()
    {
        cursor          = 0;
        hasNextDP       = hasPrevDP = null;

        // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
        expectedSize    = v.size();

        return nextDotPair();
    }

    /**
     * This does the same as {@code firstIDotPair()} but returns the <B><I>last list
     * match index-pair</I></B> found within the input {@code Vector}.
     *
     * <BR /><BR />This adds method {@code public DotPair lastIDotPair()} to the java
     * {@code public interface ListIterator<E>.}  This, actually, returns an instance of
     * {@code DotPair}.  Because this {@code Iterator} iterates {@code Vector}-sublists, not
     * individual HTML nodes, the last-index of the last match will be a {@code 'DotPair'}
     * <I>not an integer.</I>  This (hopefully obviously) is because the {@code public
     * class DotPair} encapsulates two needed numbers (a {@code Vector}-position start-index,
     * and an ending-index) into a single-data-class.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     *
     * @return Out of the entire vectorized-html webpage, this method resets the internal pointer,
     * and returns the last {@code 'DotPair'} match - the starting-index and ending-index - of the
     * last "inclusive-sublist match"
     * 
     * @see #previousDotPair()
     * @see #firstDotPair()
     */
    public DotPair lastDotPair()
    {
        cursor          = v.size() - 1;
        hasNextDP       = hasPrevDP = null;

        // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
        expectedSize    = v.size();

        return previousDotPair();
    }

    /**
     * This adds to the {@code ListIterator<E>} class by providing a {@code first()} method that
     * resets this {@code Iterator} back to the first match that is found in the underlying
     * html-{@code Vector}.  The internal-{@code cursor} will be moved back to the beginning of
     * the {@code Vector}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Modified Return-Value:</B>
     * 
     * <BR />If the underlying web-page {@code Vector} has been modified, then this method shall
     * return the <I>updated first match.</I>  There is no "match memory."  Rather, if the
     * underlying {@code Vector} changes, further calls to {@code next(), previous(), first()} and
     * {@code last()} would also change.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     *
     * @return This returns the first "inclusive" sub-list (open-tag / start-tag up to the next
     * close-tag) match as a vectorized-html sublist.
     * 
     * @see #next()
     */
    public Vector<HTMLNode> first()
    {
        cursor          = 0;
        hasNextDP       = hasPrevDP = null;

        // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
        expectedSize    = v.size();

        return next();
    }

    /**
     * This adds to the {@code ListIterator<E>} class by providing a {@code last()} method that
     * moves this {@code Iterator} to the last match that is found in the underlying 
     * html-{@code Vector}.  The internal-{@code cursor} will be moved directly to the end of the
     * {@code Vector}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Modified Return-Value:</B>
     * 
     * <BR />If the underlying web-page {@code Vector} has been modified, then this method shall
     * return the <I>updated first match.</I>  There is no "match memory."  Rather, if the
     * underlying {@code Vector} changes, further calls to {@code next(), previous(), first()} and
     * {@code last()} would also change.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     *
     * @return This returns the last "inclusive" sub-list (open-tag / start-tag up to the next
     * close-tag) match as an vectorized-html sublist.
     * 
     * @see #previous()
     */
    public Vector<HTMLNode> last()
    {
        cursor          = v.size() - 1;
        hasNextDP       = hasPrevDP = null;

        // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
        expectedSize    = v.size();

        return previous();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // NEXT and PREVIOUS Index
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The veracity of using this method has been eclipsed by method {@code public
     * previoustDotPair()}.  Nothing problematic should happen, that is unless you forget that this
     * {@code Iterator} is an 'inclusive' {@code Iterator}.  The word "Inclusive" is intended to
     * indicate that a 'range' or 'sublist' (demarcated by a {@code 'start'} and {@code 'end'}
     * {@code Vector}-index pair) are involved.  This is <I>usually-but-not-always</I> expressed
     * using an instance of class {@code 'DotPair'}.  The starting and ending indices are meant to
     * point to HTML opening and closing element tags such as: {@code <DIV>} and {@code </DIV>}, or
     * maybe {@code <A>} and {@code </A>}
     *
     * <BR /><BR />Because this method only returns a single integer, and that is the index of the
     * <I>previous opening HTML Tag</I> matching the iterator's constraints (but leaves off the
     * closing-tag) this method {@code 'previousIndex()'} may seem out of place.
     * 
     * @return Returns the index of the beginning of the previous matched sub-section.
     */
    public int previousIndex() { return previousDotPair().start; }

    /**
     * The veracity of using this method has been eclipsed by method {@code public nextDotPair()}
     * Nothing problematic should happen, that is unless you forget that this {@code Iterator} is
     * an 'inclusive' {@code Iterator}. The word "Inclusive" is intended to indicate that a 'range'
     * or 'sublist' (demarcated by a {@code 'start'} and {@code 'end'} {@code Vector}-index pair)
     * are involved.  This is <I>usually-but-not-always</I> expressed using an instance of class
     * {@code 'DotPair'}.  The starting and ending indices are meant to point to HTML opening and
     * closing element tags such as: {@code <DIV>} and {@code </DIV>}, or maybe {@code <A>} and
     * {@code </A>}
     *
     * <BR /><BR />Because this method only returns a single integer, and that is the index of the
     * <I>next opening HTML Tag</I> matching the iterator's constraints (but leaves off the
     * closing-tag) this method {@code 'nextIndex()'} may seem out of place.
     * 
     * @return Returns the index of the beginning of the next matched sub-section.
     */
    public int nextIndex() { return nextDotPair().start; }

}