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
    • 14 Method(s), 14 declared static
    • 0 Field(s)


    • Method Detail

      • 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 that is performed on the input-Replaceable's is done 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 retrieve via Ret2.b
        See Also:
        TagNodePeekL1Inclusive, Replacement.run(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 Replacement.run(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 that is performed on the input-Replaceable's is done 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 retrieve via Ret2.b
        See Also:
        TagNodePeekL1Inclusive, Replacement.run(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 Replacement.run(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)