Class AbstractHNLI<E extends HTMLNode,​F>

  • 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>
    AbstractHNLI: Abstract HTML Node List Iterator - Documentation.

    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:
        1
        2
        @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:
        1
        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:
        1
        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:
        1
        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:
        1
        protected boolean modifiedSince = true;
        
      • maxCursor

        protected int maxCursor
        The maximum boundary for the Cursor Boundary Window.

        Initialized to '-1' means the default setting is for the Iterator is not to use a Cursor Boundaries. One may be assigned using the restrictCursor(...) methods.
        See Also:
        restrictCursor(DotPair), restrictCursor(int, int), clearCursorBounds()
        Code:
        Exact Field Declaration Expression:
        1
        protected int maxCursor = -1;
        
      • minCursor

        protected int minCursor
        The minimum boundary for the Cursor Boundary Window.

        Initialized to '-1' means the default setting is for the Iterator is not to use a Cursor Boundaries. One may be assigned using the restrictCursor(...) methods.
        See Also:
        restrictCursor(DotPair), restrictCursor(int, int), clearCursorBounds()
        Code:
        Exact Field Declaration Expression:
        1
        protected int minCursor = -1;
        
      • expectedSize

        protected int expectedSize
        This is an attempt to monitor outside modifications to an HTML Vector
        Code:
        Exact Field Declaration Expression:
        1
        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:
        1
        2
        3
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
        2
        3
        4
        5
        6
        7
         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:
        1
         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:
        1
         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.

        NOTE: This method is somewhat of a "reset method" - because the internal-cursor is moved to the beginning of the underlying-Vector. Whenever the cursor is moved (or restricted), the logic that checks for a ConcurrentModificationException is reset.

        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 shall prevent an exception throw if outside modification of the underlying Vector has occurred.

        Methods from this class that move (or restrict) the cursor, include: first(), last(), firstIndex(), lastIndex(), moveCursor(...), and restrictCursor(...)
        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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
         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​(LV loopVariable)
        Convenience Method. Accepts LV. Invokes restrictCursor(int, int).
        Code:
        Exact Method Body:
        1
         restrictCursor(loopVariable.start, loopVariable.end - 1);
        
      • 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.

        NOTE: This method is somewhat of a "reset method" - because the internal-cursor is moved to the beginning of the underlying-Vector. Whenever the cursor is moved (or restricted), the logic that checks for a ConcurrentModificationException is reset.

        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 shall prevent an exception throw if outside modification of the underlying Vector has occurred.

        Methods from this class that move (or restrict) the cursor, include: first(), last(), firstIndex(), lastIndex(), moveCursor(...), and restrictCursor(...)
        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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
         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:
        1
         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:
        1
         return cursor;
        
      • add

        public void add​(E e)
        Convenience Method. Invokes addHTMLNode(HTMLNode)
        Code:
        Exact Method Body:
        1
         addHTMLNode(e);
        
      • 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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         CHECK_EXCEPTIONS();
        
         v.addAll(cursor, html);
        
         cursor += html.size();
        
         if (maxCursor != -1) maxCursor += html.size();
            
         MODIFIED();
        
      • set

        public void set​(E e)
        Convenience Method. Invokes setHTMLNode(HTMLNode)
        Code:
        Exact Method Body:
        1
         setHTMLNode(e);
        
      • 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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         remove();
        
         v.add(cursor, n);
        
         cursor++;
        
         expectedSize++;
        
         if (maxCursor != -1) maxCursor++;
        
      • set

        public void set​(java.lang.String html)
        Convenience Method. Parses HTML HTMLPage.getPageTokens(CharSequence, boolean)

        And Invokes 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:
        1
         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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         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. Parses HTML HTMLPage.getPageTokens(CharSequence, boolean)

        And Invokes 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:
        1
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         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:
        1
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         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:
        1
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
         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:
        1
        2
        3
        4
         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:
        1
        2
        3
        4
         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:
        1
        2
        3
        4
         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, there is a private int 'expectedSize' maintained. If modifications are made to the underlying vectorized-html, from outside of the add(...), set(...) or remove(...) variants provided by this interface then the value of this internal-field int 'expectedSize' will not be consistent with the actual size of the Vector. When this situation arises, both class HNLI and also HNLIInclusive will throw a ConcurrentModificationException.

        NOTE: Changes to the underlying Vector that do not modify the size will simply not be detected. This is due to 'a bug' in the JDK implementation of AbstractList which keeps an integer-field named 'modCount' stored as 'protected' - and (unfortunately) unavailable to implementers of AbstractList (rendering it useless).

        ALSO: Any call made to a variant of the provided first(...) or last(...) methods will cause the internal int 'expected-size' field to reset. This would, therefore, prevent ConcurrentModificationException from throwing - even if code from outside the Iterator had modified the size of the underlying Vector.
        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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
         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:
        1
        2
        3
        4
        5
        6
        7
        8
         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)."
         );