package Torello.HTML.NodeSearch;

import java.util.*;

import java.util.function.Predicate;

import Torello.HTML.*;

import Torello.Java.LV;

/**
 * Abstract parent-class for both of the types of HTML-{@code Iterator's}
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=AbstractHNLI>
 * 
 * @param <E> This must be either {@link TagNode}, {@link TextNode} or {@link CommentNode}.
 * This is type of the <I><B>query-specifier {@code Predicate}</B></I> being used.
 * 
 * @param <F> This is the actual-type that will be iterated.  For instances of {@link HNLI},
 * both type-parameters {@code 'E'} and {@code 'F'} are identical.  The {@code Predicate's}
 * will be querrying for a certain type of {@code HTMLNode}, and the {@code Iterator} will be
 * iterating that type of {@code HTMLNode} too.
 * 
 * <BR /><BR />However, for instances of {@link HNLIInclusive}, the query-specifier is 
 * (automatically-required) to be set to {@code TagNode}, and the {@code Iterator} shall be
 * returning instances of {@code Vector<HTMLNode>}.  Generic Type-Parameter {@code 'F'} is
 * automatically set to {@code Vector<HTMLNode>} for instances of {@code HNLIInclusive}.
 */
@SuppressWarnings("unchecked")
@Torello.JavaDoc.JDHeaderBackgroundImg
public abstract class AbstractHNLI<E extends HTMLNode, F> implements ListIterator<F>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // FIELDS
    // ********************************************************************************************
    // ********************************************************************************************


    /** The internal, underlying instance of {@code Vector} that this {@code Iterator} is using. */
    @SuppressWarnings("rawtypes")
    protected Vector v;

    /** This {@code Predicate} is the test for identifying {@code Iterator} node-matches */
    protected Predicate<E> p;

    /** This is the type of {@code HTMLNode} being iterated */
    protected Class<E> c;

    /**
     * Internal {@code 'cursor'} field.
     *
     * <BR /><BR />It is initialized to -1, which allows the iterator to identify whether it has
     * been used yet.
     */
    protected int cursor = -1;

    /**
     * This identifies whether one of the {@code Iterator's} html modification methods
     * ({@code set, remove, add}) have been invoked.  Multiple invocations of these methods
     * after a single iteration causes a {@code SecondModificationException}
     *
     * <BR /><BR />Initializing this to {@code TRUE} prevents the programmer from calling any of
     * the modification methods without first finding a match.
     */
    protected boolean modifiedSince = true;

    /**
     * The maximum boundary for the {@code Cursor Boundary Window}.
     *
     * <BR /><BR />Initialized to {@code '-1'} means the default setting is for the
     * {@code Iterator} is not to use a {@code Cursor Boundaries}.  One may be assigned
     * using the {@code restrictCursor(...)} methods.
     * 
     * @see #restrictCursor(DotPair)
     * @see #restrictCursor(int, int)
     * @see #clearCursorBounds()
     */
    protected int maxCursor = -1;

    /**
     * The minimum boundary for the {@code Cursor Boundary Window}.
     *
     * <BR /><BR />Initialized to {@code '-1'} means the default setting is for the
     * {@code Iterator} is not to use a {@code Cursor Boundaries}.  One may be assigned
     * using the {@code restrictCursor(...)} methods.
     * 
     * @see #restrictCursor(DotPair)
     * @see #restrictCursor(int, int)
     * @see #clearCursorBounds()
     */
    protected int minCursor = -1;

    /** This is an attempt to monitor outside modifications to an HTML {@code Vector} */
    protected int expectedSize;


    // ********************************************************************************************
    // ********************************************************************************************
    // Only Constructor, and 2 Abstract-Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Constructs an instance of this class using an HTML {@code Vector}, and a 
     * {@code Predicate} for testing the nodes in that {@code Vector} for matches.
     * The third parameter {@code 'c'} is only necessary because of Java's type-erasure
     * problem.
     * 
     * @param html Any vectorized HTML page or sub-page.
     * 
     * @param p A {@code java.util.function.Predicate} for testing the nodes in the html 
     * {@code Vector} for matches.
     * 
     * @param c The sub-class of {@code HTMLNode} that this {@code HNLI} shall be searching.
     * The values for parameter {@code 'c'} include: {@code TagNode.class, TextNode}, and
     * {@code CommentNode.class}
     */
    protected AbstractHNLI(Vector<?> html, Predicate<E> p, Class<E> c)
    {
        this.expectedSize   = html.size();
        this.v              = html;
        this.p              = p;
        this.c              = c;
    }

    // Implemented by both sub-classes
    abstract void RESET_MATCHES();

    // Implemented by both sub-classes
    abstract int REMOVE();


    // ********************************************************************************************
    // ********************************************************************************************
    // Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    protected final void MODIFIED()
    {
        modifiedSince   = true;
        expectedSize    = v.size();

        RESET_MATCHES();
    }

    /**
     * This removes the last match that was returned by the {@code Iterator} out of the
     * underlying {@code Vector}.
     * 
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see #CHECK_EXCEPTIONS()
     * @see #MODIFIED()
     */
    public void remove()
    {
        CHECK_EXCEPTIONS();

        int numRemoved = REMOVE();

        if (maxCursor != -1) maxCursor -= numRemoved;

        MODIFIED();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Cursor-Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #moveCursor(int)}
     * <BR />Uses minimum cursor-bound for parameter {@code 'location'}, which would
     * be zero, unless a cursor-window has been set.
     */
    public void moveCursorToStart()
    { moveCursor((minCursor == -1) ? 0 : minCursor); }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #moveCursor(int)}
     * <BR />Uses minimum cursor-bound for parameter {@code 'location'}, which would
     * be {@code v.size() - 1}, unless a cursor-window has been set.
     */
    public void moveCursorToEnd()
    { moveCursor((maxCursor == -1) ? (v.size() - 1) : maxCursor); }

    /**
     * Sets the internal state of this {@code Iterator's} cursor location.  The next invocation of
     * {@code next, previous}, etc... will return the nearest match to this {@code Vector}-index.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     *
     * @param location Any index into the underlying HTML {@code Vector}
     *
     * @throws IndexOutOfBoundsException This shall throw if the value passed to parameter
     * {@code 'location'} is negative, or past the end of the underlying html {@code Vector}.
     *
     * @throws CursorException <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     */
    public void moveCursor(int location)
    {
        if (location < 0) throw new IndexOutOfBoundsException
            ("You have passed a negative value to the cursor location: [" + location + "].");

        if (location > v.size()) throw new IndexOutOfBoundsException(
            "You have passed a cursor location value [" + location + "] that is larger than the " +
            "size of the underlying Vector [" + v.size() + "]"
        );

        CursorException.check(minCursor, maxCursor, location);

        cursor              = location;
        modifiedSince       = true;
        expectedSize        = v.size();

        RESET_MATCHES();
    }

    /**
     * Convenience Method.
     * <BR />Accepts: {@code DotPair}
     * <BR />Invokes: {@link #restrictCursor(int, int)}
     */
    public void restrictCursor(DotPair cursorBounds)
    { restrictCursor(cursorBounds.start, cursorBounds.end); }

    /**
     * Convenience Method.
     * <BR />Accepts: {@code LV}
     * <BR />Invokes: {@link #restrictCursor(int, int)}
     */
    public void restrictCursor(LV loopVariable)
    { restrictCursor(loopVariable.start, loopVariable.end - 1); }

    /**
     * Restrict the internal {@code cursor} boundaries to a window defined by the parameters
     * {@code 'maxCursorBounds'}, and {@code 'minCursorBounds'}.  When the {@code cursor}
     * bounds are restricted, any matches that would be returned by this {@code Iterator} 
     * which lay outside the boundaries of this window shall be skipped or avoided.
     * 
     * <BR /><BR />If the {@code cursor} is currently located outside the boundaries of the
     * given window, it shall be moved to within it.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMERESET>
     * 
     * @param minCursorBounds This shall set a minimum {@code cursor}-index value that restricts
     * the returned matches generated by this {@code HTML Node List Iterator} to indices less
     * than {@code minCursorBounds}.  This is an <I><B>inclusive bound</B></I>.  Matches falling
     * directly on this index may be included in a result set.
     * 
     * @param maxCursorBounds This shall set a maximum {@code cursor}-index value that restricts
     * the returned matches generated by this {@code HTML Node List Iterator} to indices greater
     * than {@code maxCursorBounds}.  This is <B>*also*</B> an <I><B>inclusive bound</B></I>.
     * Matches falling directly on this index may be included in a result set.
     *
     * @throws IndexOutOfBoundsException If the bounds provided by the {@code 'cursorBounds'}
     * input parameter extend past the end of the current underlying {@code Vector}, then this
     * exception shall throw.
     */
    public void restrictCursor(int minCursorBounds, int maxCursorBounds)
    {
        if (minCursorBounds < 0) throw new IndexOutOfBoundsException
            ("The value for parameter 'minPos' [" + minCursorBounds + "] cannot be negative");

        if (maxCursorBounds >= v.size()) throw new IndexOutOfBoundsException(
            "The value for parameter 'maxPos' [" + maxCursorBounds + "] is larger than " +
            "(or equal to) the size of the underlying Vector [" + v.size() + "]."
        );

        this.minCursor = minCursorBounds;
        this.maxCursor = maxCursorBounds;

        if (this.cursor < this.minCursor)
            { RESET_MATCHES();  this.cursor = this.minCursor; }

        else if (this.cursor > this.maxCursor)
            { RESET_MATCHES();  this.cursor = this.maxCursor; }
    }

    /** Eliminates the <B>Cursor Boundary Window</B>, if one had been set. */
    public void clearCursorBounds()
    { this.maxCursor = this.minCursor = -1; }

    /**
     * Retrieves the current location of the cursor.
     * 
     * @return The current location of {@code 'this' Iterator's} cursor.  If {@code hasNext()}
     * or {@code hasPrevious()} has just been called, for example, the cursor will be pointing
     * to the next (or previous) node-match in the HTML {@code Vector}.
     */
    public int cursorLocation()
    { return cursor; }


    // ********************************************************************************************
    // ********************************************************************************************
    // ADD
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #addHTMLNode(HTMLNode)}
     */
    public void add(E e) { addHTMLNode(e); }

    /**
     * This provides a way to <B><I>insert</I></B> an HTML node into the HTML-{@code Vector}.  The
     * node is at the current {@code cursor}-index.  The cursor should be pointing to the location
     * of the last returned match.
     *
     * @param n <EMBED CLASS='external-html' DATA-FILE-ID=HNLIN>
     *
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     *
     * @see #CHECK_EXCEPTIONS()
     * @see #MODIFIED()
     */
    public void addHTMLNode(HTMLNode n)
    {
        CHECK_EXCEPTIONS();

        v.add(cursor, n);

        if (maxCursor != -1) maxCursor++;

        cursor++;

        MODIFIED();
    }

    /**
     * This provides a way to <B><I>insert</I></B> {@code String}-represented HTML.  The HTML will
     * placed in the underlying HTML-{@code Vector} directly before the current
     * {@code cursor}-index.  The {@code cursor} is situated at the location of the last match
     * returned by the {@code Iterator}.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=HTMLSTR>
     * 
     * @param html This is any valid, parse-able HTML section represented as a
     * {@code java.lang.String}.  The {@code String} will be converted to vectorized-html before
     * insertion.
     * 
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see HTMLPage#getPageTokens(CharSequence, boolean)
     */
    public void add(String html) { add(HTMLPage.getPageTokens(html, false)); }

    /**
     * Adds vectorized-HTML at the current {@code cursor} position.
     * 
     * @param html This may be any vectorized HTML page or sub-page.  It will be inserted at the
     * the location of the last returned match.
     * 
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     *
     * @see #CHECK_EXCEPTIONS()
     * @see #MODIFIED()
     */
    public void add(Vector<HTMLNode> html)
    {
        CHECK_EXCEPTIONS();

        v.addAll(cursor, html);

        cursor += html.size();

        if (maxCursor != -1) maxCursor += html.size();
    
        MODIFIED();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // SET
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #setHTMLNode(HTMLNode)}
     */
    public void set(E e) { setHTMLNode(e); }

    /**
     * This provides a way to <B><I>replace</I></B> the previous match with an instance of
     * {@code HTMLNode.}  The match that is replaced is the one that was last returned from a
     * call to any of: {@code next(), previous(), nextIndex(), previousIndex(),} etc...
     *
     * @param n <EMBED CLASS='external-html' DATA-FILE-ID=HNLIN>
     *
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see #remove()
     * @see #cursor
     * @see #expectedSize
     * @see #maxCursor
     */
    public void setHTMLNode(HTMLNode n)
    {
        remove();

        v.add(cursor, n);

        cursor++;

        expectedSize++;

        if (maxCursor != -1) maxCursor++;
    }

    /**
     * Convenience Method.
     * <BR />Invokes: (Parses HTML) {@link HTMLPage#getPageTokens(CharSequence, boolean)}
     * <BR />And-Then: {@link #set(Vector)}
     * <BR /><BR /><B CLASS=JDDescLabel>Efficiency Warning:</B>
     * <BR />This method will will parse (and re-parse) the HTML inside parameter {@code 'html'}
     * everytime this method is invoked!
     */
    public void set(String html) { set(HTMLPage.getPageTokens(html, false)); }

    /**
     * Replaces the last returned match with the contents of parameter {@code 'html'}.
     * 
     * @param html This may be any-sized html page, or sub-page.
     * 
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * 
     * @see Util.Remove#range(Vector, DotPair)
     * @see #remove()
     * @see #cursor
     * @see #expectedSize
     * @see #maxCursor
     */
    public void set(Vector<HTMLNode> html)
    {
        remove();

        v.addAll(cursor, html);

        cursor += html.size();

        expectedSize += html.size();

        if (maxCursor != -1) maxCursor += + html.size();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // INSERT-AT
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Inserts parameter {@code HTMLNode n} into the underlying vectorized-html at
     * {@code Vector}-index {@code 'pos'}.
     *
     * @param n <EMBED CLASS='external-html' DATA-FILE-ID=HNLIN>
     *
     * @param pos This is the location in the underlying {@code Vector} being iterated where the
     * passed parameter {@code 'n'} shall be inserted.
     *
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     *
     * @see #CHECK_EXCEPTIONS(int)
     * @see #MODIFIED()
     */
    public void insertAt(HTMLNode n, int pos)
    {
        CHECK_EXCEPTIONS(pos);

        v.add(pos, n);

        if (pos < cursor) cursor++;

        if (maxCursor != -1) maxCursor++;

        MODIFIED();
    }

    /**
     * Convenience Method.
     * <BR />Invokes: (Parses HTML) {@link HTMLPage#getPageTokens(CharSequence, boolean)}
     * <BR />And-Then: {@link #insertAt(Vector, int)}.
     * <BR /><BR /><B CLASS=JDDescLabel>Efficiency Warning:</B>
     * <BR />This method will will parse (and re-parse) the HTML inside parameter {@code 'html'}
     * everytime this method is invoked!
     */
    public void insertAt(String html, int pos)
    { insertAt(HTMLPage.getPageTokens(html, false), pos); }

    /**
     * Insert the contents of vectorized-html parameter {@code 'html'} into the underlying html
     * {@code Vector}, beginning at position {@code 'pos'}.
     *
     * @param html This may be any HTML page or sub-page.
     *
     * @param pos This is the location in the underlying {@code Vector} being iterated where the
     * passed parameter {@code 'html'} shall be inserted.
     *
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     *
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see #CHECK_EXCEPTIONS(int)
     * @see #MODIFIED()
     */
    public void insertAt(Vector<? extends HTMLNode> html, int pos)
    {
        CHECK_EXCEPTIONS(pos);

        v.addAll(pos, html);

        if (pos < cursor) cursor += html.size();

        if (maxCursor != -1) maxCursor += html.size();

        MODIFIED();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // REPLACE
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #replaceRange(DotPair, Vector)}
     * <BR /><BR /><B CLASS=JDDescLabel>Off-By-One Mistake:</B>
     * <BR />{@code ePos} is decremented by 1, since {@code DotPair.end} is always an
     * <I>inclusive</I> value, while {@code ePos} is always <I>exclusive</I>.
     */
    public void replaceRange(int sPos, int ePos, Vector<HTMLNode> newNodes)
    { replaceRange(new DotPair(sPos, ePos - 1), newNodes); }

    /**
     * This replaces a specified sub-range of nodes in the underlying vectorized-html with the
     * nodes in {@code 'newNodes'}.
     *
     * @param range This is the sub-range or "sub-section" of the underlying vectorized-html page
     * that is going to be replaced by the {@code 'newNodes'}.
     * 
     * @param newNodes These are the nodes to be inserted into the location where the old range is.
     *
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     *
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see Util.Remove#range(Vector, DotPair)
     * @see DotPair#isInside(int)
     * @see DotPair#size()
     * @see #CHECK_EXCEPTIONS(DotPair)
     * @see #MODIFIED()
     */
    public void replaceRange(DotPair range, Vector<HTMLNode> newNodes)
    {
        CHECK_EXCEPTIONS(range);

        Util.replaceRange(v, range, newNodes);

        int sizeChange = newNodes.size() - range.size();

        if (range.isInside(cursor))     cursor = range.start;
        else if(cursor > range.end)     cursor += sizeChange;

        if (maxCursor != -1) maxCursor += sizeChange;
    
        MODIFIED();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // REMOVE
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This removes the node at a specified index in the underlying vectorized-html.
     *
     * @param pos This is the index into the underlying vectorized-html page to be removed.
     *
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     *
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see #CHECK_EXCEPTIONS(int)
     * @see #MODIFIED()
     */
    public void removeElementAt(int pos)
    {
        CHECK_EXCEPTIONS(pos);

        v.removeElementAt(pos);

        if (pos < cursor) cursor--;

        if (maxCursor != -1) maxCursor--;           

        MODIFIED();
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #removeRange(int, int)}
     * <BR /><BR /><B CLASS=JDDescLabel>Off-By-One Mistake:</B>
     * <BR />{@code ePos} is decremented by 1, since {@code DotPair.end} is always an
     * <I>inclusive</I> value, while {@code ePos} is always <I>exclusive</I>.
     */
    public void removeRange(int sPos, int ePos)
    { removeRange(new DotPair(sPos, ePos-1)); }

    /**
     * This removes a specified sub-range of nodes in the underlying vectorized-html.
     *
     * @param range This is the sub-range or "sub-section" of the underlying vectorized-html page;
     *
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     *
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see Util.Remove.range(Vector, DotPair)
     * @see DotPair#isInside(int)
     * @see DotPair#size()
     * @see #CHECK_EXCEPTIONS(DotPair)
     * @see #MODIFIED()
     */
    public void removeRange(DotPair range)
    {
        CHECK_EXCEPTIONS(range);

        Util.Remove.range(v, range);

        if (range.isInside(cursor))     cursor = range.start;
        else if(cursor > range.end)     cursor -= range.size();

        if (maxCursor != -1) maxCursor -= range.size();
    
        MODIFIED();
    }

    /**
     * This will remove every {@code Vector}-element that is identified by the {@code 'posArr'}
     * {@code Vector}-position {@code int[]} array.
     *
     * @param posArr This is a list of nodes that shall be removed from the underlying
     * html-{@code Vector}.
     *
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     *
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see Util.Remove.nodes(boolean, Vector, int[])
     * @see #CHECK_EXCEPTIONS(int[])
     * @see #MODIFIED()
     */
    public void removeElements(int... posArr)
    {
        CHECK_EXCEPTIONS(posArr);

        Util.Remove.nodes(false, v, posArr); // false --> sorts the input int[] array

        int ORIGINAL_CURSOR = cursor;

        for (int pos : posArr)

            if (pos < ORIGINAL_CURSOR) cursor--;
            else break;

        if (maxCursor != -1) maxCursor -= posArr.length;

        MODIFIED();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Exception Checking
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Checks the input position {@code 'pos'} parameter to verify it is not out of the
     * bounds of the underlying HTML-{@code Vector}, nor out of the bounds of the {@code Cursor
     * Boundary Window} - <I>if one has been set.</I>
     *
     * <BR /><BR />This shall throw exceptions if the passed {@code 'range'} is out of either of
     * these bounds.
     * 
     * <BR /><BR />Upon completion of this test, the rest of the standard Exception check-throws
     * are performed.
     *
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * 
     * @see #CHECK_EXCEPTIONS()
     */
    protected void CHECK_EXCEPTIONS(int pos)
    {
        IteratorOutOfBoundsException.check(v, pos);
        CursorException.check(minCursor, maxCursor, pos);

        CHECK_EXCEPTIONS();
    }

    /**
     * Checks the input position {@code 'range'} parameter to verify the provided {@code range}
     * values are not out of the bounds of the underlying HTML-{@code Vector}, nor out of the 
     * bounds of the {@code Cursor Boundary Window} - <I>if one has been set.</I>
     *
     * <BR /><BR />This shall throw exceptions if the passed {@code 'range'} is out of either of
     * these bounds.
     * 
     * <BR /><BR />Upon completion of this test, the rest of the standard Exception check-throws
     * are performed.
     *
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * 
     * @see #CHECK_EXCEPTIONS()
     */
    protected void CHECK_EXCEPTIONS(DotPair range)
    {
        IteratorOutOfBoundsException.check(v, range);
        CursorException.check(minCursor, maxCursor, range);

        CHECK_EXCEPTIONS();
    }

    /**
     * Checks the input position-array {@code 'posArr'} parameter to verify that none of the
     * indices listed in this position-array are out of the bounds of the underlying 
     * HTML-{@code Vector}, nor out of the bounds of the {@code Cursor Boundary Window} - <I>if
     * one has been set.</I>
     *
     * <BR /><BR />This shall throw exceptions if the indices in this input array extend past
     * either of these boundaries.
     * 
     * <BR /><BR />Upon completion of this test, the rest of the standard Exception check-throws
     * are performed.
     *
     * @throws IteratorOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=IOOB_EX>
     * @throws CursorException              <EMBED CLASS='external-html' DATA-FILE-ID=CURSOR_EX>
     * 
     * @see #CHECK_EXCEPTIONS()
     */
    protected void CHECK_EXCEPTIONS(int[] posArr)
    {
        IteratorOutOfBoundsException.check(v, posArr);
        CursorException.check(minCursor, maxCursor, posArr);

        CHECK_EXCEPTIONS();
    }

    /**
     * Does a check regarding whether any exceptions should throw.
     * 
     * @throws IllegalStateException        <EMBED CLASS='external-html' DATA-FILE-ID=HNLI_ILST_EX>
     * @throws SecondModificationException  <EMBED CLASS='external-html' DATA-FILE-ID=SEC_MOD_EX>
     * 
     * @throws ConcurrentModificationException
     * <EMBED CLASS='external-html' DATA-FILE-ID=CONC_MOD_EX>
     * 
     * @see #CHECK_CME()
     */
    protected void CHECK_EXCEPTIONS()
    {
        CHECK_CME();

        if (cursor == -1) throw new IllegalStateException(
            "Neither next, nor previous have been called since initializing the iterator with a " +
            "constructor."
        );

        if (modifiedSince) throw new SecondModificationException(
            "One of the remove, add, or set methods - which are this Iterator's Update (Modifier) " +
            "Operations - has already been called since the prior call to a next, previous, first, " +
            "or last (Inspection) method.  The Modifier and Inspection methods / API of this " + 
            "Iterator may only be used ONCE PER CALL (or, rather, on A ONE-TO-ONE BASIS) with " + 
            "each-other.  In other words, after an invocation of an 'Inspection Method' (such as " +
            "'next'), only one invocation of a 'Modifier Method' (such as 'set') will be allowed " +
            "until another inspection is invoked."
        );
    }

    /**
     * Does a check regarding whether an exception should throw.
     * 
     * @throws ConcurrentModificationException Checks for, and throws if necessary, Java's
     * {@code ConcurrentModificationException}.
     */
    protected void CHECK_CME()  // Because HNLI<E> is an interface, this is actually 'protected'
    {
        if (expectedSize != v.size()) throw new ConcurrentModificationException(
            "The expected size of the underlying vector was: [" + expectedSize + "], but the " +
            "encountered size was: [" + v.size() + "].  This implies that the Vector was modified " +
            "outside of this HNLI Iterator's provided update & modify API.  This is not allowed, " +
            "unless followed by a call to: first, last, firstIndex, or lastIndex - all of which " +
            "'reset' the outside-modification monitor-logic (as do the cursor-movement and cursor " +
            "bounds methods)."
        );
    }
}