package Torello.HTML.NodeSearch;

import java.util.*;

import java.util.function.Predicate;

import Torello.HTML.*;

import Torello.Java.LV;

/**
 * A Java Generic {@code Iterator}-Class that for iterating {@link TagNode}, {@link TextNode} and
 * {@code CommentNode} instances which match user-provided search-criteria.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_EXTENDS_LITER>
 * <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_EASY_TO_USE>
 * 
 * @param <E> The type of {@code HTMLNode} being iterated.
 */
@SuppressWarnings("unchecked")
@Torello.JavaDoc.JDHeaderBackgroundImg
public class HNLI<E extends HTMLNode> extends AbstractHNLI<E, E>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Private Fields
    // ********************************************************************************************
    // ********************************************************************************************


    // -1 means a "Right-Direction Match" has not been found/identified yet.
    private int hasNextVectorPos = -1;

    // -1 means a "Left-Direction Match" has not been found/identified yet.
    private int hasPrevVectorPos = -1;


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


    /**
     * This will produce an {@code Iterator<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.
     *
     * @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 an instance of {@code 'E'} to be a "Match."
     *
     * @param c This parameter should just be the value of a call to {@code 'E'.getClass()} where
     * {@code 'E'} is the instance of the variable-type parameter {@code 'E'} used in this method.
     */
    HNLI (Vector<? extends HTMLNode> html, Predicate<E> p, Class<E> c)
    { super(html, p, c); }

    void RESET_MATCHES() { hasNextVectorPos = hasPrevVectorPos = -1; }

    int REMOVE() { v.remove(cursor); return 1; }


    // ********************************************************************************************
    // ********************************************************************************************
    // "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 node-match.  This method shall return
     * {@code FALSE} if calling {@code previous} would generate / throw a
     * {@code 'NoSuchElementException'} - <I>because there are no more 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>
     */
    public boolean hasPrevious()
    {
        CHECK_CME();

        if (hasPrevVectorPos != -1) return true;

        Object o; // Temp Object

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

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

        // System.out.println("Loop Boundary: " + LOOP_BOUNDARY + ", cursor: " + cursor);

        while (--cursor >= LOOP_BOUNDARY)

            if (c.isInstance(o = v.elementAt(cursor)) && p.test(c.cast(o)))
            {
                hasPrevVectorPos = cursor;
                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 left-direction, or in the direction of
     * decreasing {@code Vector}-indices.</I>
     *
     * @return This shall return the node-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 aren't any more matches available, 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
     * {@code TRUE}.
     */
    public E previous()
    { return (E) v.elementAt(previousIndex()); }

    /**
     * Returns the nearest node-match, <I><B>as an integer {@code Vector}-index</I></B>, 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 node-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 aren't any more matches available, this exception
     * shall throw.  Avoid having to catch this exception by always calling method
     * {@code 'hasPrevious()'}, and only invoking {@code 'previousIndex()'} if that method
     * returned <B>TRUE.</B>
     */
    public int previousIndex()
    {
        CHECK_CME();

        int temp = hasPrevVectorPos;

        hasPrevVectorPos = hasNextVectorPos = -1;
        modifiedSince = false;

        if (temp != -1) return temp;

        Object o; // Temp Object

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

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

        while (--cursor >= LOOP_BOUNDARY)

            if (c.isInstance(o = v.elementAt(cursor)) && p.test(c.cast(o)))
                return cursor;

        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 node-match.  This method shall return {@code FALSE} if calling
     * {@code next()} would generate / throw a {@code 'NoSuchElementException'} - <I>because there
     * are no more 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>
     */
    public boolean hasNext()
    {
        CHECK_CME();

        if (hasNextVectorPos != -1) return true;

        Object o; // Temp Object

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

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

        // System.out.println("Loop Boundary: " + LOOP_BOUNDARY + ", cursor: " + cursor);

        while (++cursor <= LOOP_BOUNDARY)

            if (c.isInstance(o = v.elementAt(cursor)) && p.test(c.cast(o)))
                { hasNextVectorPos=cursor;  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 node-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 aren't any more matches available, 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 {@code TRUE}.
     */
    public E next()
    { return (E) v.elementAt(nextIndex()); }

    /**
     * Returns the nearest node-match, <I><B>as an integer {@code Vector}-index</I></B>, 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 node-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 aren't any more matches available, this exception
     * shall throw.  Avoid having to catch this exception by always calling method
     * {@code 'hasNext()'}, and  only invoking {@code 'nextIndex()'} if that method returned
     * <B>TRUE.</B>
     */
    public int nextIndex()
    {
        CHECK_CME();

        int temp = hasNextVectorPos;

        hasPrevVectorPos = hasNextVectorPos = -1;
        modifiedSince = false;

        if (temp != -1) return temp;

        Object o; // Temp Object

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

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

        while (++cursor <= LOOP_BOUNDARY)

            if (c.isInstance(o = v.elementAt(cursor)) && p.test(c.cast(o)))
                return cursor;

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


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


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #firstIndex()}
     * <BR />Retrieves: {@code 'E'} node-instance from the {@code Vector}
     */
    public E first()
    { return (E) v.elementAt(firstIndex()); }

    /**
     * This method will "reset the internal {@code cursor}" to the beginning, and return the index
     * of the first node-match (rather than the node itself).
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     *
     * @return The index of the very-first node-match in this list.  As with other
     * {@code Iterator}-retrieval methods, if the underlying {@code Vector} has been changed using
     * calls to: {@code set, remove,} or {@code add}, then this method will return the
     * first-integer index of the node-match for the modified-{@code Vector}.
     */
    public int firstIndex()
    {
        cursor              = (minCursor == -1) ? 0 : minCursor;
        hasNextVectorPos    = hasPrevVectorPos = -1;
        expectedSize        = v.size();
        
        // NOTE: A call to first, last, firstIndex, or lastIndex
        // "resets" the CME Monitor-Logic ==> expectedSize = v.size();

        return nextIndex();
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #lastIndex()}
     * <BR />Retrieves: {@code 'E'} node-instance from the {@code Vector}
     */
    public E last()
    { return (E) v.elementAt(lastIndex()); }

    /**
     * This method will "advance the internal {@code cursor}" to the end of the {@code Vector}, and
     * return the index of the last node-match (rather than the node itself).
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     *
     * @return The index of the very-last node-match in this list.  As with other
     * {@code Iterator}-retrieval methods, if the underlying {@code Vector} has been changed using
     * calls to: {@code set, remove,} or {@code add}, then this method will return the
     * last-integer index of the node-match for the modified-{@code Vector}.
     */
    public int lastIndex()
    {
        cursor              = (maxCursor == -1) ? (v.size() - 1) : maxCursor;
        hasNextVectorPos    = hasPrevVectorPos = -1;
        expectedSize        = v.size();

        // NOTE: A call to first, last, firstIndex, or lastIndex
        // "resets" the CME Monitor-Logic ==> expectedSize = v.size();

        return previousIndex();
    }
}