1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
package Torello.HTML.NodeSearch;

import java.util.*;

import java.util.function.Predicate;

import Torello.HTML.*;

import Torello.Java.LV;
import Torello.HTML.Util.Inclusive;

/**
 * Iterates <B>'Inclusive'</B> {@link TagNode} sublist-matches, which would be similar to iterating
 * the <CODE>'&#46;innerHTML'</cODE> fields of elements in a JavaScript DOM-Tree.
 * 
 * <EMBED CLASS="external-html" DATA-FILE-ID=HNLIInclusive>
 */
@SuppressWarnings("unchecked")
@Torello.HTML.Tools.JavaDoc.JDHeaderBackgroundImg
public class HNLIInclusive extends AbstractHNLI<TagNode, Vector<HTMLNode>> 
{
    // **************************************************************************************
    // Private, Non-Static, Fields
    // **************************************************************************************

    private DotPair hasNextDP       = null;
    private DotPair hasPrevDP       = null;
    private DotPair lastReturned    = null;

    // **************************************************************************************
    // lone constructor
    // **************************************************************************************

    /**
     * This will produce an P@code Iterator} with generic type {@code 'E'}.  The last parameter to
     * this constructor {@code Class<E> c} is required since as per Java's Erasure "Feature" -
     * there is no way to identify what the Variable-Type Parameter {@code 'E'} evaluates at
     * Run-Time.
     * 
     * <BR /><BR /><B><SPAN STYLE="color: red;">PROTECTED NOTE:</B></SPAN> This method is, by
     * necessity kept {@code 'protected'} because of the nature of what constitutes an match for a
     * {@code TagNode} when <B>'Inclusive'</B> Sublists are to be returned.
     * 
     * @param html This may be any HTML {@code Vector} or sub-section.
     *
     * @param p This is a {@code java.util.function.Predicate} that identifies when the
     * {@code Iterator} should consider a {@code TagNode} a "Match."
     */
    HNLIInclusive (Vector<? extends HTMLNode> html, Predicate<TagNode> p)
    { super(html, p, TagNode.class); }

    void RESET_MATCHES() { hasNextDP = hasPrevDP = lastReturned = null; }

    int REMOVE() { return Util.removeRange(v, lastReturned); }


    // **************************************************************************************
    // HELPER
    // **************************************************************************************

    private DotPair TEST_CURSOR_INCLUSIVE()
    {
        Object o = v.elementAt(cursor);

        if (! (o instanceof TagNode)) return null;

        TagNode tn = (TagNode) o;

        if (tn.isClosing) return null;

        if (! p.test(tn)) return null;

        if (maxCursor == -1)    return Inclusive.dotPairOPT(v, cursor);
        else                    return Inclusive.dotPairOPT(v, cursor, maxCursor);
    }

    // **************************************************************************************
    // "Previous" - Retrieval Operations
    // **************************************************************************************

    /**
     * Use this method to find out whether the underlying {@code Vector} and current {@code cursor}
     * position would retrieve another match if {@code 'previous'} or {@code 'previousIndex'} were
     * called.
     * 
     * @return This shall return <B>TRUE</B> if calling the {@code previous()}, or 
     * {@code previousIndex()} methods would return another inclusive / sub-list node-match.  This
     * method shall return <B>FALSE</B> if calling {@code previous()} would generate / throw a 
     * {@code 'NoSuchElementException'} - <I>because there are no more sub-list matches in the
     * underlying {@code Vector}, given the current {@code cursor} position.</I>
     * 
     * @throws ConcurrentModificationException <EMBED CLASS="external-html" DATA-FILE-ID="CMEX">
     * 
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public boolean hasPrevious()
    {
        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;
    }

    /**
     * Returns the nearest sub-list match in the underlying {@code Vector}, given the current
     * {@code cursor} position - <I>when searching in the left-direction, or in the direction of
     * decreasing {@code Vector}-indices.</I>
     * 
     * @return This shall return the sub-list match that is directly previous to the current
     * {@code cursor} position.
     * 
     * @throws ConcurrentModificationException <EMBED CLASS="external-html" DATA-FILE-ID="CMEX">
     * 
     * @throws NoSuchElementException If there are not more matches, this exception shall throw.  
     * Avoid having to catch this exception by always calling method {@code 'hasPrevious'}, and
     * only invoking {@code 'previous'} if that method returned <B>TRUE.</B>
     */
    public Vector<HTMLNode> previous()
    { return Util.cloneRange(v, previousDotPair()); }

    /**
     * This method, in-some-ways but-not-others, <B>"overrides"</B> the original
     * {@code ListIterator<E> public int previousIndex()} method.  Since
     * {@code public class HNLIInclusive} is an {@code Iterator} over "sub-lists" - <I>not
     * individual nodes</I> - this means that whenever a {@code Vector}-index position is expected,
     * the programmer should be expecting this {@code Iterator} to return two values:  both a
     * sub-list start-position, and also a sublist ending-{@code Vector}-position.  <I><B>This is
     * the purpose of {@code class DotPair}</B></I> - it allows pointers (indices) rather than
     * copies of the nodes themselves to be saved, copied or evaluated.
     *
     * <BR /><BR /><B>NOTE:</B> Java's {@code public int 'previousIndex()'} method requires that an
     * integer be returned in order for this class to properly implement the
     * {@code public interface ListIterator<E>}.  This method, however, is offered as a "better 
     * substitution for" the original {@code 'previousIndex'} method.  The original
     * {@code previousIndex()} method in the ancestor {@code interface ListIterator}  may still be
     * used, but the actual intention (finding sublists matches in a vectorized-html webpage) could
     * be misunderstood by a novice.  Method {@code previousIndex()}, which is mandatory, will
     * return an integer that points to the beginning index of the next sub-list match, <I>but will
     * (obviously) leave off the ending-position of the next sub-list match.</I>  Remember that the
     * concept behind the key-word "Inclusive" is that a {@code Vector}-sublist shall searched,
     * found, and returned, not just the first HTML Element {@code TagNode} found.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">SUMMARY OF ISSUE:</B></SPAN> The method
     * {@code previousDotPair()} returns a value that is more-exactly in-line with the notion of an
     * HTML Node List Iterator than the method {@code previousIndex()}.  The latter will return an
     * integer index-pointer (into the underlying vectorized-HTML page-{@code Vector}) that
     * identifies the first element of the previous-match, but leave off completely information
     * about where that sublist ends.
     *
     * @return 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 ConcurrentModificationException <EMBED CLASS="external-html" DATA-FILE-ID="CMEX">
     * 
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     */
    public DotPair previousDotPair()
    {
        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.");
    }

    // **************************************************************************************
    // "Next" - Retrieval Operations
    // **************************************************************************************

    /**
     * Use this method to find out whether the underlying {@code Vector} and current {@code cursor}
     * position would retrieve another match if {@code 'next'} or {@code 'nextIndex'} were called.
     * 
     * @return This shall return <B>TRUE</B> if calling the {@code next()}, or {@code nextIndex()}
     * methods would return another inclusive / sub-list match.  This method shall return
     * <B>FALSE</B> if calling {@code 'next'} would generate / throw a
     * {@code 'NoSuchElementException'} - <I>because there are no more sub-list matches in the
     * underlying {@code Vector}, given the current {@code cursor} position.</I>
     * 
     * @throws ConcurrentModificationException <EMBED CLASS="external-html" DATA-FILE-ID="CMEX">
     * 
     * @see #CHECK_CME()
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public boolean hasNext()
    {
        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;
    }

    /**
     * Returns the nearest node-match in the underlying {@code Vector}, given the current
     * {@code cursor} position - <I>when searching in the right-direction, or in the direction of
     * increasing {@code Vector}-indices.</I>
     * 
     * @return This shall return the sub-list match that is directly next to the current
     * {@code cursor} position.
     * 
     * @throws ConcurrentModificationException <EMBED CLASS="external-html" DATA-FILE-ID="CMEX">
     * 
     * @throws NoSuchElementException If there are not more matches, this exception shall throw.  
     * Avoid having to catch this exception by always calling method {@code 'hasNext'}, and only
     * invoking {@code 'next'} if that method returned <B>TRUE.</B>
     * 
     * @see #CHECK_CME()
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public Vector<HTMLNode> next()
    { return Util.cloneRange(v, nextDotPair()); }

    /**
     * This method, in-some-ways but-not-others, <B>"overrides"</B> the original
     * {@code ListIterator<E>.nextIndex()} method.  Since {@code public class HNLIInclusive} is an
     * {@code Iterator} over "sub-lists" - <I>not individual nodes</I> - this means that whenever a
     * {@code Vector}-index position is expected, the programmer should be expecting this
     * {@code Iterator} to return two values: both a sub-list start-position, and also a sublist
     * ending-{@code Vector}-position.  <I><B>This is the purpose of {@code class DotPair}</B></I>
     * - it allows pointers (indices) rather than copies of the nodes themselves to be saved,
     * copied or evaluated.
     *
     * <BR /><BR /><B>NOTE:</B> Java's {@code public int nextIndex()} method requires that an
     * integer be returned in order for this class to properly implement the
     * {@code public interface ListIterator<>}.  This method, however, is offered as a "better
     * substitution for" the original {@code 'nextIndex'} method.  The original {@code nextIndex()}
     * method in the ancestor {@code class ListIterator} may still be used, but the actual
     * intention (finding sublists matches in a vectorized-html webpage) could be misunderstood by
     * a novice.  Method {@code next()}, which is mandatory, will return an integer that points to
     * the begin index of the next sub-list match, <I>but will (obviously) leave off the
     * ending-position of the next sub-list match.</I>  Remember that the concept behind the
     * key-word "Inclusive" is that a {@code Vector}-sublist shall searched, found, and returned,
     * not just the first HTML Element {@code TagNode} found.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">SUMMARY OF ISSUE:</B></SPAN> The method
     * {@code nextDotPair()} returns a value that is more-exactly in-line with the notion of an
     * HTML Node List Iterator than the method {@code nextIndex()}.  The latter will return an
     * integer index-pointer (into the underlying vectorized-HTML page-{@code Vector}) that
     * identifies the first element of the next-match, but leave off completely information about
     * where that sublist ends.
     *
     * @return 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 ConcurrentModificationException <EMBED CLASS="external-html" DATA-FILE-ID="CMEX">
     * 
     * @see #CHECK_CME()
     * @see Util.Inclusive#subSectionOPT(Vector, int, int)
     * @see TagNode#isClosing
     * @see SubSection
     */
    public DotPair nextDotPair()
    {
        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.");
    }

    // **************************************************************************************
    // "First" and "Last" - Retrieval Operations
    // **************************************************************************************

    /**
     * This adds method {@code public DotPair firstIDotPair()} to the java
     * {@code public interface ListIterator<E>.}
     * This, actually, returns an instance of {@code DotPair}.  Because this {@code Iterator}
     * iterates {@code Vector}-sublists, not individual HTML nodes, the first-index of the first
     * match will be a {@code DotPair}, <I>not an integer.</I>  This (hopefully-obvious) is because
     * the {@code public class DotPair} encapsulates two needed numbers (a {@code Vector}-position
     * start-index, and an ending-index) into a single-data-class.
     * 
     * <EMBED CLASS="external-html" DATA-FILE-ID="CMERESET">
     *
     * @return Out of the entire vectorized-html webpage, this method resets the internal
     * {@code cursor}, and returns the first {@code 'DotPair'} match - the starting-index and
     * ending-index - of the first "inclusive-sublist match"
     * 
     * @see #nextDotPair()
     * @see #lastDotPair()
     */
    public DotPair firstDotPair()
    {
        cursor          = 0;
        hasNextDP       = hasPrevDP = null;

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

        return nextDotPair();
    }

    /**
     * This does the same as {@code firstIDotPair()} but returns the <B><I>last list
     * match index-pair</I></B> found within the input {@code Vector}.
     *
     * <BR /><BR />This adds method {@code public DotPair lastIDotPair()} to the java
     * {@code public interface ListIterator<E>.}  This, actually, returns an instance of
     * {@code DotPair}.  Because this {@code Iterator} iterates {@code Vector}-sublists, not
     * individual HTML nodes, the last-index of the last match will be a {@code 'DotPair'}
     * <I>not an integer.</I>  This (hopefully obviously) is because the {@code public
     * class DotPair} encapsulates two needed numbers (a {@code Vector}-position start-index,
     * and an ending-index) into a single-data-class.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="CMERESET">
     *
     * @return Out of the entire vectorized-html webpage, this method resets the internal pointer,
     * and returns the last {@code 'DotPair'} match - the starting-index and ending-index - of the
     * last "inclusive-sublist match"
     * 
     * @see #previousDotPair()
     * @see #firstDotPair()
     */
    public DotPair lastDotPair()
    {
        cursor          = v.size() - 1;
        hasNextDP       = hasPrevDP = null;

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

        return previousDotPair();
    }

    /**
     * This adds to the {@code ListIterator<E>} class by providing a {@code first()} method that
     * resets this {@code Iterator} back to the first match that is found in the underlying
     * html-{@code Vector}.  The internal-{@code cursor} will be moved back to the beginning of
     * the {@code Vector}.
     *
     * <BR /><BR /><B>NOTE:</B> If the underlying web-page {@code Vector} has been modified, then
     * this method shall return the <I>updated first match.</I>  There is no "match memory."
     * Rather, if the underlying {@code Vector} changes, further calls to {@code next(), previous(),
     * first()} and {@code last()} could also change.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="CMERESET">
     *
     * @return This returns the first "inclusive" sub-list (open-tag / start-tag up to the next
     * close-tag) match as a vectorized-html sublist.
     * 
     * @see #next()
     */
    public Vector<HTMLNode> first()
    {
        cursor          = 0;
        hasNextDP       = hasPrevDP = null;

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

        return next();
    }

    /**
     * This adds to the {@code ListIterator<E>} class by providing a {@code last()} method that
     * moves this {@code Iterator} to the last match that is found in the underlying 
     * html-{@code Vector}.  The internal-{@code cursor} will be moved directly to the end of the
     * {@code Vector}.
     *
     * <BR /><BR /><B>NOTE:</B> If the underlying web-page {@code Vector} has been modified, then
     * this method shall return the <I>updated last match.</I>  There is no "match memory."
     * Rather, if the underlying {@code Vector} changes, further calls to {@code next(), previous(),
     * first()} and {@code last()} could also change.
     *
     * <EMBED CLASS="external-html" DATA-FILE-ID="CMERESET">
     *
     * @return This returns the last "inclusive" sub-list (open-tag / start-tag up to the next
     * close-tag) match as an vectorized-html sublist.
     * 
     * @see #previous()
     */
    public Vector<HTMLNode> last()
    {
        cursor          = v.size() - 1;
        hasNextDP       = hasPrevDP = null;

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

        return previous();
    }

    // **************************************************************************************
    // NEXT and PREVIOUS Index
    // **************************************************************************************

    /**
     * The veracity of using this method has been eclipsed by method {@code public
     * previoustDotPair()}.  Nothing problematic should happen, that is unless you forget that this
     * {@code Iterator} is an 'inclusive' {@code Iterator}.  The word "Inclusive" is intended to
     * indicate that a 'range' or 'sublist' (demarcated by a {@code 'start'} and {@code 'end'}
     * {@code Vector}-index pair) are involved.  This is <I>usually-but-not-always</I> expressed
     * using an instance of class {@code 'DotPair'}.  The starting and ending indices are meant to
     * point to HTML opening and closing element tags such as: {@code <DIV>} and {@code </DIV>}, or
     * maybe {@code <A>} and {@code </A>}
     *
     * <BR /><BR />Because this method only returns a single integer, and that is the index of the
     * <I>previous opening HTML Tag</I> matching the iterator's constraints (but leaves off the
     * closing-tag) this method {@code 'previousIndex()'} may seem out of place.
     * 
     * @return Returns the index of the beginning of the previous matched sub-section.
     */
    public int previousIndex() { return previousDotPair().start; }

    /**
     * The veracity of using this method has been eclipsed by method {@code public nextDotPair()}
     * Nothing problematic should happen, that is unless you forget that this {@code Iterator} is
     * an 'inclusive' {@code Iterator}. The word "Inclusive" is intended to indicate that a 'range'
     * or 'sublist' (demarcated by a {@code 'start'} and {@code 'end'} {@code Vector}-index pair)
     * are involved.  This is <I>usually-but-not-always</I> expressed using an instance of class
     * {@code 'DotPair'}.  The starting and ending indices are meant to point to HTML opening and
     * closing element tags such as: {@code <DIV>} and {@code </DIV>}, or maybe {@code <A>} and
     * {@code </A>}
     *
     * <BR /><BR />Because this method only returns a single integer, and that is the index of the
     * <I>next opening HTML Tag</I> matching the iterator's constraints (but leaves off the
     * closing-tag) this method {@code 'nextIndex()'} may seem out of place.
     * 
     * @return Returns the index of the beginning of the next matched sub-section.
     */
    public int nextIndex() { return nextDotPair().start; }

}