Class AbstractHNLI<E extends HTMLNode,​F>

  • Type Parameters:
    E - This must be either TagNode, TextNode or CommentNode. This is type of the query-specifier Predicate being used.
    F - This is the actual-type that will be iterated. For instances of HNLI, both type-parameters 'E' and 'F' are identical. The Predicate's will be querrying for a certain type of HTMLNode, and the Iterator will be iterating that type of HTMLNode too.

    However, for instances of HNLIInclusive, the query-specifier is (automatically-required) to be set to TagNode, and the Iterator shall be returning instances of Vector<HTMLNode>. Generic Type-Parameter 'F' is automatically set to Vector<HTMLNode> for instances of HNLIInclusive.
    All Implemented Interfaces:
    java.util.Iterator<F>, java.util.ListIterator<F>
    Direct Known Subclasses:
    HNLI, HNLIInclusive
    public abstract class AbstractHNLI<E extends HTMLNode,​F>
extends java.lang.Object
implements java.util.ListIterator<F>
    Abstract HTMLNode-ListIterator:
    This class is the parent of the following two classes:


    Methods that are common to both of these classes have been placed in this abstract super-class.
    Abstract parent-class for both of the types of HTML-Iterator's

    This is an abstract super-class for the HTML Node List Iterator classes. Having an abstract parent-class allows to collect some of the common features of both sub-classes into a single parent.


    • Field Detail

      • v

        🡇  ⇈  ⮫ 
        protected java.util.Vector v
        The internal, underlying instance of Vector that this Iterator is using.
        Code:
        Exact Field Declaration Expression:
         @SuppressWarnings("rawtypes")
     protected Vector v;

      • p

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<E extends HTMLNode> p
        This Predicate is the test for identifying Iterator node-matches
        Code:
        Exact Field Declaration Expression:
         protected Predicate<E> p;

      • c

        🡅  🡇  ⇈  ⮫ 
        protected java.lang.Class<E extends HTMLNode> c
        This is the type of HTMLNode being iterated
        Code:
        Exact Field Declaration Expression:
         protected Class<E> c;

      • cursor

        🡅  🡇  ⇈  ⮫ 
        protected int cursor
        Internal 'cursor' field.
        It is initialized to -1, which allows the iterator to identify whether it has been used yet.
        Code:
        Exact Field Declaration Expression:
         protected int cursor = -1;

      • modifiedSince

        🡅  🡇  ⇈  ⮫ 
        protected boolean modifiedSince
        This identifies whether one of the Iterator's html modification methods (set, remove, add) have been invoked. Multiple invocations of these methods after a single iteration causes a SecondModificationException

        Initializing this to TRUE prevents the programmer from calling any of the modification methods without first finding a match.
        Code:
        Exact Field Declaration Expression:
         protected boolean modifiedSince = true;

      • expectedSize

        🡅  🡇  ⇈  ⮫ 
        protected int expectedSize
        This is an attempt to monitor outside modifications to an HTML Vector
        Code:
        Exact Field Declaration Expression:
         protected int expectedSize;

    • Constructor Detail

      • AbstractHNLI

        🡅  🡇  ⇈  ⮫ 
        protected AbstractHNLI​(java.util.Vector<?> html,
                       java.util.function.Predicate<E> p,
                       java.lang.Class<E> c)
        Constructs an instance of this class using an HTML Vector, and a Predicate for testing the nodes in that Vector for matches. The third parameter 'c' is only necessary because of Java's type-erasure problem.
        Parameters:
        html - Any vectorized HTML page or sub-page.
        p - A java.util.function.Predicate for testing the nodes in the html Vector for matches.
        c - The sub-class of HTMLNode that this HNLI shall be searching. The values for parameter 'c' include: TagNode.class, TextNode, and CommentNode.class

    • Method Detail

      • MODIFIED

        🡅  🡇  ⇈  ⮫ 
        protected final void MODIFIED()
        Code:
        Exact Method Body:
         modifiedSince   = true;
 expectedSize    = v.size();

 RESET_MATCHES();

      • remove

        🡅  🡇  ⇈  ⮫ 
        public void remove()
        This removes the last match that was returned by the Iterator out of the underlying Vector.
        Specified by:
        remove in interface java.util.Iterator<E extends HTMLNode>
        Specified by:
        remove in interface java.util.ListIterator<E extends HTMLNode>
        Throws:
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        See Also:
        CHECK_EXCEPTIONS(), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS();

 int numRemoved = REMOVE();

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

 MODIFIED();

      • moveCursorToStart

        🡅  🡇  ⇈  ⮫ 
        public void moveCursorToStart()
        Convenience Method
        Invokes: moveCursor(int)
        Uses minimum cursor-bound for parameter 'location', which would be zero, unless a cursor-window has been set.
        Code:
        Exact Method Body:
         moveCursor((minCursor == -1) ? 0 : minCursor);

      • moveCursorToEnd

        🡅  🡇  ⇈  ⮫ 
        public void moveCursorToEnd()
        Convenience Method
        Invokes: moveCursor(int)
        Uses minimum cursor-bound for parameter 'location', which would be v.size() - 1, unless a cursor-window has been set.
        Code:
        Exact Method Body:
         moveCursor((maxCursor == -1) ? (v.size() - 1) : maxCursor);

      • moveCursor

        🡅  🡇  ⇈  ⮫ 
        public void moveCursor​(int location)
        Sets the internal state of this Iterator's cursor location. The next invocation of next, previous, etc... will return the nearest match to this Vector-index.

        Cursor Reset Method:
        This method is (somewhat / sort-of) of a Reset-Method - because the internal-cursor is moved to the beginning of the underlying-Vector. Whenever the cursor is moved (or restricted), this class' code will check for the possibility of a ConcurrentModificationException.

        In normal situations, when statements or method's from outside the update methods in this class, modify the underlying html-Vector a ConcurrentModificationException shall throw. However, whenever an HTML Node List Iterator method moves the cursor, the logic for checking Concurrent-Modification will reset (by setting the internal 'expectedSize' field to v.size()).

        This 'resetting' of the internal 'expectedSize' field is precisely how to prevent an exception throw due to outside modification of the underlying Vector.
        Parameters:
        location - Any index into the underlying HTML Vector
        Throws:
        java.lang.IndexOutOfBoundsException - This shall throw if the value passed to parameter 'location' is negative, or past the end of the underlying html Vector.
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        Code:
        Exact Method Body:
         if (location < 0) throw new IndexOutOfBoundsException
     ("You have passed a negative value to the cursor location: [" + location + "].");

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

 CursorException.check(minCursor, maxCursor, location);

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

 RESET_MATCHES();

      • restrictCursor

        🡅  🡇  ⇈  ⮫ 
        public void restrictCursor​(int minCursorBounds,
                           int maxCursorBounds)
        Restrict the internal cursor boundaries to a window defined by the parameters 'maxCursorBounds', and 'minCursorBounds'. When the cursor bounds are restricted, any matches that would be returned by this Iterator which lay outside the boundaries of this window shall be skipped or avoided.

        If the cursor is currently located outside the boundaries of the given window, it shall be moved to within it.

        Cursor Reset Method:
        This method is (somewhat / sort-of) of a Reset-Method - because the internal-cursor is moved to the beginning of the underlying-Vector. Whenever the cursor is moved (or restricted), this class' code will check for the possibility of a ConcurrentModificationException.

        In normal situations, when statements or method's from outside the update methods in this class, modify the underlying html-Vector a ConcurrentModificationException shall throw. However, whenever an HTML Node List Iterator method moves the cursor, the logic for checking Concurrent-Modification will reset (by setting the internal 'expectedSize' field to v.size()).

        This 'resetting' of the internal 'expectedSize' field is precisely how to prevent an exception throw due to outside modification of the underlying Vector.
        Parameters:
        minCursorBounds - This shall set a minimum cursor-index value that restricts the returned matches generated by this HTML Node List Iterator to indices less than minCursorBounds. This is an inclusive bound. Matches falling directly on this index may be included in a result set.
        maxCursorBounds - This shall set a maximum cursor-index value that restricts the returned matches generated by this HTML Node List Iterator to indices greater than maxCursorBounds. This is *also* an inclusive bound. Matches falling directly on this index may be included in a result set.
        Throws:
        java.lang.IndexOutOfBoundsException - If the bounds provided by the 'cursorBounds' input parameter extend past the end of the current underlying Vector, then this exception shall throw.
        Code:
        Exact Method Body:
         if (minCursorBounds < 0) throw new IndexOutOfBoundsException
     ("The value for parameter 'minPos' [" + minCursorBounds + "] cannot be negative");

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

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

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

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

      • clearCursorBounds

        🡅  🡇  ⇈  ⮫ 
        public void clearCursorBounds()
        Eliminates the Cursor Boundary Window, if one had been set.
        Code:
        Exact Method Body:
         this.maxCursor = this.minCursor = -1;

      • cursorLocation

        🡅  🡇  ⇈  ⮫ 
        public int cursorLocation()
        Retrieves the current location of the cursor.
        Returns:
        The current location of 'this' Iterator's cursor. If hasNext() or hasPrevious() has just been called, for example, the cursor will be pointing to the next (or previous) node-match in the HTML Vector.
        Code:
        Exact Method Body:
         return cursor;

      • addHTMLNode

        🡅  🡇  ⇈  ⮫ 
        public void addHTMLNode​(HTMLNode n)
        This provides a way to insert an HTML node into the HTML-Vector. The node is at the current cursor-index. The cursor should be pointing to the location of the last returned match.
        Parameters:
        n - This may be any descendant of the class HTMLNode. There is an issue to think about when working with Java's Generics and Compile-Time versus Run-Time types in java: vis-a-vis Type-Erasure. It is important to bear in mind that when creating an instance of class HNLI or HNLIInclusive (which are extend interface Iterator<E> - a generic-type), the underlying Vector over which the Iterator is 'iterating' could be a Vector of a sub-class (inherited class) of the top-level class HTMLNode. Specifically this could be an Iterator that is traversing: Vector<HTMLNode>, Vector<TagNode>, Vector<CommentNode>, etc...

        If an Iterator is created for a Vector<TagNode> (which are returned by many of the search operations), and an one inserts an instance of class CommentNode, Java Will Allow You To Do This ! (Specifically, 'ClassCastException' will not be thrown). This is the consequence of Run-Time Type Erasure. There is not necessarily a problem with this, and all it means is that at Run-Time - all Vector's are effectively instances of Vector<Object>. Be aware when inserting nodes into Vector's about the pitfalls.
        Throws:
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        See Also:
        CHECK_EXCEPTIONS(), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS();

 v.add(cursor, n);

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

 cursor++;

 MODIFIED();

      • add

        🡅  🡇  ⇈  ⮫ 
        public void add​(java.lang.String html)
        This provides a way to insert String-represented HTML. The HTML will placed in the underlying HTML-Vector directly before the current cursor-index. The cursor is situated at the location of the last match returned by the Iterator.

        This method will perform a parse of HTML that has been represented as a String, and convert it to a Vectorized-HTML partial-page. This partial page is then inserted into the underlying Vector using a method of the same name.

        IMMUTABILITY NOTE: The HTML Element "Data-Classes" in this HTML Scrape Package are all 100% immutable - meaning that if one wants to change a node, a new instance must be instantiated, instead. This concept is rooted in class java.lang.String. Studying java, one learns (slowly) that String's are always immutable. One outcome of this implementation, is that "reusing" instances of class HTMLNode, (and the inheriting classes TagNode, TextNode and CommentNode) is made very easy. If multiple web-pages have a copy of an HTML divider ('DIV') element, there is no chance at all that one the node will be changed in one sublist, and make another web-page invalid.

        How does this affect this method? Primarily, this method - if reused over and over in a loop - would be extremely inefficient. Since all the nodes being inserted are, by definition, un-changing - the same copy of a Vector of html could be re-inserted over and over again into different pages without any worry that the HTML would be changed in one sub-section and disastrously affect another part of the web-page. If multiple insertions of the same HTML are being performed, it is highly recommended to first parse & instantiate a vectorized-html subsection first, instead of using this method repeatedly. This method performs an instantiation of new HTML-Nodes each and every time it is invoked. In the case where the same HTML Nodes are going to be inserted many times, avoiding this method, and rather, relying on the other-version of this method that inserts sublists of 'already-parsed' and 'already-instantiated' vectorized HTML sub-sections would be smarter, as less memory would be allocated.
        Parameters:
        html - This is any valid, parse-able HTML section represented as a java.lang.String. The String will be converted to vectorized-html before insertion.
        Throws:
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        See Also:
        HTMLPage.getPageTokens(CharSequence, boolean)
        Code:
        Exact Method Body:
         add(HTMLPage.getPageTokens(html, false));

      • add

        🡅  🡇  ⇈  ⮫ 
        public void add​(java.util.Vector<HTMLNode> html)
        Adds vectorized-HTML at the current cursor position.
        Parameters:
        html - This may be any vectorized HTML page or sub-page. It will be inserted at the the location of the last returned match.
        Throws:
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        See Also:
        CHECK_EXCEPTIONS(), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS();

 v.addAll(cursor, html);

 cursor += html.size();

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

      • setHTMLNode

        🡅  🡇  ⇈  ⮫ 
        public void setHTMLNode​(HTMLNode n)
        This provides a way to replace the previous match with an instance of HTMLNode. The match that is replaced is the one that was last returned from a call to any of: next(), previous(), nextIndex(), previousIndex(), etc...
        Parameters:
        n - This may be any descendant of the class HTMLNode. There is an issue to think about when working with Java's Generics and Compile-Time versus Run-Time types in java: vis-a-vis Type-Erasure. It is important to bear in mind that when creating an instance of class HNLI or HNLIInclusive (which are extend interface Iterator<E> - a generic-type), the underlying Vector over which the Iterator is 'iterating' could be a Vector of a sub-class (inherited class) of the top-level class HTMLNode. Specifically this could be an Iterator that is traversing: Vector<HTMLNode>, Vector<TagNode>, Vector<CommentNode>, etc...

        If an Iterator is created for a Vector<TagNode> (which are returned by many of the search operations), and an one inserts an instance of class CommentNode, Java Will Allow You To Do This ! (Specifically, 'ClassCastException' will not be thrown). This is the consequence of Run-Time Type Erasure. There is not necessarily a problem with this, and all it means is that at Run-Time - all Vector's are effectively instances of Vector<Object>. Be aware when inserting nodes into Vector's about the pitfalls.
        Throws:
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        See Also:
        remove(), cursor, expectedSize, maxCursor
        Code:
        Exact Method Body:
         remove();

 v.add(cursor, n);

 cursor++;

 expectedSize++;

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

      • set

        🡅  🡇  ⇈  ⮫ 
        public void set​(java.lang.String html)
        Convenience Method
        Invokes: (Parses HTML) HTMLPage.getPageTokens(CharSequence, boolean)
        And-Then: set(Vector)

        This method will perform a parse of HTML that has been represented as a String, and convert it to a Vectorized-HTML partial-page. This partial page is then inserted into the underlying Vector using a method of the same name.

        IMMUTABILITY NOTE: The HTML Element "Data-Classes" in this HTML Scrape Package are all 100% immutable - meaning that if one wants to change a node, a new instance must be instantiated, instead. This concept is rooted in class java.lang.String. Studying java, one learns (slowly) that String's are always immutable. One outcome of this implementation, is that "reusing" instances of class HTMLNode, (and the inheriting classes TagNode, TextNode and CommentNode) is made very easy. If multiple web-pages have a copy of an HTML divider ('DIV') element, there is no chance at all that one the node will be changed in one sublist, and make another web-page invalid.

        How does this affect this method? Primarily, this method - if reused over and over in a loop - would be extremely inefficient. Since all the nodes being inserted are, by definition, un-changing - the same copy of a Vector of html could be re-inserted over and over again into different pages without any worry that the HTML would be changed in one sub-section and disastrously affect another part of the web-page. If multiple insertions of the same HTML are being performed, it is highly recommended to first parse & instantiate a vectorized-html subsection first, instead of using this method repeatedly. This method performs an instantiation of new HTML-Nodes each and every time it is invoked. In the case where the same HTML Nodes are going to be inserted many times, avoiding this method, and rather, relying on the other-version of this method that inserts sublists of 'already-parsed' and 'already-instantiated' vectorized HTML sub-sections would be smarter, as less memory would be allocated.
        Parameters:
        html - This is any valid, parse-able HTML section as a java.lang.String. The String will be converted to vectorized-html before insertion.
        Code:
        Exact Method Body:
         set(HTMLPage.getPageTokens(html, false));

      • set

        🡅  🡇  ⇈  ⮫ 
        public void set​(java.util.Vector<HTMLNode> html)
        Replaces the last returned match with the contents of parameter 'html'.
        Parameters:
        html - This may be any-sized html page, or sub-page.
        Throws:
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        See Also:
        Util.removeRange(Vector, DotPair), remove(), cursor, expectedSize, maxCursor
        Code:
        Exact Method Body:
         remove();

 v.addAll(cursor, html);

 cursor += html.size();

 expectedSize += html.size();

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

      • insertAt

        🡅  🡇  ⇈  ⮫ 
        public void insertAt​(HTMLNode n,
                     int pos)
        Inserts parameter HTMLNode n into the underlying vectorized-html at Vector-index 'pos'.
        Parameters:
        n - This may be any descendant of the class HTMLNode. There is an issue to think about when working with Java's Generics and Compile-Time versus Run-Time types in java: vis-a-vis Type-Erasure. It is important to bear in mind that when creating an instance of class HNLI or HNLIInclusive (which are extend interface Iterator<E> - a generic-type), the underlying Vector over which the Iterator is 'iterating' could be a Vector of a sub-class (inherited class) of the top-level class HTMLNode. Specifically this could be an Iterator that is traversing: Vector<HTMLNode>, Vector<TagNode>, Vector<CommentNode>, etc...

        If an Iterator is created for a Vector<TagNode> (which are returned by many of the search operations), and an one inserts an instance of class CommentNode, Java Will Allow You To Do This ! (Specifically, 'ClassCastException' will not be thrown). This is the consequence of Run-Time Type Erasure. There is not necessarily a problem with this, and all it means is that at Run-Time - all Vector's are effectively instances of Vector<Object>. Be aware when inserting nodes into Vector's about the pitfalls.
        pos - This is the location in the underlying Vector being iterated where the passed parameter 'n' shall be inserted.
        Throws:
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        See Also:
        CHECK_EXCEPTIONS(int), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS(pos);

 v.add(pos, n);

 if (pos < cursor) cursor++;

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

 MODIFIED();

      • insertAt

        🡅  🡇  ⇈  ⮫ 
        public void insertAt​(java.lang.String html,
                     int pos)
        Convenience Method
        Invokes: (Parses HTML) HTMLPage.getPageTokens(CharSequence, boolean)
        And-Then: insertAt(Vector, int).

        This method will perform a parse of HTML that has been represented as a String, and convert it to a Vectorized-HTML partial-page. This partial page is then inserted into the underlying Vector using a method of the same name.

        IMMUTABILITY NOTE: The HTML Element "Data-Classes" in this HTML Scrape Package are all 100% immutable - meaning that if one wants to change a node, a new instance must be instantiated, instead. This concept is rooted in class java.lang.String. Studying java, one learns (slowly) that String's are always immutable. One outcome of this implementation, is that "reusing" instances of class HTMLNode, (and the inheriting classes TagNode, TextNode and CommentNode) is made very easy. If multiple web-pages have a copy of an HTML divider ('DIV') element, there is no chance at all that one the node will be changed in one sublist, and make another web-page invalid.

        How does this affect this method? Primarily, this method - if reused over and over in a loop - would be extremely inefficient. Since all the nodes being inserted are, by definition, un-changing - the same copy of a Vector of html could be re-inserted over and over again into different pages without any worry that the HTML would be changed in one sub-section and disastrously affect another part of the web-page. If multiple insertions of the same HTML are being performed, it is highly recommended to first parse & instantiate a vectorized-html subsection first, instead of using this method repeatedly. This method performs an instantiation of new HTML-Nodes each and every time it is invoked. In the case where the same HTML Nodes are going to be inserted many times, avoiding this method, and rather, relying on the other-version of this method that inserts sublists of 'already-parsed' and 'already-instantiated' vectorized HTML sub-sections would be smarter, as less memory would be allocated.
        Parameters:
        html - This is any valid, parse-able HTML section as a java.lang.String. The String will be converted to vectorized-html before insertion.
        Code:
        Exact Method Body:
         insertAt(HTMLPage.getPageTokens(html, false), pos);

      • insertAt

        🡅  🡇  ⇈  ⮫ 
        public void insertAt​(java.util.Vector<? extends HTMLNode> html,
                     int pos)
        Insert the contents of vectorized-html parameter 'html' into the underlying html Vector, beginning at position 'pos'.
        Parameters:
        html - This may be any HTML page or sub-page.
        pos - This is the location in the underlying Vector being iterated where the passed parameter 'html' shall be inserted.
        Throws:
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        See Also:
        CHECK_EXCEPTIONS(int), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS(pos);

 v.addAll(pos, html);

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

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

 MODIFIED();

      • replaceRange

        🡅  🡇  ⇈  ⮫ 
        public void replaceRange​(int sPos,
                         int ePos,
                         java.util.Vector<HTMLNode> newNodes)
        Convenience Method
        Invokes: replaceRange(DotPair, Vector)
        NOTE: ePos is decremented by 1, since DotPair.end is always an inclusive value, while ePos is always exclusive.
        Code:
        Exact Method Body:
         replaceRange(new DotPair(sPos, ePos - 1), newNodes);

      • replaceRange

        🡅  🡇  ⇈  ⮫ 
        public void replaceRange​(DotPair range,
                         java.util.Vector<HTMLNode> newNodes)
        This replaces a specified sub-range of nodes in the underlying vectorized-html with the nodes in 'newNodes'.
        Parameters:
        range - This is the sub-range or "sub-section" of the underlying vectorized-html page that is going to be replaced by the 'newNodes'.
        newNodes - These are the nodes to be inserted into the location where the old range is.
        Throws:
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        See Also:
        Util.removeRange(Vector, DotPair), DotPair.isInside(int), DotPair.size(), CHECK_EXCEPTIONS(DotPair), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS(range);

 Util.replaceRange(v, range, newNodes);

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

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

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

      • removeElementAt

        🡅  🡇  ⇈  ⮫ 
        public void removeElementAt​(int pos)
        This removes the node at a specified index in the underlying vectorized-html.
        Parameters:
        pos - This is the index into the underlying vectorized-html page to be removed.
        Throws:
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        See Also:
        CHECK_EXCEPTIONS(int), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS(pos);

 v.removeElementAt(pos);

 if (pos < cursor) cursor--;

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

 MODIFIED();

      • removeRange

        🡅  🡇  ⇈  ⮫ 
        public void removeRange​(int sPos,
                        int ePos)
        Convenience Method
        Invokes: removeRange(int, int)
        NOTE: ePos is decremented by 1, since DotPair.end is always an inclusive value while ePos is always exclusive.
        Code:
        Exact Method Body:
         removeRange(new DotPair(sPos, ePos-1));

      • removeRange

        🡅  🡇  ⇈  ⮫ 
        public void removeRange​(DotPair range)
        This removes a specified sub-range of nodes in the underlying vectorized-html.
        Parameters:
        range - This is the sub-range or "sub-section" of the underlying vectorized-html page;
        Throws:
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        See Also:
        Util.removeRange(Vector, DotPair), DotPair.isInside(int), DotPair.size(), CHECK_EXCEPTIONS(DotPair), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS(range);

 Util.removeRange(v, range);

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

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

      • removeElements

        🡅  🡇  ⇈  ⮫ 
        public void removeElements​(int... posArr)
        This will remove every Vector-element that is identified by the 'posArr' Vector-position int[] array.
        Parameters:
        posArr - This is a list of nodes that shall be removed from the underlying html-Vector.
        Throws:
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        See Also:
        Util.removeNodes(boolean, Vector, int[]), CHECK_EXCEPTIONS(int[]), MODIFIED()
        Code:
        Exact Method Body:
         CHECK_EXCEPTIONS(posArr);

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

 int ORIGINAL_CURSOR = cursor;

 for (int pos : posArr)

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

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

 MODIFIED();

      • CHECK_EXCEPTIONS

        🡅  🡇  ⇈  ⮫ 
        protected void CHECK_EXCEPTIONS​(int pos)
        Checks the input position 'pos' parameter to verify it is not out of the bounds of the underlying HTML-Vector, nor out of the bounds of the Cursor Boundary Window - if one has been set.

        This shall throw exceptions if the passed 'range' is out of either of these bounds.

        Upon completion of this test, the rest of the standard Exception check-throws are performed.
        Throws:
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        See Also:
        CHECK_EXCEPTIONS()
        Code:
        Exact Method Body:
         IteratorOutOfBoundsException.check(v, pos);
 CursorException.check(minCursor, maxCursor, pos);

 CHECK_EXCEPTIONS();

      • CHECK_EXCEPTIONS

        🡅  🡇  ⇈  ⮫ 
        protected void CHECK_EXCEPTIONS​(DotPair range)
        Checks the input position 'range' parameter to verify the provided range values are not out of the bounds of the underlying HTML-Vector, nor out of the bounds of the Cursor Boundary Window - if one has been set.

        This shall throw exceptions if the passed 'range' is out of either of these bounds.

        Upon completion of this test, the rest of the standard Exception check-throws are performed.
        Throws:
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        See Also:
        CHECK_EXCEPTIONS()
        Code:
        Exact Method Body:
         IteratorOutOfBoundsException.check(v, range);
 CursorException.check(minCursor, maxCursor, range);

 CHECK_EXCEPTIONS();

      • CHECK_EXCEPTIONS

        🡅  🡇  ⇈  ⮫ 
        protected void CHECK_EXCEPTIONS​(int[] posArr)
        Checks the input position-array 'posArr' parameter to verify that none of the indices listed in this position-array are out of the bounds of the underlying HTML-Vector, nor out of the bounds of the Cursor Boundary Window - if one has been set.

        This shall throw exceptions if the indices in this input array extend past either of these boundaries.

        Upon completion of this test, the rest of the standard Exception check-throws are performed.
        Throws:
        IteratorOutOfBoundsException - This exception will be thrown if any of the insert or remove methods are invoked with any value for the int pos parameter (or values in the int[] posArr parameter) that are negative, or past the end of the underlying vectorized-html.
        CursorException - Whenever a method attempts to modify the underlying HTML Vector, the location where the modification is occurring shall be checked against the Cursor Boundary Window. It is not mandatory that an HTML Node List Iterator have a Boundary Window set for the cursor, and by default, no such window is created. If, however, one was created, the modification Vector index or indices shall be checked against the values set for minCursor and maxCursor - and if the location does not fall within the window's bounds, (if the window exists) a CursorException shall throw.
        See Also:
        CHECK_EXCEPTIONS()
        Code:
        Exact Method Body:
         IteratorOutOfBoundsException.check(v, posArr);
 CursorException.check(minCursor, maxCursor, posArr);

 CHECK_EXCEPTIONS();

      • CHECK_EXCEPTIONS

        🡅  🡇  ⇈  ⮫ 
        protected void CHECK_EXCEPTIONS()
        Does a check regarding whether any exceptions should throw.
        Throws:
        java.util.ConcurrentModificationException - Internal to this Iterator's state is a private int-field named 'expectedSize' that is consistently maintained to know the current size of the underlying HTML-Vector. Whenever modifications are made to that HTML with this class' Add, Set & Remove methods - this class code will also, simultaenously, update the 'expectedSize' field.

        If changes to the HTML-Vector are made outside of this class' Add, Set, Remove or Update interface-methods, then the value of this internal integer-field ('expectedSize') will stop being consistent with the actual size of the HTML-Vector.

        When the size of the internal HTML-Vector does not equal the value stored inside field 'expectedSize', this class' code will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the Vector's size simply won't be detected. This is (somewhat) due to 'a bug' in the JDK implementation of AbstractList where the integer-field named 'modCount' is assigned 'protected' visibility, rendering it somewhat useless.

        RESET NOTE: Any call made to a variant of the provided first(...) or last(...) methods will force a reset of this the internal integer-field 'expected-size' (to the Vector's actual size). When this field is reset, it will actually prevent the ConcurrentModificationException from throwing - even if code from outside this class has changed the size of the HTML-Vector - because it becomes impossible to detect that change.
        java.lang.IllegalStateException - This exception will also throw if the Iterator has just been constructed, and no calls to next, previous, first or last have been made (or any of their variants). This is necessary because until a value has been returned by the Iterator, the internal cursor has not been set to a valid match-value, and thusly modifying a value near the cursor-index would have non-deterministic results.
        SecondModificationException - This exception will throw if successive, multiple invocations are made to any of the Iterator method variants for add(...), set(...), or remove(...) without an inter-leaved, or intervening call being made to the standard getter methods next(), nextDotPair(), previous(), previousDotPair, first() or last(), etc...

        IMPORTANT NOTE: Both HNLI Iterators shall not permit successive calls to the add, set, or remove operations after a call to next, previous, first or last. Operations that modify the underlying Vector may only be invoked once per retrieval operation. That means after any retrieval operation such as: next(), previous(), first(), etc... The iteration-match can be changed, appended, etc. - but this may only occur once per match. After the first change, the user is expected to move on to the next iteration-match before making a second attempt to modify the underlying vectorized-html.
        See Also:
        CHECK_CME()
        Code:
        Exact Method Body:
         CHECK_CME();

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

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

      • CHECK_CME

        🡅  ⇈  ⮫ 
        protected void CHECK_CME()
        Does a check regarding whether an exception should throw.
        Throws:
        java.util.ConcurrentModificationException - Checks for, and throws if necessary, Java's ConcurrentModificationException.
        Code:
        Exact Method Body:
         if (expectedSize != v.size()) throw new ConcurrentModificationException(
     "The expected size of the underlying vector was: [" + expectedSize + "], but the " +
     "encountered size was: [" + v.size() + "].  This implies that the Vector was modified " +
     "outside of this HNLI Iterator's provided update & modify API.  This is not allowed, " +
     "unless followed by a call to: first, last, firstIndex, or lastIndex - all of which " +
     "'reset' the outside-modification monitor-logic (as do the cursor-movement and cursor " +
     "bounds methods)."
 );