package Torello.HTML;

import java.util.*;

import java.util.function.ObjIntConsumer;

// This is only needed for the Java Doc {@link ...} taglets.
import Torello.HTML.NodeSearch.TagNodePeekL1Inclusive;

import Torello.Java.LV;

/**
 * Methods for quickly & efficiently replacing the nodes on a Web-Page.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=REPLACE_NODES>
 */
@Torello.JavaDoc.StaticFunctional
public class ReplaceNodes
{
    private ReplaceNodes() { }

    /**
     * Allows a user to quickly alter each <B STYLE='color: red;'>row</B> in an HTML
     * <B STYLE='color: red;'>table</B>, iteratively, in a manner that offers a tremendous
     * efficiency-improvement over the HTML {@code Iterator's} in the Node Seach Package.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REPL_NODES_FAST DATA-ITEM='table-row'>
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> {@code 'page'} is not null.
     *      </LI>
     * <LI> {@code 'table'} is non-null, and has {@link DotPair#start} and {@link DotPair#end}
     *      indices with integer-values smaller than the size of {@code 'page'}
     *      </LI>
     * <LI> {@code 'table'} has indices which point to {@code TagNode's} in {@code 'page'} that
     *      are opening {@code <TABLE>} and closing {@code </TABLE>} tags.
     *      </LI>
     * </UL>
     * 
     * @param page Any HTML Page or sub-page that has a table.
     * 
     * @param table A pointer to the table start and end index bounds.
     * 
     * @param tableRowModifier <EMBED CLASS='external-html' DATA-TYPE=Table DATA-ENTITY=Row 
     *      DATA-FILE-ID=REPL_NODES_ROW_MOD>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=REPLACEMENT_MRET>
     * <!-- Bororwed from Replacement.run(...) -->
     * 
     * @see TagNodePeekL1Inclusive
     * @see Replacement#run(Vector, Iterable, boolean)
     * @see DotPair#exceptionCheck(Vector, String[])
     * @see SubSection
     * <!-- In the JD Comments 'external-html/' directory, this is filed under 'r02r03/' -->
     */
    public static Vector<HTMLNode> tableTR(
            Vector<HTMLNode> page, DotPair table,
            ObjIntConsumer<Vector<HTMLNode>> tableRowModifier
        )
    {
        // Ensure that page.elementAt(table.start) contains a "<TABLE>" element, and that
        // page.elementAt(table.end) contains a "</TABLE>" element.
        //
        // If some other type of TagNode, or a non-TagNode is present, this method throws one of
        // several exceptions to inform the user about the error.

        table.exceptionCheck(page, "table");

        // Retrieve all "<TR> ... </TR>" elements.  The "L1Inclusive" stipulates that any potential
        // inner-table rows (if there are any inner-tables), should be ignored.

        Vector<SubSection> rows = TagNodePeekL1Inclusive.all(page, table.start, table.end, "tr");

        // All this does is invoke the user-provided function-pointer on each table-row
        for (int i=0; i < rows.size(); i++) tableRowModifier.accept(rows.elementAt(i).html, i);

        // Update all Table-Rows.  Remove the old Rows, and insert the new ones.  This replace
        // operation does this much more efficiently than most replacement-code.

        return Replacement.run(page, rows, false).a;
    }

    /**
     * Allows a user to quickly alter each <B STYLE='color: red;'>item</B> in an HTML
     * <B STYLE='color: red;'>list</B> ({@code <OL>, <UL>} or {@code <MENU>}), iteratively, in a
     * manner that offers a tremendous efficiency-improvement over the HTML {@code Iterator's} in
     * the Node Seach Package.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=REPL_NODES_FAST DATA-ITEM='list-item'>
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> {@code 'page'} is not null.
     *      </LI>
     * <LI> {@code 'list'} is non-null, and has {@link DotPair#start} and {@link DotPair#end}
     *      indices with integer-values smaller than the size of {@code 'page'}
     *      </LI>
     * <LI> {@code 'list'} has indices which point to {@code TagNode's} in {@code 'page'} that
     *      are opening-and-closing {@code <UL>, <OL>} or {@code <MENU>} tags.
     *      </LI>
     * </UL>
     * 
     * @param page Any HTML Page or sub-page that has an {@code <OL>, <UL>} or {@code <MENU>}.
     * 
     * @param list A pointer to the list start and end index bounds.
     * 
     * @param listItemModifier <EMBED CLASS='external-html' DATA-TYPE=List DATA-ENTITY=Item 
     *      DATA-FILE-ID=REPL_NODES_ROW_MOD>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=REPLACEMENT_MRET> <!-- Bororwed from R01 RET -->
     * 
     * @see TagNodePeekL1Inclusive
     * @see Replacement#run(Vector, Iterable, boolean)
     * @see DotPair#exceptionCheck(Vector, String[])
     * @see SubSection
     * <!-- In the JD Comments 'external-html/' directory, this is filed under 'r02r03/' -->
     */
    public static Vector<HTMLNode> listLI(
            Vector<HTMLNode> page, DotPair list,
            ObjIntConsumer<Vector<HTMLNode>> listItemModifier
        )
    {
        // Ensure that page.elementAt(list.start) contains an "<OL>", "<UL>", or "<MENU>" element,
        // and that page.elementAt(list.end) contains an "</OL>", "</UL>" or "</MENU>" element.
        //
        // If some other type of TagNode, or a non-TagNode is present, this method throws one of
        // several exceptions to inform the user about the error.

        list.exceptionCheck(page, "ol", "ul", "menu");

        // Retrieve all "<LI> ... </LI>" elements.  The "L1Inclusive" stipulates that any potential
        // inner-list items (if there are any inner-lists), should be ignored.

        Vector<SubSection> items = TagNodePeekL1Inclusive.all(page, list.start, list.end, "li");

        // All this does is invoke the user-provided function-pointer on each list-item
        for (int i=0; i < items.size(); i++) listItemModifier.accept(items.elementAt(i).html, i);

        // Update all items.  Remove the old-Items, and insert the new ones.  This replace
        // operation does this much more efficiently than most replacement-code.

        return Replacement.run(page, items, false).a;
    }

    /**
     * Iterates the integer-pointer values in {@code int[] posArr}, and replaces the nodes inside
     * {@code 'html'} that have been identified by the {@code 'posArr'} list with a new node
     * supplied by the {@code interface ReplaceFunction}.  It should be obvious, that lambda
     * expressions may be used here.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Returning 'null':</B>
     * 
     * <BR />If the Lambda-Target / Functional-Interface {@link ReplaceFunction} (whose method
     * is named {@link ReplaceFunction#getReplacement(HTMLNode, int, int)}
     * <B><I STYLE='color: red;'>actually returns <CODE>'null'</CODE></I></B>,
     * then null will indeed by inserted into the corresponding {@code Vector} position.
     * 
     * @param html Any HTML page or section that has been loaded already.
     * 
     * @param posArr This is usually generated by one of the node-search {@code 'Find.all(...)'}
     * methods.  Each and every one of the {@code 'Find.all(...)'} methods in the search package
     * will return an array of integers.  These integers represent positions/locations in the
     * passed HTML page {@code Vector}.
     * 
     * @param rf This is just a class that implements the {@code interface ReplaceFunction}.  The
     * interface has a single-method that will receive the position in the {@code Vector}, along
     * with the {@code HTMLNode} found at that location.  It is expected to produce a new version
     * of the {@code HTMLNode}.  This new node will be substituted into the page or sup-page.
     * 
     * <BR /><BR />This function-pointer may return null, and when it does, <I>the node located at
     * the current loop-iteration's {@code Vector}-index will not be replaced</I>.
     * 
     * @return The number of nodes that were succesfully replaced.  This number will be equal to
     * {@code posArr.length} minus the number of times {@code rf} returned null;
     * 
     * @throws ArrayIndexOutOfBoundsException <B><SPAN STYLE="color: red;">IMPORTANT
     * NOTE:</B></SPAN> Usually, a position-{@code array} is generated by one of the search-methods
     * in the NodeSearch package.  If, however, the {@code Vector} has since changed and
     * {@code posArr} contains stale-data, or if for other reasons there are invalid index-pointers
     * in {@code posArr}, then an {@code ArrayIndexOutOfBoundsException} will, naturally, be thrown
     * by java's {@code Vector.setElementAt(...)} method.
     * 
     * @see ReplaceFunction
     */
    public static int r(Vector<HTMLNode> html, int[] posArr, ReplaceFunction rf)
    {
        int counter=0, numReplaced=0;
        HTMLNode n;

        for (int pos : posArr)

            // pos is the vector-position, counter is the "iteration-count"
            if ((n = rf.getReplacement(html.elementAt(pos), pos, counter++)) != null)
            {
                html.setElementAt(n, pos);
                numReplaced++;
            }

        return numReplaced;
    }

    /**
     * This will replace <I>each and every node indicated by {@code 'posArr'}</I> with the
     * exact same replacement node {@code 'n'}.
     *
     * @param html Any HTML page or section that has been loaded already.
     * 
     * @param posArr This is usually generated by one of the node-search {@code 'Find.all(...)'}
     * methods.  Each and every one of the {@code 'Find.all(...)'} methods in the search package
     * will return an array of integers.  These integers represent positions/locations in the
     * passed HTML page {@code Vector}.
     *
     * @param n This may be any non-null {@code HTMLNode}.  This node shall be inserted (and will
     * replace) each node indicated by the parameter {@code 'posArr'}.
     * 
     * @throws ArrayIndexOutOfBoundsException <B><SPAN STYLE="color: red;">IMPORTANT
     * NOTE:</B></SPAN> Usually, a position-{@code array} is generated by one of the search-methods
     * in the NodeSearch package.  If, however, the {@code Vector} has since changed and
     * {@code posArr} contains stale-data, or if for other reasons there are invalid index-pointers
     * in {@code posArr}, then an {@code ArrayIndexOutOfBoundsException} will, naturally, be thrown
     * by java's {@code Vector.setElementAt(...)} method.
     */
    public static void r(Vector<HTMLNode> html, int[] posArr, HTMLNode n)
    { 
        int len= html.size();

        for (int i=0; i < len; i++) html.setElementAt(n, i);
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #r(Vector, int, int, ReplaceFunction)}
     * <BR />Passes: Entire Range of {@code html} into {@code sPos & ePos}
     */
    public static int r(Vector<HTMLNode> html, ReplaceFunction rf)
    { return r(html, 0, -1, rf); }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #r(Vector, int, int, ReplaceFunction)}
     * <BR />Passes: {@link DotPair#start} &amp; {@link DotPair#end} into {@code sPos & ePos}
     */
    public static int r(Vector<HTMLNode> html, DotPair range, ReplaceFunction rf)
    { return r(html, range.start, range.end + 1, rf); }

    /**
     * Iterates <I>the entire html-page, checking every node</I>, replacing them by the
     * values returned by {@code 'rf'} (the replace function).  The {@link ReplaceFunction}
     * (parameter {@code 'rf'}) is expected to return values that either:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>provide a replacement {@code HTMLNode} for the indicated position</LI>
     * <LI>return null as a value - in which case, <I>no substitution will occur</I></LI>
     * </UL>
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Returning 'null':</B>
     * 
     * <BR />If the Lambda-Target / Functional-Interface {@link ReplaceFunction} (whose method
     * is named {@link ReplaceFunction#getReplacement(HTMLNode, int, int)}
     * <B><I STYLE='color: red;'>returns <CODE>'null'</CODE></I></B>,
     * then in this particular method (differing from a previous method in this class), the
     * returned 'null' will be ignored, and no substitution will be performed.
     * 
     * @param html Any HTML page or section that has been loaded already.
     * 
     * @param sPos <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * 
     * @param rf This is just a class that implements the {@code interface ReplaceFunction}.  The
     * interface has a single-method (@code getReplacement(...)} that will receive the position in
     * the {@code Vector}, along with the {@code HTMLNode} found at that location.  It is expected
     * to return a new version of the {@code HTMLNode}.
     * 
     * <BR /><BR />This function-pointer may return null, and when it does, <I>the node located at
     * the current loop-iteration's {@code Vector}-index will not be replaced</I>.
     * 
     * @return The number of nodes that were succesfully replaced.  This number will be equal to
     * {@code html.size()} minus the number of times {@code rf} returned null;
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * 
     * @see ReplaceFunction
     * @see HTMLNode
     */
    public static int r(Vector<HTMLNode> html, int sPos, int ePos, ReplaceFunction rf)
    {
        LV  l           = new LV(html, sPos, ePos);
        int numReplaced = 0;

        for (int i=l.start; i < l.end; i++)
        {
            // Here the vector-position and iteration-number are the same
            HTMLNode n = rf.getReplacement(html.elementAt(i), i, i);

            if (n != null)
            {
                html.setElementAt(n, i);
                numReplaced++;
            }
        }

        return numReplaced;
    }

    /**
     * Iterates the integer-pointer values listed by {@code 'posArr'}, and replaces every position
     * in {@code 'html'} with an {@code HTMLNode} from the nodes provided by the {@code 'newNodes'}
     * parameter.
     * 
     * @param html Any HTML page or section that has been loaded already.
     * 
     * @param posArr This is usually generated by one of the node-search {@code 'Find.all(...)'} 
     * methods.  Each and every one of the {@code 'Find.all(...)'} methods in the search package 
     * will return an {@code int[] array}.  These integers represent positions/locations in the
     * passed HTML page {@code Vector.}
     * 
     * @param newNodes This list of new nodes must have a length identical to the
     * {@code int[] posArr} (pointer-Array) length.
     * 
     * @throws ArrayIndexOutOfBoundsException This exception will throw if any of the elements of
     * {@code 'posArr'} point to a position in the {@code Vector<HTMLNode> v} parameter that are
     * out of bounds for that {@code Vector}.
     * 
     * @throws IllegalArgumentException if the length of the position array (pointer-array) is not
     * identical to the length of the new-nodes {@code Vector.}
     */
    public static void r(Vector<HTMLNode> html, int[] posArr, Vector<HTMLNode> newNodes)
    {
        if (posArr.length != newNodes.size()) throw new ArrayIndexOutOfBoundsException(
            "The pointer array 'posArr', and the replacement-node array 'newNodes' do not have " +
            "equal lengths!\n" +
            "posArr.length=" + posArr.length + ", newNodes.size()=" + newNodes.size()
        );

        int newNodesPos = 0;

        for (int pos : posArr) html.setElementAt(newNodes.elementAt(newNodesPos++), pos);
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #r(Vector, int, int, Vector)}
     */
    public static int r(Vector<HTMLNode> html, DotPair range, Vector<HTMLNode> newNodes)
    { return r(html, range.start, range.end + 1, newNodes); }

    /**
     * Replaces the nodes currently within the vectorized HTML parameter {@code 'html'}, in the
     * sub-range provided by the {@code 'sPos'} and {@code 'ePos'} parameters - <I>using the new
     * nodes provided by {@code Vector}-Parameter {@code 'newNodes'}.</I>  This is, essentially,
     * a sub-range array-replacement operation.
     * 
     * <BR /><BR />Unless exactly the same number of nodes that are in the {@code 'replaceRange'}
     * are also in {@code 'newNodes'}, this method shall have to shorten or lengthen the size of
     * the HTML {@code Vector}.
     * 
     * @param html This may be any HTML page or sub-page
     * @param sPos <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * @param newNodes These are the new {@code HTMLNode's} that are to replace the old ones.
     * @return The change in the size (size-delta) of the input {@code html} parameter.
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     */
    public static int r(Vector<HTMLNode> html, int sPos, int ePos, Vector<HTMLNode> newNodes)
    {
        // The loop variable is needed because its constructor does all of the error checking.
        // The constructor also checks for the negative-ePos, and changes it if it is negative
        //
        // The original version of this method has been deprected, and left as a private method to
        // this class.  It was before noticing the "mirrored" stipulations about Vector-operation
        // "subList"  View the source-code to see the original replace-range method.

        LV l = new LV(html, sPos, ePos);

        List<HTMLNode> list = html.subList(l.start, l.end);

        // The Sun-Oracle Docs say that changes to the list returned by sub-list are mirrored into
        // changes in the original vector.  This is how sub-range operations are done.

        list.clear();
        list.addAll(newNodes);

        return newNodes.size() - (ePos - sPos); // ==> (newSize - originalSize)
    }


    // This was how to do this, until noticing in the Java-Docs that "subList" is "linked"
    // to the original list!

    private static void rOLD(Vector<HTMLNode> html, int sPos, int ePos, Vector<HTMLNode> newNodes)
    {
        LV l = new LV(html, sPos, ePos);

        // Replacement while-loop.  This will replace all nodes that can be replaced in the
        // "replace range" - without growing or shrinking the size of the underlying vector.
        //
        // AFTERWARDS   If there are still more nodes to insert, they will be inserted by
        //              growing the vector.
        //
        // AND ALSO     If there were fewer nodes to insert than the number that need to be
        //              removed the Vector will be shortened.

        int i = 0;
        int j = sPos;

        while ((j < l.end) && (i < newNodes.size()))
        {
            html.setElementAt(newNodes.elementAt(i), j);

            i++; j++;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // CASE 1: The number of nodes to remove is precisely equal to the number being inserted.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (l.size() == newNodes.size()) return;

    
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // CASE 2: The number of nodes being removed is greater than the number being inserted
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Use Util.removeRange(...) to remove the remaining nodes that weren't replaced.
        // More nodes need to be removed than the number of nodes that have already been inserted
        // (in the previous loop).  In this case the original HTML Vector will SHRINK in SIZE.

        if (j < l.end) { Util.Remove.range(html, j, l.end);  return; }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // CASE 3: There are more nodes being added than the number of nodes being removed.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Use Vector.addAll(...) to add the rest which haven't been inserted yet.
        // The HTML Vector is going to grow.  There were fewer nodes removed than the number of
        // nodes that need to be inserted.
        //
        // NOTE: An "intermediate temp Vector" is used since the "Node Shift" is likely done more
        //       efficiently by 'Vector.addAll', than by calling 'Vector.add' multiple times.

        Vector<HTMLNode> temp = new Vector<>(newNodes.size() - i);

        while (i < newNodes.size()) temp.add(newNodes.elementAt(i++));

        html.addAll(l.end, temp);
    }

    /**
     * Convenience Method.
     * Invokes: {@link #r(Vector, int, int, HTMLNode)}
     */
    public static int r(Vector<HTMLNode> html, DotPair range, HTMLNode newNode)
    { return r(html, range.start, range.end + 1, newNode); }

    /**
     * Replaces the nodes currently within the vectorized HTML parameter {@code 'html'}, in the
     * sub-range provided by the {@code 'sPos'} and {@code 'ePos'} parameters, <I>with a single
     * new node provided by {@code 'newNode'}.</I>  Essentially, this is a <B>Range Removal</B>
     * Operation, because a complete sublist is removed, and only a single-node replaces it.
     * 
     * <BR /><BR />Unless the replacement-range (defined by {@code 'sPos'} and {@code 'ePos'}) has
     * a size equal to {@code '1'}, this operation will (obviously) shorten the size of the input
     * HTML {@code Vector} by {@code size - 1} nodes.
     * 
     * @param html This may be any HTML page or sub-page
     * 
     * @param sPos <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * 
     * @param newNode This is the new {@code HTMLNode} that is to replace the (entire) list
     * specified by parameters {@code 'sPos'} and {@code 'ePos'}.
     * 
     * @return The change in the size (size-delta) of the input {@code html} parameter.
     * The number returned will always equal {@code 1 - (ePos - sPos)}.  This means the return
     * value for this method will always be negative (i.e. the {@code Vector} shrunk) - unless
     * {@code sPos} and {@code ePos} had specified a range that was equal to 1.
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     */
    public static int r(Vector<HTMLNode> html, int sPos, int ePos, HTMLNode newNode)
    {
        // This method doesn't have any "for-loops", but the LV class does all the much needed
        // exception checks, and conversion computations. (ePos < 0  ==>  epos = html.size())

        LV l = new LV(html, sPos, ePos);

        html.setElementAt(newNode, l.start);

        if (l.size() > 1)

            // Util.removeRange(html, l.start + 1, l.end);  // OLD-WAY
            html.subList(l.start + 1, l.end).clear();       // NEW & IMPROVED WAY

        return 1 - (ePos - sPos); // ==> (newSize - originalSize)
    }

    /**
     * Replaces the instance of {@code HTMLNode} located at {@code Vector}-index {@code 'pos'}
     * with the contents of {@code Vector} parameter {@code 'newNodes'}.  This removes just
     * a single instance of {@code HTMLNode}, and replaces it with a list of nodes.
     * <BR /><BR />Note that this method will, indeed, lengthen the size of the input HTML
     * {@code Vector} (unless the {@code 'newNodes' Vector} being inserted has only 1 or 0
     * elements).
     *
     * @param html This may be any HTML page or sub-page.
     *
     * @param replacePos The position of the {@code HTMLNode} to be removed and replaced with the
     * list of nodes.
     * 
     * @param newNodes These are the new {@code HTMLNode's} that are to replace the old instance
     * of {@code HTMLNode} at position {@code 'pos'}.
     * 
     * @return The change in the size (size-delta) of the input {@code html} parameter.
     * The number returned will always equal {@code newNodes.size() - 1}
     * 
     * @throws ArrayIndexOutOfBoundsException This exception will throw if the specified 
     * {@code 'pos'} parameter is not within the bounds of the {@code Vector}.
     */
    public static int r(Vector<HTMLNode> html, int replacePos, Vector<HTMLNode> newNodes)
    {
        if (replacePos < 0) throw new ArrayIndexOutOfBoundsException(
            "The position passed to this method [" + replacePos + "] is negative."
        );

        if (replacePos >= newNodes.size()) throw new ArrayIndexOutOfBoundsException(
            "The position passed to this method [" + replacePos + "] is greater than or equal " +
            " to the size of the input HTML Vector parameter, 'html' [" + html.size() + "]"
        );

        html.removeElementAt(replacePos);
        html.addAll(replacePos, newNodes);

        return newNodes.size() - 1; // ==> (newSize - originalSize)
    }
}