001package Torello.HTML.NodeSearch;
002
003import Torello.HTML.NodeSearch.*;
004import Torello.HTML.*;
005import java.util.Vector;
006
007/**
008 * A 'work-book' class included in the Java-HTML JAR-Library, mostly in order to demonstrate the
009 * similarities between searching a Java Script DOM-Tree and searching Vectorized-HTML for tags,
010 * text and comments.
011 * 
012 * <BR /><BR /><EMBED CLASS="external-html" DATA-FILE-ID=JS>
013 */
014@Torello.HTML.Tools.JavaDoc.StaticFunctional
015public class JS
016{
017    private JS() { }
018
019    // ********************************************************************************
020    // Element By Id
021    // ********************************************************************************
022
023    /**
024     * Java-Script's <B>{@code Element by ID}</B> function retrieves all HTML {@code TagNode}
025     * Elements that have a specified CSS {@code 'ID'} Attribute.
026     *
027     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
028     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
029     * that match the specified criteria.
030     *
031     * @param html This may be any vectorized-html page, or sub-page.
032     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
033     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
034     * {@code 'ID'} Tag. 
035     * @return The integer vector-index of the first HTML {@code TagNode} Element that matches the
036     * specified criteria.
037     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
038     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
039     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
040     * @see InnerTagFind
041     */
042    public static int findElementById(Vector<HTMLNode> html, String id)
043    {
044        CSSStrException.check(id);
045        return InnerTagFind.first(html, "id", TextComparitor.EQ_CI_TRM, id);
046    }
047
048    /**
049     * Java-Script's <B>{@code Element by ID}</B> function retrieves all HTML {@code TagNode}
050     * Elements that have a specified CSS {@code 'ID'} Attribute.
051     *
052     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
053     * that match the specified criteria.
054     *
055     * @param html This may be any vectorized-html page, or sub-page.
056     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
057     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
058     * {@code 'ID'} Tag. 
059     * @return The first HTML {@code TagNode} Element that matches the specified criteria.
060     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
061     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
062     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
063     * @see InnerTagGet
064     */
065    public static TagNode getElementById(Vector<HTMLNode> html, String id)
066    {
067        CSSStrException.check(id);
068        return InnerTagGet.first(html, "id", TextComparitor.EQ_CI_TRM, id);
069    }
070
071    /**
072     * Java-Script's <B>{@code Element by ID}</B> function retrieves all HTML {@code TagNode}
073     * Elements that have a specified CSS {@code 'ID'} Attribute.
074     *
075     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
076     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
077     * informing the user how many nodes were ultimately removed.
078     *
079     * @param html This may be any vectorized-html page, or sub-page.
080     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
081     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
082     * {@code 'ID'} Tag. 
083     * @return The total number of HTML Nodes that were removed from the
084     * input-{@code Vector 'html'}
085     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
086     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
087     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
088     * @see InnerTagRemove
089     */
090    public static int removeElementById(Vector<HTMLNode> html, String id)
091    {
092        CSSStrException.check(id);
093        return InnerTagRemove.first(html, "id", TextComparitor.EQ_CI_TRM, id);
094    }
095
096    /**
097     * Java-Script's <B>Element by ID</B> function retrieves all HTML {@code TagNode} Elements that
098     * have a specified CSS {@code ID} Attribute.
099     *
100     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
101     * along with the {@code Vector}-indices where they were found / identified are returned,
102     * together, as a single data-class {@code Object}-instance {@code 'TagNodeIndex'.}
103     *
104     * @param html This may be any vectorized-html page, or sub-page.
105     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
106     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
107     * {@code 'ID'} Tag. 
108     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
109     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
110     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
111     * {@code Vector}-index from whence it came.
112     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
113     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
114     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
115     * @see InnerTagPeek
116     */
117    public static TagNodeIndex peekElementById(Vector<HTMLNode> html, String id)
118    {
119        CSSStrException.check(id);
120        return InnerTagPeek.first(html, "id", TextComparitor.EQ_CI_TRM, id);
121    }
122
123    /**
124     * Java-Script's <B>Element by ID</B> function retrieves all HTML {@code TagNode} Elements that
125     * have a specified CSS {@code ID} Attribute.
126     *
127     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
128     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
129     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
130     * the invoking method.
131     *
132     * @param html This may be any vectorized-html page, or sub-page.
133     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
134     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
135     * {@code 'ID'} Tag. 
136     * @return The first HTML {@code TagNode} Element that matches the specified criteria.
137     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
138     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
139     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
140     * @see InnerTagPoll
141     */
142    public static TagNode pollElementById(Vector<HTMLNode> html, String id)
143    {
144        CSSStrException.check(id);
145        return InnerTagPoll.first(html, "id", TextComparitor.EQ_CI_TRM, id);
146    }
147
148    // ********************************************************************************
149    // Element By Id, Inclusive
150    // ********************************************************************************
151
152    /**
153     * Java-Script's <B>Element by ID</B> function retrieves all HTML {@code TagNode} Elements that
154     * have a specified CSS {@code ID} Attribute.
155     *
156     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
157     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
158     * that match the specified criteria.
159     *
160     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
161     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
162     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
163     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
164     * result.  This, effectively, means these methods will all return either a complete
165     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
166     * demarcating a sublist.  For instance, an HTML divider-element like
167     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
168     * many {@code HTMLNode's} in this list.
169     *
170     * @param html This may be any vectorized-html page, or sub-page.
171     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
172     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
173     * {@code 'ID'} Tag. 
174     * @return Integer vector-index pointers, for a sublist, that match the specified input
175     * criteria.
176     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
177     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
178     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
179     * @see InnerTagFindInclusive
180     */
181    public static DotPair findElementByIdInclusive(Vector<HTMLNode> html, String id)
182    {
183        CSSStrException.check(id);
184        return InnerTagFindInclusive.first  (html, "id", TextComparitor.EQ_CI_TRM, id);
185    }
186
187    /**
188     * Java-Script's <B>Element by ID</B> function retrieves all HTML {@code TagNode} Elements that
189     * have a specified CSS {@code ID} Attribute.
190     *
191     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
192     * that match the specified criteria.
193     *
194     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
195     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
196     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
197     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
198     * result.  This, effectively, means these methods will all return either a complete
199     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
200     * demarcating a sublist.  For instance, an HTML divider-element like
201     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
202     * many {@code HTMLNode's} in this list.
203     *
204     * @param html This may be any vectorized-html page, or sub-page.
205     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
206     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
207     * {@code 'ID'} Tag. 
208     * @return The complete sub-list of {@code HTMLNode's} that match the specified input criteria.
209     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
210     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
211     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
212     * @see InnerTagGetInclusive
213     */
214    public static Vector<HTMLNode> getElementByIdInclusive(Vector<HTMLNode> html, String id)
215    {
216        CSSStrException.check(id);
217        return InnerTagGetInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
218    }
219
220    /**
221     * Java-Script's <B>Element by ID</B> function retrieves all HTML {@code TagNode} Elements that
222     * have a specified CSS {@code ID} Attribute.
223     *
224     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
225     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
226     * informing the user how many nodes were ultimately removed.
227     *
228     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
229     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
230     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
231     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
232     * result.  This, effectively, means these methods will all return either a complete
233     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
234     * demarcating a sublist.  For instance, an HTML divider-element like
235     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
236     * many {@code HTMLNode's} in this list.
237     *
238     * @param html This may be any vectorized-html page, or sub-page.
239     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
240     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
241     * {@code 'ID'} Tag. 
242     * @return The total number of HTML Nodes that were removed from the
243     * input-{@code Vector 'html'}
244     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
245     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
246     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
247     * @see InnerTagRemoveInclusive
248     */
249    public static int removeElementByIdInclusive(Vector<HTMLNode> html, String id)
250    {
251        CSSStrException.check(id);
252        return InnerTagRemoveInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
253    }
254
255    /**
256     * Java-Script's <B>Element by ID</B> function retrieves all HTML {@code TagNode} Elements that
257     * have a specified CSS {@code ID} Attribute.
258     *
259     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
260     * along with the {@code Vector}-indices where they were found / identified are returned as a
261     * single data-{@code Object} simply named {@code 'SubSection.'}  {@code class SubSection}
262     * and {@code class TagNodeIndex} differ in that instances of {@code class SubSection} contain
263     * an entire sub-list, while instances of {@code class TagNodeIndex} only contain a single
264     * node.  Both have index &amp; node information encapsulated, together.
265     *
266     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
267     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
268     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
269     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
270     * result.  This, effectively, means these methods will all return either a complete
271     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
272     * demarcating a sublist.  For instance, an HTML divider-element like
273     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
274     * many {@code HTMLNode's} in this list.
275     *
276     * @param html This may be any vectorized-html page, or sub-page.
277     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
278     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
279     * {@code 'ID'} Tag. 
280     * @return Instances of {@code 'SubSection'} contain both the html sub-page as a 
281     * {@code Vector}, and the matching {@code 'DotPair' Vector} index-pointer from the original
282     * {@code Vector} from whence they came.
283     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
284     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
285     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
286     * @see InnerTagPeekInclusive
287     */
288    public static SubSection peekElementByIdInclusive(Vector<HTMLNode> html, String id)
289    {
290        CSSStrException.check(id);
291        return InnerTagPeekInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
292    }
293
294    /**
295     * Java-Script's <B>Element by ID</B> function retrieves all HTML {@code TagNode} Elements that
296     * have a specified CSS {@code 'ID'} Attribute.
297     *
298     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
299     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
300     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
301     * the invoking method.
302     *
303     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
304     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
305     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
306     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
307     * result.  This, effectively, means these methods will all return either a complete
308     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
309     * demarcating a sublist.  For instance, an HTML divider-element like
310     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
311     * many {@code HTMLNode's} in this list.
312     *
313     * @param html This may be any vectorized-html page, or sub-page.
314     * @param id This should be a valid HTML {@code 'ID'} Attribute-<B STYLE='color: red;'>Value
315     * </B> (inner-tag <B STYLE='color: red;'>value</B>).  This is also known as a CSS-Style-Sheet
316     * {@code 'ID'} Tag. 
317     * @return The complete sub-list of {@code HTMLNode's} that match the specified input criteria.
318     * @throws CSSStrException  This exception will throw if the {@code String} passed to the
319     * {@code 'id'} parameter is not a valid CSS {@code 'ID'}.  Please review the Exception
320     * {@code class CSSStrException} to see what constitutes a valid CSS {@code 'ID'}.
321     * @see InnerTagPollInclusive
322     */
323    public static Vector<HTMLNode> pollElementByIdInclusive(Vector<HTMLNode> html, String id)
324    {
325        CSSStrException.check(id);
326        return InnerTagPollInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
327    }
328
329    // ********************************************************************************
330    // Elements By TagName
331    // ********************************************************************************
332
333    /**
334     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
335     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
336     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
337     *
338     * <BR /><BR /><B><SPAN STYLE="color: red;">COUNT:</SPAN></B> These operations return a count
339     * on the number of matches of the specified criteria.
340     *
341     * @param html This may be any vectorized-html page, or sub-page.
342     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
343     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
344     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
345     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
346     * HTML Element Name provided is not a valid HTML Element.
347     * @see TagNodeCount
348     */
349    public static int countElementsByTagName(Vector<HTMLNode> html, String htmlTok)
350    { return TagNodeCount.all(html, TC.OpeningTags, htmlTok); }
351
352    /**
353     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
354     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
355     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
356     *
357     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
358     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
359     * that match the specified criteria.
360     *
361     * @param html This may be any vectorized-html page, or sub-page.
362     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
363     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
364     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
365     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
366     * HTML Element Name provided is not a valid HTML Element.
367     * @see TagNodeFind
368     */
369    public static int[] findElementsByTagName(Vector<HTMLNode> html, String htmlTok)
370    { return TagNodeFind.all(html, TC.OpeningTags, htmlTok); }
371
372    /**
373     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
374     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
375     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
376     *
377     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
378     * that match the specified criteria.
379     *
380     * @param html This may be any vectorized-html page, or sub-page.
381     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
382     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
383     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
384     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
385     * HTML Element Name provided is not a valid HTML Element.
386     * @see TagNodeGet
387     */
388    public static Vector<TagNode> getElementsByTagName(Vector<HTMLNode> html, String htmlTok)
389    { return TagNodeGet.all(html, TC.OpeningTags, htmlTok); }
390
391    /**
392     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
393     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
394     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
395     *
396     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
397     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
398     * informing the user how many nodes were ultimately removed.
399     *
400     * @param html This may be any vectorized-html page, or sub-page.
401     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
402     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
403     * @return The total number of HTML Nodes that were removed from the input-{@code Vector 'html'}
404     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
405     * HTML Element Name provided is not a valid HTML Element.
406     * @see TagNodeRemove
407     */
408    public static int removeElementsByTagName(Vector<HTMLNode> html, String htmlTok)
409    { return TagNodeRemove.all(html, TC.OpeningTags, htmlTok); }
410
411    /**
412     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
413     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
414     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
415     *
416     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
417     * along with the {@code Vector}-indices where they were found / identified are returned,
418     * together, as a single data-class {@code Object}-instance {@code 'TagNodeIndex'.}
419     *
420     * @param html This may be any vectorized-html page, or sub-page.
421     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
422     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
423     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
424     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
425     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
426     * {@code Vector}-index from whence it came.
427     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
428     * HTML Element Name provided is not a valid HTML Element.
429     * @see TagNodePeek
430     */
431    public static Vector<TagNodeIndex> peekElementsByTagName(Vector<HTMLNode> html, String htmlTok)
432    { return TagNodePeek.all(html, TC.OpeningTags, htmlTok); }
433
434    /**
435     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
436     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
437     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
438     *
439     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
440     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
441     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
442     * the invoking method.
443     *
444     * @param html This may be any vectorized-html page, or sub-page.
445     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
446     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
447     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
448     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
449     * HTML Element Name provided is not a valid HTML Element.
450     * @see TagNodePoll
451     */
452    public static Vector<TagNode> pollElementsByTagName(Vector<HTMLNode> html, String htmlTok)
453    { return TagNodePoll.all(html, TC.OpeningTags, htmlTok); }
454
455    // ********************************************************************************
456    // Elements By TagName, Inclusive
457    // ********************************************************************************
458
459    /**
460     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
461     * Elements having a certain "HTML Token."  For instance, one could specify all
462     * {@code 'div'} elements, or all HTML anchor {@code '<A HREF=...>'} elements.
463     *
464     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
465     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
466     * that match the specified criteria.
467     *
468     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
469     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
470     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
471     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
472     * result.  This, effectively, means these methods will all return either a complete
473     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
474     * demarcating a sublist.  For instance, an HTML divider-element like
475     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
476     * many {@code HTMLNode's} in this list.
477     *
478     * @param html This may be any vectorized-html page, or sub-page.
479     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
480     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
481     * @return A "list of lists" where each {@code DotPair} element contains the starting and
482     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each match
483     * of the input parameter criteria-specifications.
484     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
485     * HTML Element Name provided is not a valid HTML Element.
486     * @see TagNodeFindInclusive
487     */
488    public static Vector<DotPair> findElementsByTagNameInclusive(Vector<HTMLNode> html, String htmlTok)
489    { return TagNodeFindInclusive.all(html, htmlTok); }
490
491    /**
492     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
493     * Elements having a certain "HTML Token."  For instance, one could specify all
494     * {@code 'div'} elements, or all HTML anchor {@code '<A HREF=...>'} elements.
495     *
496     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
497     * that match the specified criteria.
498     *
499     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
500     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
501     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
502     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
503     * result.  This, effectively, means these methods will all return either a complete
504     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
505     * demarcating a sublist.  For instance, an HTML divider-element like
506     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
507     * many {@code HTMLNode's} in this list.
508     *
509     * @param html This may be any vectorized-html page, or sub-page.
510     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
511     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
512     * @return A "list of lists" for each opening and closing HTML Element match.
513     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
514     * HTML Element Name provided is not a valid HTML Element.
515     * @see TagNodeGetInclusive
516     */
517    public static Vector<Vector<HTMLNode>> getElementsByTagNameInclusive
518        (Vector<HTMLNode> html, String htmlTok)
519    { return TagNodeGetInclusive.all(html, htmlTok); }
520
521    /**
522     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
523     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
524     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
525     *
526     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
527     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
528     * informing the user how many nodes were ultimately removed.
529     *
530     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
531     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
532     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
533     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
534     * result.  This, effectively, means these methods will all return either a complete
535     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
536     * demarcating a sublist.  For instance, an HTML divider-element like
537     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
538     * many {@code HTMLNode's} in this list.
539     *
540     * @param html This may be any vectorized-html page, or sub-page.
541     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
542     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
543     * @return The total number of HTML Nodes that were removed from the
544     * input-{@code Vector 'html'}
545     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
546     * HTML Element Name provided is not a valid HTML Element.
547     * @see TagNodeRemoveInclusive
548     */
549    public static int removeElementsByTagNameInclusive(Vector<HTMLNode> html, String htmlTok)
550    { return TagNodeRemoveInclusive.all(html, htmlTok); }
551
552    /**
553     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode}
554     * Elements having a certain "HTML Token."  For instance, one could specify all {@code 'div'}
555     * elements, or all HTML anchor {@code '<A HREF=...>'} elements.
556     *
557     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
558     * along with the {@code Vector}-indices where they were found / identified are returned as a
559     * single data-{@code Object} simply named {@code 'SubSection.'}  {@code class SubSection}
560     * and {@code class TagNodeIndex} differ in that instances of {@code class SubSection} contain
561     * an entire sub-list, while instances of {@code class TagNodeIndex} only contain a single
562     * node.  Both have index &amp; node information encapsulated, together.
563     *
564     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
565     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
566     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
567     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
568     * result.  This, effectively, means these methods will all return either a complete
569     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
570     * demarcating a sublist.  For instance, an HTML divider-element like
571     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
572     * many {@code HTMLNode's} in this list.
573     *
574     * @param html This may be any vectorized-html page, or sub-page.
575     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
576     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
577     * @return A "list of lists" for each opening and closing HTML Element match.  Instances
578     * of {@code 'SubSection'} contain both the html sub-page as a {@code Vector}, and the
579     * matching {@code 'DotPair' Vector} index-pointer from the original {@code Vector} from
580     * whence they came.
581     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
582     * HTML Element Name provided is not a valid HTML Element.
583     * @see TagNodePeekInclusive
584     */
585    public static Vector<SubSection> peekElementsByTagNameInclusive
586        (Vector<HTMLNode> html, String htmlTok)
587    { return TagNodePeekInclusive.all(html, htmlTok); }
588
589    /**
590     * Java-Script's <B>Elements by TagName</B> function retrieves all HTML {@code TagNode} Elements
591     * having a certain "HTML Token."  For instance, one could specify all {@code 'div'} elements,
592     * or all HTML anchor {@code '<A HREF=...>'} elements.
593     *
594     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
595     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
596     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
597     * the invoking method.
598     *
599     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
600     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
601     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
602     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
603     * result.  This, effectively, means these methods will all return either a complete
604     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
605     * demarcating a sublist.  For instance, an HTML divider-element like
606     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
607     * many {@code HTMLNode's} in this list.
608     *
609     * @param html This may be any vectorized-html page, or sub-page.
610     * @param htmlTok This is an HTML Element Token - also known as "The HTML Element Name."  For
611     * instance: {@code 'DIV', 'SPAN', 'IMG',} etc...
612     * @return A "list of lists" for each opening and closing HTML Element match.
613     * @throws HTMLTokException This exception will be thrown by {@code class ARGCHECK} if the
614     * HTML Element Name provided is not a valid HTML Element.
615     * @see TagNodePollInclusive
616     */
617    public static Vector<Vector<HTMLNode>> pollElementsByTagNameInclusive
618        (Vector<HTMLNode> html, String htmlTok)
619    { return TagNodePollInclusive.all(html, htmlTok); }
620
621    // ********************************************************************************
622    // Elements By Class-Name
623    // ********************************************************************************
624
625    /**
626     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
627     * Elements that match a specified CSS {@code 'CLASS'}.
628     *
629     * <BR /><BR /><B><SPAN STYLE="color: red;">COUNT:</SPAN></B> These operations return a count
630     * on the number of matches of the specified criteria.
631     *
632     * @param html This may be any vectorized-html page, or sub-page.
633     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
634     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
635     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
636     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
637     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
638     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
639     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
640     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
641     * @see InnerTagCount
642     */
643    public static int countElementsByClassName(Vector<HTMLNode> html, String className)
644    { return InnerTagCount.all(html, "class", TextComparitor.C, className); }
645
646    /**
647     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
648     * Elements that match a specified CSS {@code 'CLASS'}.
649     *
650     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
651     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
652     * that match the specified criteria.
653     *
654     * @param html This may be any vectorized-html page, or sub-page.
655     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
656     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
657     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
658     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
659     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
660     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
661     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
662     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
663     * @see InnerTagFind
664     */
665    public static int[] findElementsByClassName(Vector<HTMLNode> html, String className)
666    { return InnerTagFind.all(html, "class", TextComparitor.C, className); }
667
668    /**
669     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
670     * Elements that match a specified CSS {@code 'CLASS'}.
671     *
672     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
673     * that match the specified criteria.
674     *
675     * @param html This may be any vectorized-html page, or sub-page.
676     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
677     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
678     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
679     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
680     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
681     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
682     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
683     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
684     * @see InnerTagGet
685     */
686    public static Vector<TagNode> getElementsByClassName(Vector<HTMLNode> html, String className)
687    { return InnerTagGet.all(html, "class", TextComparitor.C, className); }
688
689    /**
690     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
691     * Elements that match a specified CSS {@code 'CLASS'}.
692     *
693     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
694     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
695     * informing the user how many nodes were ultimately removed.
696     *
697     * @param html This may be any vectorized-html page, or sub-page.
698     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
699     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
700     * @return The total number of HTML Nodes that were removed from the
701     * input-{@code Vector 'html'}
702     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
703     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
704     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
705     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
706     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
707     * @see InnerTagRemove
708     */
709    public static int removeElementsByClassName(Vector<HTMLNode> html, String className)
710    { return InnerTagRemove.all(html, "class", TextComparitor.C, className); }
711
712    /**
713     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
714     * Elements that match a specified CSS {@code 'CLASS'}.
715     *
716     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
717     * along with the {@code Vector}-indices where they were found / identified are returned,
718     * together, as a single data-class {@code Object}-instance {@code 'TagNodeIndex'.}
719     *
720     * @param html This may be any vectorized-html page, or sub-page.
721     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
722     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
723     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
724     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
725     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
726     * {@code Vector}-index from whence it came.
727     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
728     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
729     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
730     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
731     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
732     * @see InnerTagPeek
733     */
734    public static Vector<TagNodeIndex> peekElementsByClassName
735        (Vector<HTMLNode> html, String className)
736    { return InnerTagPeek.all(html, "class", TextComparitor.C, className); }
737
738    /**
739     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
740     * Elements that match a specified CSS {@code 'CLASS'}.
741     *
742     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
743     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
744     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
745     * the invoking method.
746     *
747     * @param html This may be any vectorized-html page, or sub-page.
748     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
749     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
750     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
751     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
752     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
753     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
754     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
755     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
756     * @see InnerTagPoll
757     */
758    public static Vector<TagNode> pollElementsByClassName(Vector<HTMLNode> html, String className)
759    { return InnerTagPoll.all(html, "class", TextComparitor.C, className); }
760
761    // ********************************************************************************
762    // Elements By Class-Name, Inclusive
763    // ********************************************************************************
764
765    /**
766     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
767     * Elements that match a specified CSS {@code 'CLASS'}.
768     *
769     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
770     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
771     * that match the specified criteria.
772     *
773     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
774     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
775     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
776     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
777     * result.  This, effectively, means these methods will all return either a complete
778     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
779     * demarcating a sublist.  For instance, an HTML divider-element like
780     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
781     * many {@code HTMLNode's} in this list.
782     *
783     * @param html This may be any vectorized-html page, or sub-page.
784     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
785     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
786     * @return A "list of lists" where each {@code DotPair} element contains the starting and
787     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each
788     * match of the input parameter criteria-specifications.
789     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
790     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
791     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
792     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
793     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
794     * @see InnerTagFindInclusive
795     */
796    public static Vector<DotPair> findElementsByClassNameInclusive
797        (Vector<HTMLNode> html, String className)
798    { return InnerTagFindInclusive.all(html, "class", TextComparitor.C, className); }
799
800    /**
801     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
802     * Elements that match a specified CSS {@code 'CLASS'}.
803     *
804     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
805     * that match the specified criteria.
806     *
807     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
808     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
809     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
810     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
811     * result.  This, effectively, means these methods will all return either a complete
812     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
813     * demarcating a sublist.  For instance, an HTML divider-element like
814     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
815     * many {@code HTMLNode's} in this list.
816     *
817     * @param html This may be any vectorized-html page, or sub-page.
818     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
819     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
820     * @return  A "list of lists" for each opening and closing HTML Element match.
821     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
822     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
823     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
824     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
825     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
826     * @see InnerTagGetInclusive
827     */
828    public static Vector<Vector<HTMLNode>> getElementsByClassNameInclusive
829        (Vector<HTMLNode> html, String className)
830    { return InnerTagGetInclusive.all(html, "class", TextComparitor.C, className); }
831
832    /**
833     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
834     * Elements that match a specified CSS {@code 'CLASS'}.
835     *
836     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
837     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
838     * informing the user how many nodes were ultimately removed.
839     *
840     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
841     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
842     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
843     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
844     * result.  This, effectively, means these methods will all return either a complete
845     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
846     * demarcating a sublist.  For instance, an HTML divider-element like
847     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
848     * many {@code HTMLNode's} in this list.
849     *
850     * @param html This may be any vectorized-html page, or sub-page.
851     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
852     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
853     * @return The total number of HTML Nodes that were removed from the
854     * input-{@code Vector 'html'}
855     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
856     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
857     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
858     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
859     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
860     * @see InnerTagRemoveInclusive
861     */
862    public static int removeElementsByClassNameInclusive(Vector<HTMLNode> html, String className)
863    { return InnerTagRemoveInclusive.all(html, "class", TextComparitor.C, className); }
864
865    /**
866     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
867     * Elements that match a specified CSS {@code 'CLASS'}.
868     *
869     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
870     * along with the {@code Vector}-indices where they were found / identified are returned as a
871     * single data-{@code Object} simply named {@code 'SubSection.'}  {@code class SubSection}
872     * and {@code class TagNodeIndex} differ in that instances of {@code class SubSection} contain
873     * an entire sub-list, while instances of {@code class TagNodeIndex} only contain a single
874     * node.  Both have index &amp; node information encapsulated, together.
875     *
876     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
877     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
878     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
879     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
880     * result.  This, effectively, means these methods will all return either a complete
881     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
882     * demarcating a sublist.  For instance, an HTML divider-element like
883     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
884     * many {@code HTMLNode's} in this list.
885     *
886     * @param html This may be any vectorized-html page, or sub-page.
887     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
888     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
889     * @return  A "list of lists" for each opening and closing HTML Element match.  Instances of
890     * "SubSection" contain both the html sub-page as a vector, and the matching {@code DotPair
891     * Vector} index-pointer from the original {@code Vector} from whence they came.
892     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
893     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
894     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
895     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
896     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
897     * @see InnerTagPeekInclusive
898     */
899    public static Vector<SubSection> peekElementsByClassNameInclusive
900        (Vector<HTMLNode> html, String className)
901    { return InnerTagPeekInclusive.all(html, "class", TextComparitor.C, className); }
902
903    /**
904     * Java-Script's <B>Elements by Class Name</B> function retrieves all HTML {@code TagNode}
905     * Elements that match a specified CSS {@code 'CLASS'}.
906     *
907     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
908     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
909     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
910     * the invoking method.
911     *
912     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
913     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
914     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
915     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
916     * result.  This, effectively, means these methods will all return either a complete
917     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
918     * demarcating a sublist.  For instance, an HTML divider-element like
919     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
920     * many {@code HTMLNode's} in this list.
921     *
922     * @param html This may be any vectorized-html page, or sub-page.
923     * @param className  This should be a valid HTML CSS {@code 'CLASS'} 
924     * Attribute-<B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).
925     * @return  A "list of lists" for each opening and closing HTML Element match.
926     * @throws CSSStrException Whenever the {@code TextComparitor's} for CSS {@code 'Classes'} are
927     * used, passed or invoked, the {@code 'class-name'}, or list of {@code class-name's} 
928     * (as {@code String's}) provided to the {@code TextComparitor} will be checked for validity
929     * according to CSS naming conventions.  If parameter {@code 'className'} does not meet the
930     * strict requirements for CSS {@code Class-Names}, this exception will throw immediately.
931     * @see InnerTagPollInclusive
932     */
933    public static Vector<Vector<HTMLNode>> pollElementsByClassNameInclusive
934        (Vector<HTMLNode> html, String className)
935    { return InnerTagPollInclusive.all(html, "class", TextComparitor.C, className); }
936
937
938    // ********************************************************************************
939    // Elements By Name
940    // ********************************************************************************
941
942    /**
943     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
944     * {@code 'NAME'} attribute matches the specified {@code String name} parameter.
945     *
946     * <BR /><BR /><B><SPAN STYLE="color: red;">COUNT:</SPAN></B> These operations return a count
947     * on the number of matches of the specified criteria.
948     *
949     * @param html This may be any vectorized-html page, or sub-page.
950     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
951     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
952     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
953     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
954     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
955     * @see InnerTagCount
956     */
957    public static int countElementsByName(Vector<HTMLNode> html, String name)
958    { return InnerTagCount.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
959
960    /**
961     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
962     * {@code 'NAME'} attribute matches the specified {@code String name} parameter.
963     *
964     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
965     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
966     * that match the specified criteria.
967     *
968     * @param html This may be any vectorized-html page, or sub-page.
969     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
970     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
971     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
972     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
973     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
974     * @see InnerTagFind
975     */
976    public static int[] findElementsByName(Vector<HTMLNode> html, String name)
977    { return InnerTagFind.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
978
979    /**
980     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
981     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
982     *
983     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
984     * that match the specified criteria.
985     *
986     * @param html This may be any vectorized-html page, or sub-page.
987     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
988     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
989     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
990     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
991     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
992     * @see InnerTagGet
993     */
994    public static Vector<TagNode> getElementsByName(Vector<HTMLNode> html, String name)
995    { return InnerTagGet.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
996
997    /**
998     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
999     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1000     *
1001     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
1002     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
1003     * informing the user how many nodes were ultimately removed.
1004     *
1005     * @param html This may be any vectorized-html page, or sub-page.
1006     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1007     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1008     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1009     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1010     * @return The total number of HTML Nodes that were removed from the
1011     * input-{@code Vector 'html'}
1012     * @see InnerTagRemove
1013     */
1014    public static int removeElementsByName(Vector<HTMLNode> html, String name)
1015    { return InnerTagRemove.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1016
1017    /**
1018     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
1019     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1020     *
1021     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
1022     * along with the {@code Vector}-indices where they were found / identified are returned,
1023     * together, as a single data-class {@code Object}-instance {@code 'TagNodeIndex'.}
1024     *
1025     * @param html This may be any vectorized-html page, or sub-page.
1026     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1027     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1028     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1029     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1030     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
1031     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
1032     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
1033     * {@code Vector}-index from whence it came.
1034     * @see InnerTagPeek
1035     */
1036    public static Vector<TagNodeIndex> peekElementsByName(Vector<HTMLNode> html, String name)
1037    { return InnerTagPeek.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1038
1039    /**
1040     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
1041     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1042     *
1043     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
1044     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
1045     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
1046     * the invoking method.
1047     *
1048     * @param html This may be any vectorized-html page, or sub-page.
1049     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1050     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1051     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1052     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1053     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
1054     * @see InnerTagPoll
1055     */
1056    public static Vector<TagNode> pollElementsByName(Vector<HTMLNode> html, String name)
1057    { return InnerTagPoll.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1058
1059    // ********************************************************************************
1060    // Elements By Name, Inclusive
1061    // ********************************************************************************
1062
1063    /**
1064     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
1065     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1066     *
1067     * <BR /><BR /><B><SPAN STYLE="color: red;">FIND:</SPAN></B> These operations return the
1068     * integer {@code Vector}-indices which point to nodes in the original html-{@code Vector}
1069     * that match the specified criteria.
1070     *
1071     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
1072     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
1073     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
1074     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
1075     * result.  This, effectively, means these methods will all return either a complete
1076     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
1077     * demarcating a sublist.  For instance, an HTML divider-element like
1078     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
1079     * many {@code HTMLNode's} in this list.
1080     *
1081     * @param html This may be any vectorized-html page, or sub-page.
1082     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1083     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1084     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1085     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1086     * @return A "list of lists" where each {@code DotPair} element contains the starting and
1087     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each
1088     * match of the input parameter criteria-specifications.
1089     * @see InnerTagFindInclusive
1090     */
1091    public static Vector<DotPair> findElementsByNameInclusive(Vector<HTMLNode> html, String name)
1092    { return InnerTagFindInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1093
1094    /**
1095     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
1096     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1097     *
1098     * <BR /><BR /><B><SPAN STYLE="color: red;">GET:</SPAN></B> These operations return the nodes
1099     * that match the specified criteria.
1100     *
1101     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
1102     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
1103     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
1104     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
1105     * result.  This, effectively, means these methods will all return either a complete
1106     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
1107     * demarcating a sublist.  For instance, an HTML divider-element like
1108     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
1109     * many {@code HTMLNode's} in this list.
1110     *
1111     * @param html This may be any vectorized-html page, or sub-page.
1112     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1113     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1114     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1115     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1116     * @return A "list of lists" for each opening and closing HTML Element match.
1117     * @see InnerTagGetInclusive
1118     */
1119    public static Vector<Vector<HTMLNode>> getElementsByNameInclusive
1120        (Vector<HTMLNode> html, String name)
1121    { return InnerTagGetInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1122
1123    /**
1124     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
1125     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1126     *
1127     * <BR /><BR /><B><SPAN STYLE="color: red;">REMOVE:</SPAN></B> These operations remove the
1128     * nodes that match the specified criteria, and then, also, return an integer {@code 'count'} -
1129     * informing the user how many nodes were ultimately removed.
1130     *
1131     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
1132     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
1133     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
1134     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
1135     * result.  This, effectively, means these methods will all return either a complete
1136     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
1137     * demarcating a sublist.  For instance, an HTML divider-element like
1138     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
1139     * many {@code HTMLNode's} in this list.
1140     *
1141     * @param html This may be any vectorized-html page, or sub-page.
1142     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1143     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1144     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1145     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1146     * @return The total number of HTML Nodes that were removed from the
1147     * input-{@code Vector 'html'}
1148     * @see InnerTagRemoveInclusive
1149     */
1150    public static int removeElementsByNameInclusive(Vector<HTMLNode> html, String name)
1151    { return InnerTagRemoveInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1152
1153    /**
1154     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
1155     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1156     *
1157     * <BR /><BR /><B><SPAN STYLE="color: red;">PEEK:</SPAN></B> The elements / nodes themselves,
1158     * along with the {@code Vector}-indices where they were found / identified are returned as a
1159     * single data-{@code Object} simply named {@code 'SubSection.'}  {@code class SubSection}
1160     * and {@code class TagNodeIndex} differ in that instances of {@code class SubSection} contain
1161     * an entire sub-list, while instances of {@code class TagNodeIndex} only contain a single
1162     * node.  Both have index &amp; node information encapsulated, together.
1163     *
1164     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
1165     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
1166     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
1167     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
1168     * result.  This, effectively, means these methods will all return either a complete
1169     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
1170     * demarcating a sublist.  For instance, an HTML divider-element like
1171     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
1172     * many {@code HTMLNode's} in this list.
1173     *
1174     * @param html This may be any vectorized-html page, or sub-page.
1175     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1176     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1177     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1178     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1179     * @return A "list of lists" for each opening and closing HTML Element match.  Instances
1180     * of {@code 'SubSection'} contain both the html sub-page as a {@code Vector}, and the
1181     * matching {@code 'DotPair' Vector} index-pointer from the original {@code Vector} from
1182     * whence they came.
1183     * @see InnerTagPeekInclusive
1184     */
1185    public static Vector<SubSection> peekElementsByNameInclusive(Vector<HTMLNode> html, String name)
1186    { return InnerTagPeekInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1187
1188    /**
1189     * Java-Script's <B>Elements by Name</B> function retrieves all HTML Elements whose
1190     * {@code 'NAME'} attribute matches the specified {@code String name} parameter. 
1191     *
1192     * <BR /><BR /><B><SPAN STYLE="color: red;">POLL:</SPAN></B> These operations simply behave
1193     * like a combination of the <B>{@code 'GET'}</B> operation and the {@code 'REMOVE'} operation.
1194     * {@code HTMLNode's} are removed, and afterwards, these removed nodes are returned back to the
1195     * the invoking method.
1196     *
1197     * <BR /><BR /><B><SPAN STYLE="color: red;">INCLUSIVE:</SPAN></B> In this html search library,
1198     * all the word <B>'inclusive'</B> means, is that when an opening {@code TagNode} is found by
1199     * an 'inclusive method', before returning that node, the <I>matching, and closing pair</I> of
1200     * that {@code TagNode}, along with all {@code HTMLNode's} in-between, are included in the
1201     * result.  This, effectively, means these methods will all return either a complete
1202     * vectorized-html sublist, or a {@code 'DotPair'} (instead) start-index and end-index
1203     * demarcating a sublist.  For instance, an HTML divider-element like
1204     * {@code <DIV class=someClass ...> ... </DIV>} as an 'inclusive return-value' might have
1205     * many {@code HTMLNode's} in this list.
1206     *
1207     * @param html This may be any vectorized-html page, or sub-page.
1208     * @param name  This should be a valid HTML {@code 'NAME'} Attribute-
1209     * <B STYLE='color: red;'>Value</B> (inner-tag <B STYLE='color: red;'>value</B>).  This a
1210     * "pre-HTML-5" used tag, that has been largely deprecated, and subsequently replaced by the
1211     * {@code 'ID'} and {@code 'CLASS'} CSS-Attributes.
1212     * @return A "list of lists" for each opening and closing HTML Element match.
1213     * @see InnerTagPollInclusive
1214     */
1215    public static Vector<Vector<HTMLNode>> pollElementsByNameInclusive
1216        (Vector<HTMLNode> html, String name)
1217    { return InnerTagPollInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
1218}