Package Torello.HTML

Class ReplaceNodes

  • public class ReplaceNodes
extends java.lang.Object
    Methods for quickly & efficiently replacing the nodes on a Web-Page.

    Generally, this class is reasonably similar to the class Attributes in that it can be used to quickly replace certain elements in a vectorized-html web-page. Here, though, rather than using the pre-defined methods from the enumerated-type enum AUM, a programmer is expected to write a java.util.function "Lambda Functional Interface." This interface has a pre-defined interface in this sub-package - interface ReplaceFunction.

    When using the AUM and Attributes class pair to update vectorized web-page elements, there is a limited subset of actions that can be performed on the nodes. The class ReplaceNodes and ReplaceFunction is much lighter and allows a programmer to change any feature about a TagNode, or any node by writing an appropriate lambda.



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 16 Method(s), 16 declared static
    • 0 Field(s)


    • Method Detail

      • r

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static Ret2<java.util.Vector<HTMLNode>,​java.util.Vector<Replaceable>> r​
            (java.util.Vector<HTMLNode> page,
             java.lang.Iterable<? extends Replaceable> updatedReplaceables,
             boolean updateReplaceablesAfterBuild)
        Updates a page Vector using a list of Replaceable 's that have been retrieved & copied from that Vector. The intention here is that if-and-when the contents of the Replaceable's currentNodes() have been modified, those updates and changes need to be reflected / propogated back into the original HTML-Vector.

        To see a use of this method from the Java Doc Upgrader Package, click on the HiLited Source-File Below. This source-code example inserts a third-table column into an HTML Table for the page Package Summary page of the package Torello.Java.Function. Adding additional Table Columns to an already existing HTML-Table is done very efficiently, even without a DOM Tree (using Vectoried-HTML instead) via the 'Peek-Inclusive' search methods and this replace-function.

        FunctionPackageSummary.java
        Parameters:
        page - Any HTML page (or sub-page), but this parameter must contain the HTML from whence the contents of the 'updatedReplaceables' iterable was created (usually by a Node Search 'Peek' methods).

        IMPORTANT NOTE: 'page' should not have been modified at all since the extraction of the SubSection and NodeIndex elements contained by updatedReplaceables. The entire purpose of a Replaceable is to modify / update / "change" the contents of the Replaceable's themselves, rather than modifying the underlying page-Vector!. Remember, because the HTML in this package is saved as a List, rather than a DOM Tree, any time an HTMLNode is inserted or deleted, the entire page will need to be shifted by that many nodes because of the upsert (insert or delete).

        NOTE: If the page has been resized in anyway, what-so-ever, the loops in this method will be replacing the wrong nodes, and the returned Vector will be entirely incorrect.

        Using a "Peek" method (which returns Replaceable instances) and changing the sub-parts of that page individually (and afterwards rebuilding the page using this method), insert and delete operations can be made an order of magnitude more efficient.
        updatedReplaceables - This should be a sorted collection of HTML Replaceable instances. Replaceable's are easily be obtained using one of the Node Search Peek methods. For instance, calling TagNodePeekL1Inclusive, and requesting all HTML <LI> elements would return a Vector<Replaceable> having all of the list <LI> items found inside of an HTML <OL> or <UL> list.

        Parameter Requirements:


        NOTE: These requirements are all mostly obeyed automatically if the Inclusive-Peek operations from the NodeSearch package were invoked to generate the Vector<Replaceable> passed to 'updatedReplaceables'. The word 'mostly' is used here because of the second requirement stating that these sections may not overlap. Peek operations may return overlapping HTML segments, when searching, for instance for multiple tag. Care should be taken when modifying HTML by looking for the relevant parts that are needed.

        AGAIN: For each Replaceable, it's Replaceable.originalLocationStart() and Replaceable.originalLocationEnd() fields will not have been changed, while the Replaceable.currentHTML() is what should have been changed (if changes are to be made to a given section). This, indeed, means that when this method is invoked, the length / size of the 'html' field will not necessarily be consistent with the length / size of its corresponding 'location' field.
        updateReplaceablesAfterBuild - When the updated sections are pieced together, and placed into the return-Vector, they will have different locations in that newly returned HTML 'page'. When TRUE is passed to this parameter, the 'updatedReplaceables' iterable-list will havve Replaceable's with stale-location fields. For class SubSection, it's location field will be stale, and for the NodeIndex classes, their index fields will no longer relfect their node's actual location in the newly constructed HTML page.

        NOTE: This should not cause any concert, unless a further round of modifications need to be made to the page.

        When TRUE is passed to this parameter, a list of newly constructed Replaceable instances will be built using the same html, and updated location values (and that list will be placed into Ret2.b). When this parameter receives FALSE, the returned Ret2.b instance' b field will be null.
        Returns:
        IMPORTANT! Unlike many of the list-modification methods in Java HTML, this is not an in-place replacement! The Vector that is returned by this method will be the updated Vector, while the Vector-parameter passed ('page') shall remain unchanged.

        NOTE: The whole basis of 'the optimization' going on here is that the Vector is only resized once! Performing an in-place substitution would result in Vector-elements constantly being shifted, and the Vector, itself, being resized.

        Ret2<Vector, Vector>:

        • Vector<HTMLNode> - Ret2.a

          The updated / modified html page. The original-input Vectorized HTML will remain unchanged!

        • Vector<Replaceable> - Ret2.b

          The Replaceable's themselves can be updated if the user has passed TRUE to parameter updateReplaceablesAfterBuild. If FALSE was passed to the parameter, then the field Ret2.b will be null.

          Note that this should seldom be necessary. If for whatever reason another round of changes will need to be made to the page, then and only then should TRUE be passed to updateReplaceablesAfterBuild.

          The update performed on the input-Replaceable's is to adjust their locations to reflect their new locations within the newly built html-page. This is done by creating new Replaceables with the same html, but different locations, and putting them in the returned Vector, which can be retrieved via Ret2.b
        Throws:
        ReplaceableOutOfBoundsException - If any of the Replaceable instances returned by the 'updatedReplaceables' iterator-parameter have original location Vector-indices that are not within the bounds of the HTML page-Vector (parameter 'page').
        ReplaceablesOverlappingException - If any of the Replaceable instances returned by the 'updatedReplaceables' iterator-parameter have original location Vector-indices that overlap.
        ReplaceablesUnsortedException - If any of the Replaceable instances returned by the 'updatedReplaceables' iterator-parameter have original-starting locations that are non-consecutive (out of order!)
        Code:
        Exact Method Body:
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // 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);

      • tableTR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Vector<HTMLNode> tableTR​
            (java.util.Vector<HTMLNode> page,
             DotPair table,
             java.util.function.ObjIntConsumer<java.util.Vector<HTMLNode>> tableRowModifier)
        Allows a user to quickly alter each row in an HTML table, iteratively, in a manner that offers a tremendous efficiency-improvement over the HTML Iterator's in the Node Seach Package.

        Significant Speed Improvements


        Whenever one modifies a Vector<HTMLNode>, if the page is very long, insert and remove operations can result in hundreds (or even thousands) of HTMLNode's being shifted. Though not noticeable in comparison to the cost incurred from an Internet web-page download, this type of operation can become very costly for pages that were merely loaded from disk, for instance.

        This method will first extract table-row (s) from the input, and then send each table-row to the table-row modifier lambda. Since HTML Pages can grow very lengthy, by first exracting each table-row from the list, and later doing the updates all at once, the time cost accrued from Vector-shifts and re-sizes is virtually eliminated.

        Exception's Thrown:
        Though not listed here, this method will throw all of the standard RuntimeException's that can be thrown by the method DotPair#exceptionCheck(Vector, String[]). Please review that method for the list of exceptions that will throw when faulty input is passed to this method. Below are listed more parameter-requirements for this method:

        • 'page' is not null.
        • 'table' is non-null, and has DotPair.start and DotPair.end indices with integer-values smaller than the size of 'page'
        • 'table' has indices which point to TagNode's in 'page' that are opening <TABLE> and closing </TABLE> tags.
        Parameters:
        page - Any HTML Page or sub-page that has a table.
        table - A pointer to the table start and end index bounds.
        tableRowModifier - A function-pointer (FunctionalInterface) that accepts the Row number (an integer), and a Row (Sub-Page Vector) and does an update to that HTML Table-Row Vector.

        The method-signature of java.util.function.ObjIntConsumer is as below. The index-parameter is provided to identify the number of the Table Row being passed for modification by your Consumer. This is a Consumer and the changes should be done on the input-Vector.

        Java Method Signature:
        void accept(Vector<HTMLNode>, int index)
        Returns:
        IMPORTANT! Unlike many of the list-modification methods in Java HTML, this is not an in-place replacement! The Vector that is returned by this method will be the updated Vector, while the Vector-parameter passed ('page') shall remain unchanged.

        NOTE: The whole basis of 'the optimization' going on here is that the Vector is only resized once! Performing an in-place substitution would result in Vector-elements constantly being shifted, and the Vector, itself, being resized.

        Ret2<Vector, Vector>:

        • Vector<HTMLNode> - Ret2.a

          The updated / modified html page. The original-input Vectorized HTML will remain unchanged!

        • Vector<Replaceable> - Ret2.b

          The Replaceable's themselves can be updated if the user has passed TRUE to parameter updateReplaceablesAfterBuild. If FALSE was passed to the parameter, then the field Ret2.b will be null.

          Note that this should seldom be necessary. If for whatever reason another round of changes will need to be made to the page, then and only then should TRUE be passed to updateReplaceablesAfterBuild.

          The update performed on the input-Replaceable's is to adjust their locations to reflect their new locations within the newly built html-page. This is done by creating new Replaceables with the same html, but different locations, and putting them in the returned Vector, which can be retrieved via Ret2.b
        See Also:
        TagNodePeekL1Inclusive, r(Vector, Iterable, boolean), DotPair.exceptionCheck(Vector, String[]), SubSection
        Code:
        Exact Method Body:
         // 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 ReplaceNodes.r(page, rows, false).a;

      • listLI

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.util.Vector<HTMLNode> listLI​
            (java.util.Vector<HTMLNode> page,
             DotPair list,
             java.util.function.ObjIntConsumer<java.util.Vector<HTMLNode>> listItemModifier)
        Allows a user to quickly alter each item in an HTML list (<OL>, <UL> or <MENU>), iteratively, in a manner that offers a tremendous efficiency-improvement over the HTML Iterator's in the Node Seach Package.

        Significant Speed Improvements


        Whenever one modifies a Vector<HTMLNode>, if the page is very long, insert and remove operations can result in hundreds (or even thousands) of HTMLNode's being shifted. Though not noticeable in comparison to the cost incurred from an Internet web-page download, this type of operation can become very costly for pages that were merely loaded from disk, for instance.

        This method will first extract list-item (s) from the input, and then send each list-item to the list-item modifier lambda. Since HTML Pages can grow very lengthy, by first exracting each list-item from the list, and later doing the updates all at once, the time cost accrued from Vector-shifts and re-sizes is virtually eliminated.

        Exception's Thrown:
        Though not listed here, this method will throw all of the standard RuntimeException's that can be thrown by the method DotPair#exceptionCheck(Vector, String[]). Please review that method for the list of exceptions that will throw when faulty input is passed to this method. Below are listed more parameter-requirements for this method:

        • 'page' is not null.
        • 'list' is non-null, and has DotPair.start and DotPair.end indices with integer-values smaller than the size of 'page'
        • 'list' has indices which point to TagNode's in 'page' that are opening-and-closing <UL>, <OL> or <MENU> tags.
        Parameters:
        page - Any HTML Page or sub-page that has an <OL>, <UL> or <MENU>.
        list - A pointer to the list start and end index bounds.
        listItemModifier - A function-pointer (FunctionalInterface) that accepts the Item number (an integer), and a Item (Sub-Page Vector) and does an update to that HTML List-Item Vector.

        The method-signature of java.util.function.ObjIntConsumer is as below. The index-parameter is provided to identify the number of the List Item being passed for modification by your Consumer. This is a Consumer and the changes should be done on the input-Vector.

        Java Method Signature:
        void accept(Vector<HTMLNode>, int index)
        Returns:
        IMPORTANT! Unlike many of the list-modification methods in Java HTML, this is not an in-place replacement! The Vector that is returned by this method will be the updated Vector, while the Vector-parameter passed ('page') shall remain unchanged.

        NOTE: The whole basis of 'the optimization' going on here is that the Vector is only resized once! Performing an in-place substitution would result in Vector-elements constantly being shifted, and the Vector, itself, being resized.

        Ret2<Vector, Vector>:

        • Vector<HTMLNode> - Ret2.a

          The updated / modified html page. The original-input Vectorized HTML will remain unchanged!

        • Vector<Replaceable> - Ret2.b

          The Replaceable's themselves can be updated if the user has passed TRUE to parameter updateReplaceablesAfterBuild. If FALSE was passed to the parameter, then the field Ret2.b will be null.

          Note that this should seldom be necessary. If for whatever reason another round of changes will need to be made to the page, then and only then should TRUE be passed to updateReplaceablesAfterBuild.

          The update performed on the input-Replaceable's is to adjust their locations to reflect their new locations within the newly built html-page. This is done by creating new Replaceables with the same html, but different locations, and putting them in the returned Vector, which can be retrieved via Ret2.b
        See Also:
        TagNodePeekL1Inclusive, r(Vector, Iterable, boolean), DotPair.exceptionCheck(Vector, String[]), SubSection
        Code:
        Exact Method Body:
         // 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 ReplaceNodes.r(page, items, false).a;

      • r

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int r​(java.util.Vector<HTMLNode> html,
                    int[] posArr,
                    ReplaceFunction rf)
        Iterates the integer-pointer values in int[] posArr, and replaces the nodes inside 'html' that have been identified by the 'posArr' list with a new node supplied by the interface ReplaceFunction. It should be obvious, that lambda expressions may be used here.

        Returning 'null':
        If the Lambda-Target / Functional-Interface ReplaceFunction (whose method is named ReplaceFunction.getReplacement(HTMLNode, int, int) actually returns 'null', then null will indeed by inserted into the corresponding Vector position.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        posArr - This is usually generated by one of the node-search 'Find.all(...)' methods. Each and every one of the 'Find.all(...)' methods in the search package will return an array of integers. These integers represent positions/locations in the passed HTML page Vector.
        rf - This is just a class that implements the interface ReplaceFunction. The interface has a single-method that will receive the position in the Vector, along with the HTMLNode found at that location. It is expected to produce a new version of the HTMLNode. This new node will be substituted into the page or sup-page.

        This function-pointer may return null, and when it does, the node located at the current loop-iteration's Vector-index will not be replaced.
        Returns:
        The number of nodes that were succesfully replaced. This number will be equal to posArr.length minus the number of times rf returned null;
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - IMPORTANT NOTE: Usually, a position-array is generated by one of the search-methods in the NodeSearch package. If, however, the Vector has since changed and posArr contains stale-data, or if for other reasons there are invalid index-pointers in posArr, then an ArrayIndexOutOfBoundsException will, naturally, be thrown by java's Vector.setElementAt(...) method.
        See Also:
        ReplaceFunction
        Code:
        Exact Method Body:
         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;

      • r

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void r​(java.util.Vector<HTMLNode> html,
                     int[] posArr,
                     HTMLNode n)
        This will replace each and every node indicated by 'posArr' with the exact same replacement node 'n'.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        posArr - This is usually generated by one of the node-search 'Find.all(...)' methods. Each and every one of the 'Find.all(...)' methods in the search package will return an array of integers. These integers represent positions/locations in the passed HTML page Vector.
        n - This may be any non-null HTMLNode. This node shall be inserted (and will replace) each node indicated by the parameter 'posArr'.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - IMPORTANT NOTE: Usually, a position-array is generated by one of the search-methods in the NodeSearch package. If, however, the Vector has since changed and posArr contains stale-data, or if for other reasons there are invalid index-pointers in posArr, then an ArrayIndexOutOfBoundsException will, naturally, be thrown by java's Vector.setElementAt(...) method.
        Code:
        Exact Method Body:
         int len= html.size();

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

      • r

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int r​(java.util.Vector<HTMLNode> html,
                    int sPos,
                    int ePos,
                    ReplaceFunction rf)
        Iterates the entire html-page, checking every node, replacing them by the values returned by 'rf' (the replace function). The ReplaceFunction (parameter 'rf') is expected to return values that either:

        • provide a replacement HTMLNode for the indicated position
        • return null as a value - in which case, no substitution will occur


        Returning 'null':
        If the Lambda-Target / Functional-Interface ReplaceFunction (whose method is named ReplaceFunction.getReplacement(HTMLNode, int, int) returns 'null', 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.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        sPos - This is the (integer) Vector-index that sets a limit for the left-most Vector-position to inspect/search inside the input Vector-parameter.

        This value is considered 'inclusive' meaning that the HTMLNode at this Vector-index will be visited by this method.

        NOTE: If this value is negative, or larger than the length of the input-Vector, an exception will be thrown.
        ePos - This is the (integer) Vector-index that sets a limit for the right-most Vector-position to inspect/search inside the input Vector-parameter.

        This value is considered 'exclusive' meaning that the 'HTMLNode' at this Vector-index will not be visited by this method.

        NOTE: If this value is larger than the size of input the Vector-parameter, an exception will throw.

        ALSO: Passing a negative value to this parameter, 'ePos', will cause its value to be reset to the size of the input Vector-parameter.
        rf - This is just a class that implements the interface ReplaceFunction. The interface has a single-method (@code getReplacement(...)} that will receive the position in the Vector, along with the HTMLNode found at that location. It is expected to return a new version of the HTMLNode.

        This function-pointer may return null, and when it does, the node located at the current loop-iteration's Vector-index will not be replaced.
        Returns:
        The number of nodes that were succesfully replaced. This number will be equal to html.size() minus the number of times rf returned null;
        Throws:
        java.lang.IndexOutOfBoundsException - This exception shall be thrown if any of the following are true:

        • If 'sPos' is negative, or if sPos is greater-than-or-equal-to the size of the Vector
        • If 'ePos' is zero, or greater than the size of the Vector
        • If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Vector.size(), before this check is done.
        See Also:
        ReplaceFunction, HTMLNode
        Code:
        Exact Method Body:
         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;

      • r

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void r​(java.util.Vector<HTMLNode> html,
                     int[] posArr,
                     java.util.Vector<HTMLNode> newNodes)
        Iterates the integer-pointer values listed by 'posArr', and replaces every position in 'html' with an HTMLNode from the nodes provided by the 'newNodes' parameter.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        posArr - This is usually generated by one of the node-search 'Find.all(...)' methods. Each and every one of the 'Find.all(...)' methods in the search package will return an int[] array. These integers represent positions/locations in the passed HTML page Vector.
        newNodes - This list of new nodes must have a length identical to the int[] posArr (pointer-Array) length.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - This exception will throw if any of the elements of 'posArr' point to a position in the Vector<HTMLNode> v parameter that are out of bounds for that Vector.
        java.lang.IllegalArgumentException - if the length of the position array (pointer-array) is not identical to the length of the new-nodes Vector.
        Code:
        Exact Method Body:
         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);

      • r

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int r​(java.util.Vector<HTMLNode> html,
                    int sPos,
                    int ePos,
                    java.util.Vector<HTMLNode> newNodes)
        Replaces the nodes currently within the vectorized HTML parameter 'html', in the sub-range provided by the 'sPos' and 'ePos' parameters - using the new nodes provided by Vector-Parameter 'newNodes'. This is, essentially, a sub-range array-replacement operation.

        Unless exactly the same number of nodes that are in the 'replaceRange' are also in 'newNodes', this method shall have to shorten or lengthen the size of the HTML Vector.
        Parameters:
        html - This may be any HTML page or sub-page
        sPos - This is the (integer) Vector-index that sets a limit for the left-most Vector-position to inspect/search inside the input Vector-parameter.

        This value is considered 'inclusive' meaning that the HTMLNode at this Vector-index will be visited by this method.

        NOTE: If this value is negative, or larger than the length of the input-Vector, an exception will be thrown.
        ePos - This is the (integer) Vector-index that sets a limit for the right-most Vector-position to inspect/search inside the input Vector-parameter.

        This value is considered 'exclusive' meaning that the 'HTMLNode' at this Vector-index will not be visited by this method.

        NOTE: If this value is larger than the size of input the Vector-parameter, an exception will throw.

        ALSO: Passing a negative value to this parameter, 'ePos', will cause its value to be reset to the size of the input Vector-parameter.
        newNodes - These are the new HTMLNode's that are to replace the old ones.
        Returns:
        The change in the size (size-delta) of the input html parameter.
        Throws:
        java.lang.IndexOutOfBoundsException - This exception shall be thrown if any of the following are true:

        • If 'sPos' is negative, or if sPos is greater-than-or-equal-to the size of the Vector
        • If 'ePos' is zero, or greater than the size of the Vector
        • If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Vector.size(), before this check is done.
        Code:
        Exact Method Body:
         // 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)

      • r

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int r​(java.util.Vector<HTMLNode> html,
                    int sPos,
                    int ePos,
                    HTMLNode newNode)
        Replaces the nodes currently within the vectorized HTML parameter 'html', in the sub-range provided by the 'sPos' and 'ePos' parameters, with a single new node provided by 'newNode'. Essentially, this is a Range Removal Operation, because a complete sublist is removed, and only a single-node replaces it.

        Unless the replacement-range (defined by 'sPos' and 'ePos') has a size equal to '1', this operation will (obviously) shorten the size of the input HTML Vector by size - 1 nodes.
        Parameters:
        html - This may be any HTML page or sub-page
        sPos - This is the (integer) Vector-index that sets a limit for the left-most Vector-position to inspect/search inside the input Vector-parameter.

        This value is considered 'inclusive' meaning that the HTMLNode at this Vector-index will be visited by this method.

        NOTE: If this value is negative, or larger than the length of the input-Vector, an exception will be thrown.
        ePos - This is the (integer) Vector-index that sets a limit for the right-most Vector-position to inspect/search inside the input Vector-parameter.

        This value is considered 'exclusive' meaning that the 'HTMLNode' at this Vector-index will not be visited by this method.

        NOTE: If this value is larger than the size of input the Vector-parameter, an exception will throw.

        ALSO: Passing a negative value to this parameter, 'ePos', will cause its value to be reset to the size of the input Vector-parameter.
        newNode - This is the new HTMLNode that is to replace the (entire) list specified by parameters 'sPos' and 'ePos'.
        Returns:
        The change in the size (size-delta) of the input html parameter. The number returned will always equal 1 - (ePos - sPos). This means the return value for this method will always be negative (i.e. the Vector shrunk) - unless sPos and ePos had specified a range that was equal to 1.
        Throws:
        java.lang.IndexOutOfBoundsException - This exception shall be thrown if any of the following are true:

        • If 'sPos' is negative, or if sPos is greater-than-or-equal-to the size of the Vector
        • If 'ePos' is zero, or greater than the size of the Vector
        • If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Vector.size(), before this check is done.
        Code:
        Exact Method Body:
         // 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)

      • r

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static int r​(java.util.Vector<HTMLNode> html,
                    int replacePos,
                    java.util.Vector<HTMLNode> newNodes)
        Replaces the instance of HTMLNode located at Vector-index 'pos' with the contents of Vector parameter 'newNodes'. This removes just a single instance of HTMLNode, and replaces it with a list of nodes.

        Note that this method will, indeed, lengthen the size of the input HTML Vector (unless the 'newNodes' Vector being inserted has only 1 or 0 elements).
        Parameters:
        html - This may be any HTML page or sub-page.
        replacePos - The position of the HTMLNode to be removed and replaced with the list of nodes.
        newNodes - These are the new HTMLNode's that are to replace the old instance of HTMLNode at position 'pos'.
        Returns:
        The change in the size (size-delta) of the input html parameter. The number returned will always equal newNodes.size() - 1
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - This exception will throw if the specified 'pos' parameter is not within the bounds of the Vector.
        Code:
        Exact Method Body:
         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)