Class HNLIInclusive

  • All Implemented Interfaces:
    java.util.Iterator<java.util.Vector<HTMLNode>>, java.util.ListIterator<java.util.Vector<HTMLNode>>
    public class HNLIInclusive
extends AbstractHNLI<TagNode,​java.util.Vector<HTMLNode>>
    HNLIInclusive: HTMLNode ListIterator Inclusive
    This is an Iterator class that has been heavily improved to allow for all types of updates, additions, removals, etc... to a vectorized-html web-page. The methods that are provided allow a user to request an Iterator from the Inclusive Iterator retrieval classes in this Node-Search Package.

    The concept of 'Inclusive', as explained quite thoroughly in the classes that contain this word, 'Inclusive' means that in this here Iterator, sub-lists of (Vectors) of 'HTMLNode' will be returned from the nextElement() methods in this class. Each Vector or sublist of HTMLNode will begin with an opening HTML Element, for example '<DIV ...>', and the last element in the Vector that's returned, will be a Matching, Closing, Element - for example '</DIV>'

    HNLIInclusive Generator Class:
    Iterates 'Inclusive' TagNode sublist-matches, which would be similar to iterating the '.innerHTML' fields of elements in a JavaScript DOM-Tree.

    This interface builds on Java's 'ListIterator<E>' interface.

    Iterator<E>
    public interface java.util.Iterator<E> exports these methods:

    • boolean hasNext()
    • default void forEachRemaining(Consumer<? super E> action)
    • E next()
    • default void remove()


    ListIterator<E>
    public interface java.util.ListIterator<E> extends the previous Iterator with these methods:

    • void add(E e)
    • boolean hasNext()
    • boolean hasPrevious()
    • E next()
    • int nextIndex()
    • E previous()
    • int previousIndex()
    • void remove()
    • void set(E e)


    This Iterator class further extends Java's ListIterator<E> to add several HTMLNode and Vector<HTMLNode> specific insertion, deletion, and replacement operations. These methods are all properly-listed below in the Method-Summary Section of this class' Java-Doc Documentation-Page.


    Easy to Use:
    Generally, it is sometimes apparent that Java's introduction of the concept of generics - and particularly the Iterator<E> and ListIterator<E> has been somewhat down-played in some circles. The value of an Iterator is sometimes over-looked when applied to data-modification. 4 out of 6 of the static method-based class-types in this package: Find, Get, Peek, Count and Count provide only "data-observation" of the underlying Vectorized-HTML. The other two Poll and Remove, however, modify the underlying Vector.

    All of these work fine without an using an Iterator, however, there may be cases where node-replacement and node-removal on a case-by-case basis will be necessary. And that can lead to problems caused by stale data pointers.


    Stale Data-Pointers Helper:
    If an array of index pointers is requested: 

    int[] posArr = TagNodeFind.all(...)


    When the user begins replacing and removing nodes using this array... if at any point the size of the Vector is changed, the entire pointer-array will immediately contain stale-data!

    This can be overcome by maintaining a 'Vector-size delta' value, and offsetting each value in the pointer-array. Other tricks include modifying the data inside the Vector in reverse-order. Working with the last index-pointers first means that when or if the size of a HTML-Vector changes, the earlier pointers will not become stale. Remember, after an insert or remove operation is done on a list, only the nodes that lay after the insert-index or remove-index are shifted!

    Indeed, however, this is exactly what the HNLI and HNLIInclusive iterators do internally! If a programmer employs the set(...), add(...) and remove(...) methods provided by the Iterator-classes both in this package, and the java-interfaces they inherit, internally a size-delta and a cursor are maintained by the Iterator when & if elements are added, updated and removed.

    As long long as the underlying Vector is not modified by code outside of the Iterator methods, stale and invalid data-pointers will never be returned by the getter methods of this class. Index-Pointer Arrays are often useful, but less-so when the user plans on changing or adding sections of HTMLNode that change how many nodes are in the underlying Vector.

    Iterator Efficiency:
    If large numbers of changes are going to be made to big Vectorized-HTML web-pages, it is much more efficient to use the Replaceable interface than an Iterator! However, in cases where several quick change or retrieval operations are needed (and to smaller pages), and where efficiency is not imperative, writing HTML-Retrieval or Update Code using an HNLI will usually be code that is world's easier to understand, read and write.


    • Method Detail

      • hasPrevious

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean hasPrevious()
        Use this method to find out whether the underlying Vector and current cursor position would retrieve another match if 'previous' or 'previousIndex' were called.
        Returns:
        This shall return TRUE if calling the previous(), or previousIndex() methods would return another inclusive / sub-list node-match. This method shall return FALSE if calling previous() would generate / throw a 'NoSuchElementException' - because there are no more sub-list matches in the underlying Vector, given the current cursor position.
        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.

        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.
        See Also:
        Util.Inclusive.subSectionOPT(Vector, int, int), TagNode.isClosing, SubSection
        Code:
        Exact Method Body:
         CHECK_CME();

 if (hasPrevDP != null) return true;

 int LOOP_BOUNDARY = (minCursor == -1) ? 0 : minCursor;

 if (cursor == -1) cursor = LOOP_BOUNDARY;  // will return false

 while (--cursor >= LOOP_BOUNDARY)

     if ((hasPrevDP = TEST_CURSOR_INCLUSIVE()) != null)
         return true;

 return false;

      • previous

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Vector<HTMLNode> previous()
        Returns the nearest sub-list match in the underlying Vector, given the current cursor position - when searching in the left-direction, or in the direction of decreasing Vector-indices.
        Returns:
        This shall return the sub-list match that is directly previous to the current cursor position.
        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.

        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.util.NoSuchElementException - If there are not more matches, this exception shall throw. Avoid having to catch this exception by always calling method 'hasPrevious', and only invoking 'previous' if that method returned TRUE.
        Code:
        Exact Method Body:
         return Util.cloneRange(v, previousDotPair());

      • previousDotPair

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public DotPair previousDotPair()
        This method, in-some-ways (but-not-others), "overrides" the original ListIterator<E> method named previousIndex(). Since class HNLIInclusive is an Iterator over "sub-lists" - not individual nodes - whenever a Vector-index position is expected, the programmer should be expecting this Iterator to return two values: both a sub-list start-position, and also a sublist ending-Vector-position.

        Returning a complete Sub-List in a single Java-Reference is the entire rationale behind class DotPair. Class DotPair allows pointer-indices to paired together and returned, and eliminates the need to return actual copies of list-nodes themslves.

        Implementing ListIterator.previousIndex()
        Java's ListIterator class has an abstract-method that must be implemented - namely previousIndex(). Java requires this method to exist in order for this class to properly implement the interface.

        This method (previousDotPair()), however, is provided as a "far better solution" than the original 'previousIndex()' method. ListIterator's previousIndex() method can still be used. However, the actual intention of an "HNLI Inclusive" Iterator is to find entire Sublist-Matches in a Vectorized-HTML Web-Page, and thusly, returning a single integer-index is not actually acheiving that purpose.

        The method previousIndex(), which again is mandatory, will return an integer that points to the Begin-Index of the previous sub-list match, but will (obviously) leave off the Ending-Index of that very match! Remember that the concept behind the key-word "Inclusive" is such that a complete Vector-Sublist shall be searched, found, and returned - rather than just the first HTML TagNode of that Sub-List.

        DotPair Return-Type Summary:
        This method, previousDotPair, returns a value that is more closely in line with the concepts behind an HTML Node List-Iterator than that returned by method int previousIndex(). The latter will return an integer index-pointer (into the underlying vectorized-HTML page-Vector) that identifies the first element of the previous-match.

        But if only the opening sub-list Vector-index is returned (and the closing Vector-index is omitted), this will very-often (but not always) be completely useless information! A "Sub-List Match" is comprised of both Opening & Closing Indices, and therefore necessitates a complete DotPair return, rather than an integer.
        Returns:
        The previous integer-pointer pair to the starting-index and ending-index of the previous "inclusive-sublist match" found on the vectorized-html webpage.
        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.

        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.
        See Also:
        Util.Inclusive.subSectionOPT(Vector, int, int), TagNode.isClosing
        Code:
        Exact Method Body:
         CHECK_CME();

 lastReturned    = hasPrevDP;
 hasNextDP       = hasPrevDP = null;
 modifiedSince   = false;

 if (lastReturned != null) return lastReturned;

 int LOOP_BOUNDARY = (minCursor == -1) ? 0 : minCursor;

 if (cursor == -1) cursor = LOOP_BOUNDARY; // Will throw exception

 while (--cursor >= LOOP_BOUNDARY)

     if ((lastReturned = TEST_CURSOR_INCLUSIVE()) != null)
         return lastReturned;

 throw new NoSuchElementException("There are no more previous elements available.");

      • hasNext

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean hasNext()
        Use this method to find out whether the underlying Vector and current cursor position would retrieve another match if 'next' or 'nextIndex' were called.
        Returns:
        This shall return TRUE if calling the next(), or nextIndex() methods would return another inclusive / sub-list match. This method shall return FALSE if calling 'next' would generate / throw a 'NoSuchElementException' - because there are no more sub-list matches in the underlying Vector, given the current cursor position.
        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.

        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.
        See Also:
        AbstractHNLI.CHECK_CME(), Util.Inclusive.subSectionOPT(Vector, int, int), TagNode.isClosing, SubSection
        Code:
        Exact Method Body:
         CHECK_CME();

 if (hasNextDP != null) return true;

 int LOOP_BOUNDARY = (maxCursor == -1) ? (v.size() - 1) : maxCursor;

 if (cursor == -1) cursor = (minCursor == -1) ? -1 : (minCursor-1);

 while (++cursor <= LOOP_BOUNDARY)

     if ((hasNextDP = TEST_CURSOR_INCLUSIVE()) != null)
         return true;

 return false;

      • next

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Vector<HTMLNode> next()
        Returns the nearest node-match in the underlying Vector, given the current cursor position - when searching in the right-direction, or in the direction of increasing Vector-indices.
        Returns:
        This shall return the sub-list match that is directly next to the current cursor position.
        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.

        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.util.NoSuchElementException - If there are not more matches, this exception shall throw. Avoid having to catch this exception by always calling method 'hasNext', and only invoking 'next' if that method returned TRUE.
        See Also:
        AbstractHNLI.CHECK_CME(), Util.Inclusive.subSectionOPT(Vector, int, int), TagNode.isClosing, SubSection
        Code:
        Exact Method Body:
         return Util.cloneRange(v, nextDotPair());

      • nextDotPair

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public DotPair nextDotPair()
        This method, in-some-ways (but-not-others), "overrides" the original ListIterator<E> method named nextIndex(). Since class HNLIInclusive is an Iterator over "sub-lists" - not individual nodes - whenever a Vector-index position is expected, the programmer should be expecting this Iterator to return two values: both a sub-list start-position, and also a sublist ending-Vector-position.

        Returning a complete Sub-List in a single Java-Reference is the entire rationale behind class DotPair. Class DotPair allows pointer-indices to paired together and returned, and eliminates the need to return actual copies of list-nodes themslves.

        Implementing ListIterator.nextIndex()
        Java's ListIterator class has an abstract-method that must be implemented - namely nextIndex(). Java requires this method to exist in order for this class to properly implement the interface.

        This method (nextDotPair()), however, is provided as a "far better solution" than the original 'nextIndex()' method. ListIterator's nextIndex() method can still be used. However, the actual intention of an "HNLI Inclusive" Iterator is to find entire Sublist-Matches in a Vectorized-HTML Web-Page, and thusly, returning a single integer-index is not actually acheiving that purpose.

        The method nextIndex(), which again is mandatory, will return an integer that points to the Begin-Index of the next sub-list match, but will (obviously) leave off the Ending-Index of that very match! Remember that the concept behind the key-word "Inclusive" is such that a complete Vector-Sublist shall be searched, found, and returned - rather than just the first HTML TagNode of that Sub-List.

        DotPair Return-Type Summary:
        This method, nextDotPair, returns a value that is more closely in line with the concepts behind an HTML Node List-Iterator than that returned by method int nextIndex(). The latter will return an integer index-pointer (into the underlying vectorized-HTML page-Vector) that identifies the first element of the next-match.

        But if only the opening sub-list Vector-index is returned (and the closing Vector-index is omitted), this will very-often (but not always) be completely useless information! A "Sub-List Match" is comprised of both Opening & Closing Indices, and therefore necessitates a complete DotPair return, rather than an integer.
        Returns:
        The next integer-pointer pair to the starting-index and ending-index of the next "inclusive-sublist match" found on the vectorized-html webpage.
        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.

        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.
        See Also:
        AbstractHNLI.CHECK_CME(), Util.Inclusive.subSectionOPT(Vector, int, int), TagNode.isClosing, SubSection
        Code:
        Exact Method Body:
         CHECK_CME();

 lastReturned    = hasNextDP;
 hasNextDP       = hasPrevDP = null;
 modifiedSince   = false;

 if (lastReturned != null) return lastReturned;

 int LOOP_BOUNDARY = (maxCursor == -1) ? (v.size() - 1) : maxCursor;

 if (cursor == -1) cursor = (minCursor == -1) ? -1 : (minCursor-1);

 while (++cursor <= LOOP_BOUNDARY)

     if ((lastReturned = TEST_CURSOR_INCLUSIVE()) != null)
         return lastReturned;

 throw new NoSuchElementException("There are no more next elements available.");

      • firstDotPair

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public DotPair firstDotPair()
        This adds method public DotPair firstIDotPair() to the java public interface ListIterator<E>. This, actually, returns an instance of DotPair. Because this Iterator iterates Vector-sublists, not individual HTML nodes, the first-index of the first match will be a DotPair, not an integer. This (hopefully-obvious) is because the public class DotPair encapsulates two needed numbers (a Vector-position start-index, and an ending-index) into a single-data-class.

        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.
        Returns:
        Out of the entire vectorized-html webpage, this method resets the internal cursor, and returns the first 'DotPair' match - the starting-index and ending-index - of the first "inclusive-sublist match"
        See Also:
        nextDotPair(), lastDotPair()
        Code:
        Exact Method Body:
         cursor          = 0;
 hasNextDP       = hasPrevDP = null;

 // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
 expectedSize    = v.size();

 return nextDotPair();

      • lastDotPair

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public DotPair lastDotPair()
        This does the same as firstIDotPair() but returns the last list match index-pair found within the input Vector.

        This adds method public DotPair lastIDotPair() to the java public interface ListIterator<E>. This, actually, returns an instance of DotPair. Because this Iterator iterates Vector-sublists, not individual HTML nodes, the last-index of the last match will be a 'DotPair' not an integer. This (hopefully obviously) is because the public class DotPair encapsulates two needed numbers (a Vector-position start-index, and an ending-index) into a single-data-class.

        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.
        Returns:
        Out of the entire vectorized-html webpage, this method resets the internal pointer, and returns the last 'DotPair' match - the starting-index and ending-index - of the last "inclusive-sublist match"
        See Also:
        previousDotPair(), firstDotPair()
        Code:
        Exact Method Body:
         cursor          = v.size() - 1;
 hasNextDP       = hasPrevDP = null;

 // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
 expectedSize    = v.size();

 return previousDotPair();

      • first

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Vector<HTMLNode> first()
        This adds to the ListIterator<E> class by providing a first() method that resets this Iterator back to the first match that is found in the underlying html-Vector. The internal-cursor will be moved back to the beginning of the Vector.

        Modified Return-Value:
        If the underlying web-page Vector has been modified, then this method shall return the updated first match. There is no "match memory." Rather, if the underlying Vector changes, further calls to next(), previous(), first() and last() would also change.

        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.
        Returns:
        This returns the first "inclusive" sub-list (open-tag / start-tag up to the next close-tag) match as a vectorized-html sublist.
        See Also:
        next()
        Code:
        Exact Method Body:
         cursor          = 0;
 hasNextDP       = hasPrevDP = null;

 // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
 expectedSize    = v.size();

 return next();

      • last

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Vector<HTMLNode> last()
        This adds to the ListIterator<E> class by providing a last() method that moves this Iterator to the last match that is found in the underlying html-Vector. The internal-cursor will be moved directly to the end of the Vector.

        Modified Return-Value:
        If the underlying web-page Vector has been modified, then this method shall return the updated first match. There is no "match memory." Rather, if the underlying Vector changes, further calls to next(), previous(), first() and last() would also change.

        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.
        Returns:
        This returns the last "inclusive" sub-list (open-tag / start-tag up to the next close-tag) match as an vectorized-html sublist.
        See Also:
        previous()
        Code:
        Exact Method Body:
         cursor          = v.size() - 1;
 hasNextDP       = hasPrevDP = null;

 // Calls to first, last, firstIndex, or lastIndex "reset" the CME Monitor-Logic
 expectedSize    = v.size();

 return previous();

      • previousIndex

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int previousIndex()
        The veracity of using this method has been eclipsed by method public previoustDotPair(). Nothing problematic should happen, that is unless you forget that this Iterator is an 'inclusive' Iterator. The word "Inclusive" is intended to indicate that a 'range' or 'sublist' (demarcated by a 'start' and 'end' Vector-index pair) are involved. This is usually-but-not-always expressed using an instance of class 'DotPair'. The starting and ending indices are meant to point to HTML opening and closing element tags such as: <DIV> and </DIV>, or maybe <A> and </A>

        Because this method only returns a single integer, and that is the index of the previous opening HTML Tag matching the iterator's constraints (but leaves off the closing-tag) this method 'previousIndex()' may seem out of place.
        Returns:
        Returns the index of the beginning of the previous matched sub-section.
        Code:
        Exact Method Body:
         return previousDotPair().start;

      • nextIndex

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public int nextIndex()
        The veracity of using this method has been eclipsed by method public nextDotPair() Nothing problematic should happen, that is unless you forget that this Iterator is an 'inclusive' Iterator. The word "Inclusive" is intended to indicate that a 'range' or 'sublist' (demarcated by a 'start' and 'end' Vector-index pair) are involved. This is usually-but-not-always expressed using an instance of class 'DotPair'. The starting and ending indices are meant to point to HTML opening and closing element tags such as: <DIV> and </DIV>, or maybe <A> and </A>

        Because this method only returns a single integer, and that is the index of the next opening HTML Tag matching the iterator's constraints (but leaves off the closing-tag) this method 'nextIndex()' may seem out of place.
        Returns:
        Returns the index of the beginning of the next matched sub-section.
        Code:
        Exact Method Body:
         return nextDotPair().start;