package Torello.HTML;

import Torello.Java.StringParse;
import Torello.Java.Additional.Ret2;
import Torello.JavaDoc.StaticFunctional;

import java.util.Vector;
import java.util.Iterator;

/**
 * The means by which the {@link Replaceable} interface may be used to efficiently update a
 * modified HTML-{@code Vector}, <B STYLE='color: red;'><I>quickly, and all-at-once</I></B>.
 * 
 * <BR /><BR />This class has but two public methods.  The both accept a single
 * Java-{@code Vector}, and either a single {@link Replaceable}, or a list of
 * {@link Replaceable Replaceable's}.  These {@code Replaceable's} must have been 'derived' from
 * that self-same input {@code Vector}.
 * 
 * <BR /><BR />The class will iterate those User-Provided {@code Replaceable's},
 * modifying the contents of the original / input {@code Vector} to reflect those changes.
 * 
 * <BR /><BR /><B CLASS=JDDescLabel2>Efficient-Transformations</B>
 * 
 * <BR />The sole benefit of the {@link Replaceable}-{@code interface} is such that it allows a
 * programmer to avoid large numbers of <B STYLE='color: red;'>array-shift</B> and 
 * <B STYLE='color: red;'>array-copy</B> operations.
 * 
 * <BR /><BR />If a user decides to modify the contents of an HTML-Table, for instance, he should
 * first copy the {@link HTMLNode}-Contents of that table out of an input-{@code Vector} and into a
 * Java-HTML {@link SubSection} instance.  Afterwards, the {@link HTMLNode}-Content of that 
 * {@code SubSection} may be modified in any way that the user sees fit.
 * 
 * <BR /><BR />{@code SubSection's} of HTML have vastly smaller amounts of nodes inside
 * their internal-array's (the Java-Package {@code 'java.util.*'} data-structures have array's 
 * among their private data-fields).  Because the amount of nodes in an HTML-{@code SubSection}
 * will always be fewer, the number of node-shifts that are required to modify that HTML will,
 * obviously, always be tremendously fewer too.
 * 
 * <BR /><BR />By using the {@link Replaceable}-{@code interface} classes, a user may hold off the
 * innefficent transformation of a Vectorized-HTML until all changes have been decided, at which
 * point, they may be progpogated back into the original HTML-{@code Vector}, in a single pass 
 * (using this class' sole-method) -<B STYLE='color: red;'><I>thereby avoiding large number of
 * array-copy and shift operations!</I></B>
 * 
 * @see SubSection
 * @see NodeIndex
 */
@Torello.JavaDoc.StaticFunctional
public class Replacement 
{
    private Replacement() {}

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=REPLACEMENT_MDESC>
     * 
     * @param page <EMBED CLASS='external-html' DATA-FILE-ID=REPLACEMENT_MPAGE>
     * @param updatedReplaceables <EMBED CLASS='external-html' DATA-FILE-ID=REPLACEMENT_UREPLS>
     * 
     * @param updateReplaceablesAfterBuild
     *  <EMBED CLASS='external-html' DATA-FILE-ID=REPLACEMENT_URAB>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=REPLACEMENT_MRET>
     * <!-- NOTE: This HTML (for the Return-Description) is borrowed and used in ReplaceNodes -->
     * 
     * @throws ReplaceableOutOfBoundsException  If any of the {@link Replaceable} instances
     * returned by the {@code 'updatedReplaceables'} iterator-parameter have <B><I>original
     * location</I></B> {@code Vector}-indices that are not within the bounds of the HTML
     * page-{@code Vector} (parameter {@code 'page'}).
     * 
     * @throws ReplaceablesOverlappingException If any of the {@link Replaceable} instances
     * returned by the {@code 'updatedReplaceables'} iterator-parameter have <B><I>original
     * location</I></B> {@code Vector}-indices that overlap.
     * 
     * @throws ReplaceablesUnsortedException If any of the {@link Replaceable} instances returned
     * by the {@code 'updatedReplaceables'} iterator-parameter have <B><I>original-starting 
     * locations</I></B> that are non-consecutive (out of order!)
     * 
     * <!-- In the JD Comments 'external-html/' directory, this is filed under 'r0/' -->
     */
    public static
        Ret2<Vector<HTMLNode>, Vector<Replaceable>>
        run(
            final Vector<HTMLNode>                  page,
            final Iterable<? extends Replaceable>   updatedReplaceables,
            final boolean                           updateReplaceablesAfterBuild
        )
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // First check for the case that 'updatedReplaceables' is empty
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final int SIZE = page.size();

        // This entire loop is merely done for nothing more than error/exception checking.
        // It is mandatory that the SubSections which are passed are all 'in-order', that
        // none of them overlap, and that they all fit inside the 'page' vector parameter.

        Iterator<? extends Replaceable> iter = updatedReplaceables.iterator();

        // If there are no Replaceables in the Iterable, return the original page.
        if (! iter.hasNext())
        {
            if (! updateReplaceablesAfterBuild) return new Ret2<>(page, null);

            Vector<Replaceable> ret = new Vector<>();
            for (Replaceable r : updatedReplaceables) ret.add(r);
            return new Ret2<>(page, ret);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Initialize the Loop variables
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Replaceable replaceable         = iter.next();
        Replaceable previousReplaceable = null;

        // These are used, specifically, for the error-checking part of the loop
        int start1  = replaceable.originalLocationStart();
        int end1    = replaceable.originalLocationEnd() - 1;  // Value is Exclusive
        int start2  = -1;
        int end2    = -1;

        // This is used for the exception messages only.  It is incremented on the last line of the
        // loop body.

        int i=0;

        // These are used, specifically, for the part that computes the size the final vector
        int size = 0;   // Total (Future) Size of the Return / Output Vector
        int last = 0;   // Temp Variable, it is easier to have a separate one for this

        while (iter.hasNext())
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Compute what the size of the returned HTML-Vector is going to be.
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // This is done by looking at the locations of all the replacements, and the number of
            // nodes between each replacement.
            //
            // For the part of this loop that is computing the size of the final vector, there
            // start2 and end2 pointers should just be ignored.  The start1, end1 pointer pair
            // are sufficient, as during each iteration, start2 and end2 are assigned to start1 and
            // end1 in the very next step anyways.
    
            size += (start1 - last);            // Size of the previous "in-between chunk"
            size += replaceable.currentSize();  // Size of the next SubSection
            last = end1;                        // advance the 'last' pointer

        
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Advance the Validity-Checking Pointer Pairs
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            // Advance pointer-pair #1 (but DONT'T do this one the VERY FIRST ITERATION)
            if (i > 0)
            {
                start1  = start2;
                end1    = end2;
            }

            // Advance Pointer Pair #2
            previousReplaceable = replaceable;
            replaceable         = iter.next();
            start2              = replaceable.originalLocationStart();
            end2                = replaceable.originalLocationEnd() - 1;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // NOW... THE VALIDITY-CHECKING IF-STATEMENTS
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            /*
            System.out.println(
                "previousReplaceable: " + previousReplaceable +
                ", replaceable: " + replaceable + '\n' +
                "start1: " + start1 + ", end1: " + end1 + ", start2: " + start2 + ", end2: " + end2
            );
            */

            if (start2 < start1)

                throw new ReplaceablesUnsortedException(
                    "'updatedReplaceables' contains at least one Replaceable Element-Pair " +
                    "which is not sorted from first to last:\n" +
                    "The " + (i+1) + StringParse.ordinalIndicator(i+1) + " Replaceable returned " +
                    "by 'updatedReplaceables' starts at page-index " + start1 + '\n' +
                    "The " + (i+2) + StringParse.ordinalIndicator(i+2) + " Replaceable returned " +
                    "by 'updatedReplaceables' starts at page-index " + start2,
                    previousReplaceable, replaceable
                );


            if (    (start2 == start1)  // New section starts at same place as the previous section
                ||  (start2 <= end1)    // New section begins before the previous section ended
    
                // !!! Whenever a user has created a zero-length-replaceable (zero original length)
                // then the "end" of that replaceable will be "start-1".  Sounds a little silly,
                // right?  Well inserting a zero-length replaceable happens a lot in JavaDoc
                // Upgrader.  The two cases of the if-statement are both important.  Remember, the
                // iterator must be returning sorted elements, or else the previous if statement
                // would have already failed.
                )

                throw new ReplaceablesOverlappingException(
                    "'updatedReplaceables' contains at least one Replaceable Element-Pair " +
                    "that overlap each-other:\n" +
                    "The " + (i+1) + StringParse.ordinalIndicator(i+1) + " Replaceable returned " +
                    "by 'updatedReplaceables' has original-location " +
                    "[" + start1 + ", " + end1 + "]\n" +
                    "The " + (i+2) + StringParse.ordinalIndicator(i+2) + " Replaceable returned " +
                    "by 'updatedReplaceables' has original-location " +
                    "[" + start2 + ", " + end2 + ']',
                    previousReplaceable, replaceable
                );

            if (end1 > SIZE)

                throw new ReplaceableOutOfBoundsException(
                    "There was a Replaceable Element whose original-location was not within the " +
                    "bounds of page:\n" +
                    "The " + (i+1) + StringParse.ordinalIndicator(i+1) + " Replaceable returned " +
                    "by 'updatedReplaceables' has original-location " +
                    "[" + start1 + ", " + end1 + "]\n" +
                    "While page.size() is: " + SIZE,
                    replaceable
                );

            i++;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // POST-LOOP FINISHING TOUCHES
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // "Ending Read" Check.  The very last location is not checked, because the loop breaks
        // before it gets to check pointer-pair-2 (on the last iteration)
        //
        // NOTE: The patholigical-cae where there is **ONLY ONE** SubSection in the updatedReplaceables
        //       input Collection.  If pointer-pair-2 is -1, there is no need to check it... :)
        //       If (pointer-pair-2 == -1), the loop body was never entered

        if (end2 != -1) if (end2 >= SIZE)

            throw new ReplaceableOutOfBoundsException(
                "There was a Replaceable Element whose original-location was not within the " +
                "bounds of page:\n" +
                "The " + (i+2) + StringParse.ordinalIndicator(i+2) + " Replaceable returned by " +
                "'updatedReplaceables' has original-location [" + start2 + ", " + end2 + "]\n" +
                "While page.size() is: " + SIZE,
                replaceable
            );

        // the very-last replaceable was not added to the size.
        size += (start1 - last);            // Size of the previous "in-between chunk"
        size += replaceable.currentSize();  // Size of the next SubSection
        last = end1;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Build the Return Vector - NOTE - We just computed its final size!
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // ALSO: If the user has requested the DP's be udated, also build the "newSubSections" Vec
        //
        // The purpose of the above computation was for instantiating a properly-sized vector
        // at construction time.  This will save quite a bit of time that would be wasted on
        // vector resizing.

        Vector<HTMLNode> ret = new Vector<>(size);


        // By user request, only!  This really isn't *THAT* important.  All that the
        // 'newSubSections' Vector will have shall be the exact same-subsections that are passed
        // as a parameter to this method through the 'updatedReplaceables' parameter - *EXCEPT* that
        // their SubSection.location fields will be updated to hold the *ACTUAL* / *NEW* locations

        Vector<Replaceable> newReplaceables =
            updateReplaceablesAfterBuild ? new Vector<>() : null;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // MAIN-LOOP: Iterate each of the Replaceables that was passed as input to this method.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // Add their contents to Output-Vector, and make sure to add all "in-between" nodes too!

        // The index-pointer to the **ORIGINAL-VECTOR** (a.k.a. the input vector)
        int pagePos=0;


        // This loop does the replacement.  It is quick and easy if you understand what replacing
        // a list of subsections involves.

        for (Replaceable r : updatedReplaceables)
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 
            // Add all of the MOST-RECENT "In-Between Nodes"  (These are all nodes before next SS)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // AFTERWARDS: Add all nodes in the next Sub-Section 

            // Retrieve all of the 'in-between' nodes
            while (pagePos < r.originalLocationStart()) ret.add(page.elementAt(pagePos++));

            // Add this Replaceable to the returned output list!
            r.addAllInto(ret);

            // Skip over the old nodes.
            pagePos = r.originalLocationEnd(); // don't add one, value is exclusive


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 
            // User may request that the Sub-Section 'Locations' be updated, rather than discarded
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 

            // This is done for convenience so that the user knows where the sections are all
            // located in the new build.
            //
            // NOTE: All this is doing is changing the 'location' field of the old subsection
            //       which has changed to contain the new 'location'

            if (updateReplaceablesAfterBuild)
            {
                int ePos = ret.size();
                int sPos = ePos - r.currentSize() + 1;

                newReplaceables.add(r.moveAndUpdate(sPos));
            }
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // IMPORTANT: Add the last / final Elements that occur *AFTER* the *LAST* Sub-Section
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // This part should also be called "The Tail" of the Page.  (Put the Page-Tail back)

        while (pagePos < page.size()) ret.add(page.elementAt(pagePos++));


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // AGAIN: User may request that Sub-Section 'Locations' be updated, rather than discarded
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        return updateReplaceablesAfterBuild
            ? new Ret2<>(ret, newReplaceables)
            : new Ret2<>(ret, null);
    }
}