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 * <EMBED CLASS='external-html' DATA-FILE-ID=JS>
013 */
014@Torello.JavaDoc.StaticFunctional
015public class JS
016{
017    private JS() { }
018
019
020    // ********************************************************************************************
021    // ********************************************************************************************
022    // Element By Id
023    // ********************************************************************************************
024    // ********************************************************************************************
025
026
027    /**
028     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
029     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
030     *
031     * @param html This may be any vectorized-html page, or sub-page.
032     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM>
033     * 
034     * @return The integer vector-index of the first HTML {@code TagNode} Element that matches the
035     * specified criteria.
036     * 
037     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
038     * @see InnerTagFind
039     */
040    public static int findElementById(Vector<HTMLNode> html, String id)
041    {
042        CSSStrException.check(id);
043        return InnerTagFind.first(html, "id", TextComparitor.EQ_CI_TRM, id);
044    }
045
046    /**
047     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
048     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
049     *
050     * @param html This may be any vectorized-html page, or sub-page.
051     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
052     * @return The first HTML {@code TagNode} Element that matches the specified criteria.
053     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
054     * @see InnerTagGet
055     */
056    public static TagNode getElementById(Vector<HTMLNode> html, String id)
057    {
058        CSSStrException.check(id);
059        return InnerTagGet.first(html, "id", TextComparitor.EQ_CI_TRM, id);
060    }
061
062    /**
063     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
064     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
065     *
066     * @param html This may be any vectorized-html page, or sub-page.
067     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
068     * 
069     * @return The total number of HTML Nodes that were removed from the
070     * input-{@code Vector 'html'}
071     * 
072     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
073     * @see InnerTagRemove
074     */
075    public static int removeElementById(Vector<HTMLNode> html, String id)
076    {
077        CSSStrException.check(id);
078        return InnerTagRemove.first(html, "id", TextComparitor.EQ_CI_TRM, id);
079    }
080
081    /**
082     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
083     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
084     *
085     * @param html This may be any vectorized-html page, or sub-page.
086     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
087     * 
088     * @return A first {@code 'TagNode'} element that matches the specified input-criteria,
089     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
090     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
091     * {@code Vector}-index from whence it came.
092     * 
093     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
094     * @see InnerTagPeek
095     */
096    public static TagNodeIndex peekElementById(Vector<HTMLNode> html, String id)
097    {
098        CSSStrException.check(id);
099        return InnerTagPeek.first(html, "id", TextComparitor.EQ_CI_TRM, id);
100    }
101
102    /**
103     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
104     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
105     *
106     * @param html This may be any vectorized-html page, or sub-page.
107     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
108     * @return The first HTML {@code TagNode} Element that matches the specified criteria.
109     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
110     * @see InnerTagPoll
111     */
112    public static TagNode pollElementById(Vector<HTMLNode> html, String id)
113    {
114        CSSStrException.check(id);
115        return InnerTagPoll.first(html, "id", TextComparitor.EQ_CI_TRM, id);
116    }
117
118
119    // ********************************************************************************************
120    // ********************************************************************************************
121    // Element By Id, Inclusive
122    // ********************************************************************************************
123    // ********************************************************************************************
124
125
126    /**
127     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
128     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
129     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
130     *
131     * @param html This may be any vectorized-html page, or sub-page.
132     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
133     * 
134     * @return Integer vector-index pointers, for a sublist, that match the specified input
135     * criteria.
136     * 
137     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
138     * @see InnerTagFindInclusive
139     */
140    public static DotPair findElementByIdInclusive(Vector<HTMLNode> html, String id)
141    {
142        CSSStrException.check(id);
143        return InnerTagFindInclusive.first  (html, "id", TextComparitor.EQ_CI_TRM, id);
144    }
145
146    /**
147     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
148     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
149     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
150     *
151     * @param html This may be any vectorized-html page, or sub-page.
152     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
153     * @return The complete sub-list of {@code HTMLNode's} that match the specified input criteria.
154     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
155     * @see InnerTagGetInclusive
156     */
157    public static Vector<HTMLNode> getElementByIdInclusive(Vector<HTMLNode> html, String id)
158    {
159        CSSStrException.check(id);
160        return InnerTagGetInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
161    }
162
163    /**
164     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
165     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
166     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
167     *
168     * @param html This may be any vectorized-html page, or sub-page.
169     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
170     * 
171     * @return The total number of HTML Nodes that were removed from the
172     * input-{@code Vector 'html'}
173     * 
174     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
175     * @see InnerTagRemoveInclusive
176     */
177    public static int removeElementByIdInclusive(Vector<HTMLNode> html, String id)
178    {
179        CSSStrException.check(id);
180        return InnerTagRemoveInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
181    }
182
183    /**
184     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
185     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
186     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
187     *
188     * @param html This may be any vectorized-html page, or sub-page.
189     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
190     * 
191     * @return Instances of {@code 'SubSection'} contain both the html sub-page as a 
192     * {@code Vector}, and the matching {@code 'DotPair' Vector} index-pointer from the original
193     * {@code Vector} from whence they came.
194     * 
195     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
196     * @see InnerTagPeekInclusive
197     */
198    public static SubSection peekElementByIdInclusive(Vector<HTMLNode> html, String id)
199    {
200        CSSStrException.check(id);
201        return InnerTagPeekInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
202    }
203
204    /**
205     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
206     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
207     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
208     *
209     * @param html This may be any vectorized-html page, or sub-page.
210     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
211     * @return The complete sub-list of {@code HTMLNode's} that match the specified input criteria.
212     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
213     * @see InnerTagPollInclusive
214     */
215    public static Vector<HTMLNode> pollElementByIdInclusive(Vector<HTMLNode> html, String id)
216    {
217        CSSStrException.check(id);
218        return InnerTagPollInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
219    }
220
221
222    // ********************************************************************************************
223    // ********************************************************************************************
224    // Elements By TagName
225    // ********************************************************************************************
226    // ********************************************************************************************
227
228
229    /**
230     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
231     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_COUNT_NOTE>
232     *
233     * @param html This may be any vectorized-html page, or sub-page.
234     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
235     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
236     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
237     * @see TagNodeCount
238     */
239    public static int countElementsByTagName(Vector<HTMLNode> html, String htmlTok)
240    { return TagNodeCount.all(html, TC.OpeningTags, htmlTok); }
241
242    /**
243     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
244     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
245     *
246     * @param html This may be any vectorized-html page, or sub-page.
247     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
248     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
249     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
250     * @see TagNodeFind
251     */
252    public static int[] findElementsByTagName(Vector<HTMLNode> html, String htmlTok)
253    { return TagNodeFind.all(html, TC.OpeningTags, htmlTok); }
254
255    /**
256     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
257     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
258     *
259     * @param html This may be any vectorized-html page, or sub-page.
260     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
261     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
262     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
263     * @see TagNodeGet
264     */
265    public static Vector<TagNode> getElementsByTagName(Vector<HTMLNode> html, String htmlTok)
266    { return TagNodeGet.all(html, TC.OpeningTags, htmlTok); }
267
268    /**
269     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
270     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
271     *
272     * @param html This may be any vectorized-html page, or sub-page.
273     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
274     * @return The total number of HTML Nodes that were removed from the input-{@code Vector 'html'}
275     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
276     * @see TagNodeRemove
277     */
278    public static int removeElementsByTagName(Vector<HTMLNode> html, String htmlTok)
279    { return TagNodeRemove.all(html, TC.OpeningTags, htmlTok); }
280
281    /**
282     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
283     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
284     *
285     * @param html This may be any vectorized-html page, or sub-page.
286     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
287     * 
288     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
289     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
290     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
291     * {@code Vector}-index from whence it came.
292     * 
293     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
294     * @see TagNodePeek
295     */
296    public static Vector<TagNodeIndex> peekElementsByTagName(Vector<HTMLNode> html, String htmlTok)
297    { return TagNodePeek.all(html, TC.OpeningTags, htmlTok); }
298
299    /**
300     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
301     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
302     *
303     * @param html This may be any vectorized-html page, or sub-page.
304     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
305     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
306     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
307     * @see TagNodePoll
308     */
309    public static Vector<TagNode> pollElementsByTagName(Vector<HTMLNode> html, String htmlTok)
310    { return TagNodePoll.all(html, TC.OpeningTags, htmlTok); }
311
312
313    // ********************************************************************************************
314    // ********************************************************************************************
315    // Elements By TagName, Inclusive
316    // ********************************************************************************************
317    // ********************************************************************************************
318
319
320    /**
321     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
322     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
323     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
324     *
325     * @param html This may be any vectorized-html page, or sub-page.
326     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
327     * 
328     * @return A "list of lists" where each {@code DotPair} element contains the starting and
329     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each match
330     * of the input parameter criteria-specifications.
331     * 
332     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
333     * @see TagNodeFindInclusive
334     */
335    public static Vector<DotPair> findElementsByTagNameInclusive
336        (Vector<HTMLNode> html, String htmlTok)
337    { return TagNodeFindInclusive.all(html, htmlTok); }
338
339    /**
340     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
341     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
342     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
343     *
344     * @param html This may be any vectorized-html page, or sub-page.
345     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
346     * @return A "list of lists" for each opening and closing HTML Element match.
347     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
348     * @see TagNodeGetInclusive
349     */
350    public static Vector<Vector<HTMLNode>> getElementsByTagNameInclusive
351        (Vector<HTMLNode> html, String htmlTok)
352    { return TagNodeGetInclusive.all(html, htmlTok); }
353
354    /**
355     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
356     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
357     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
358     *
359     * @param html This may be any vectorized-html page, or sub-page.
360     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
361     * 
362     * @return The total number of HTML Nodes that were removed from the
363     * input-{@code Vector 'html'}
364     * 
365     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
366     * @see TagNodeRemoveInclusive
367     */
368    public static int removeElementsByTagNameInclusive(Vector<HTMLNode> html, String htmlTok)
369    { return TagNodeRemoveInclusive.all(html, htmlTok); }
370
371    /**
372     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
373     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
374     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
375     *
376     * @param html This may be any vectorized-html page, or sub-page.
377     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
378     * 
379     * @return A "list of lists" for each opening and closing HTML Element match.  Instances
380     * of {@code 'SubSection'} contain both the html sub-page as a {@code Vector}, and the
381     * matching {@code 'DotPair' Vector} index-pointer from the original {@code Vector} from
382     * whence they came.
383     * 
384     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
385     * @see TagNodePeekInclusive
386     */
387    public static Vector<SubSection> peekElementsByTagNameInclusive
388        (Vector<HTMLNode> html, String htmlTok)
389    { return TagNodePeekInclusive.all(html, htmlTok); }
390
391    /**
392     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
393     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
394     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
395     *
396     * @param html This may be any vectorized-html page, or sub-page.
397     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
398     * @return A "list of lists" for each opening and closing HTML Element match.
399     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
400     * @see TagNodePollInclusive
401     */
402    public static Vector<Vector<HTMLNode>> pollElementsByTagNameInclusive
403        (Vector<HTMLNode> html, String htmlTok)
404    { return TagNodePollInclusive.all(html, htmlTok); }
405
406
407    // ********************************************************************************************
408    // ********************************************************************************************
409    // Elements By Class-Name
410    // ********************************************************************************************
411    // ********************************************************************************************
412
413
414    /**
415     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
416     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_COUNT_NOTE>
417     *
418     * @param html This may be any vectorized-html page, or sub-page.
419     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
420     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
421     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
422     * @see InnerTagCount
423     */
424    public static int countElementsByClassName(Vector<HTMLNode> html, String className)
425    { return InnerTagCount.all(html, "class", TextComparitor.C, className); }
426
427    /**
428     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
429     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
430     *
431     * @param html This may be any vectorized-html page, or sub-page.
432     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
433     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
434     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
435     * @see InnerTagFind
436     */
437    public static int[] findElementsByClassName(Vector<HTMLNode> html, String className)
438    { return InnerTagFind.all(html, "class", TextComparitor.C, className); }
439
440    /**
441     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
442     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
443     *
444     * @param html This may be any vectorized-html page, or sub-page.
445     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
446     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
447     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
448     * @see InnerTagGet
449     */
450    public static Vector<TagNode> getElementsByClassName(Vector<HTMLNode> html, String className)
451    { return InnerTagGet.all(html, "class", TextComparitor.C, className); }
452
453    /**
454     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
455     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
456     *
457     * @param html This may be any vectorized-html page, or sub-page.
458     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
459     * 
460     * @return The total number of HTML Nodes that were removed from the
461     * input-{@code Vector 'html'}
462     * 
463     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
464     * @see InnerTagRemove
465     */
466    public static int removeElementsByClassName(Vector<HTMLNode> html, String className)
467    { return InnerTagRemove.all(html, "class", TextComparitor.C, className); }
468
469    /**
470     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
471     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
472     *
473     * @param html This may be any vectorized-html page, or sub-page.
474     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
475     * 
476     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
477     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
478     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
479     * {@code Vector}-index from whence it came.
480     * 
481     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
482     * @see InnerTagPeek
483     */
484    public static Vector<TagNodeIndex> peekElementsByClassName
485        (Vector<HTMLNode> html, String className)
486    { return InnerTagPeek.all(html, "class", TextComparitor.C, className); }
487
488    /**
489     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
490     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
491     *
492     * @param html This may be any vectorized-html page, or sub-page.
493     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
494     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
495     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
496     * @see InnerTagPoll
497     */
498    public static Vector<TagNode> pollElementsByClassName(Vector<HTMLNode> html, String className)
499    { return InnerTagPoll.all(html, "class", TextComparitor.C, className); }
500
501
502    // ********************************************************************************************
503    // ********************************************************************************************
504    // Elements By Class-Name, Inclusive
505    // ********************************************************************************************
506    // ********************************************************************************************
507
508
509    /**
510     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
511     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
512     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
513     *
514     * @param html This may be any vectorized-html page, or sub-page.
515     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
516     * 
517     * @return A "list of lists" where each {@code DotPair} element contains the starting and
518     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each
519     * match of the input parameter criteria-specifications.
520     * 
521     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
522     * @see InnerTagFindInclusive
523     */
524    public static Vector<DotPair> findElementsByClassNameInclusive
525        (Vector<HTMLNode> html, String className)
526    { return InnerTagFindInclusive.all(html, "class", TextComparitor.C, className); }
527
528    /**
529     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
530     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
531     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
532     *
533     * @param html This may be any vectorized-html page, or sub-page.
534     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
535     * @return  A "list of lists" for each opening and closing HTML Element match.
536     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
537     * @see InnerTagGetInclusive
538     */
539    public static Vector<Vector<HTMLNode>> getElementsByClassNameInclusive
540        (Vector<HTMLNode> html, String className)
541    { return InnerTagGetInclusive.all(html, "class", TextComparitor.C, className); }
542
543    /**
544     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
545     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
546     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
547     *
548     * @param html This may be any vectorized-html page, or sub-page.
549     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
550     * 
551     * @return The total number of HTML Nodes that were removed from the
552     * input-{@code Vector 'html'}
553     * 
554     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
555     * @see InnerTagRemoveInclusive
556     */
557    public static int removeElementsByClassNameInclusive(Vector<HTMLNode> html, String className)
558    { return InnerTagRemoveInclusive.all(html, "class", TextComparitor.C, className); }
559
560    /**
561     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
562     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
563     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
564     *
565     * @param html This may be any vectorized-html page, or sub-page.
566     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
567     * 
568     * @return  A "list of lists" for each opening and closing HTML Element match.  Instances of
569     * "SubSection" contain both the html sub-page as a vector, and the matching {@code DotPair
570     * Vector} index-pointer from the original {@code Vector} from whence they came.
571     * 
572     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
573     * @see InnerTagPeekInclusive
574     */
575    public static Vector<SubSection> peekElementsByClassNameInclusive
576        (Vector<HTMLNode> html, String className)
577    { return InnerTagPeekInclusive.all(html, "class", TextComparitor.C, className); }
578
579    /**
580     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
581     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
582     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
583     *
584     * @param html This may be any vectorized-html page, or sub-page.
585     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
586     * @return  A "list of lists" for each opening and closing HTML Element match.
587     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
588     * @see InnerTagPollInclusive
589     */
590    public static Vector<Vector<HTMLNode>> pollElementsByClassNameInclusive
591        (Vector<HTMLNode> html, String className)
592    { return InnerTagPollInclusive.all(html, "class", TextComparitor.C, className); }
593
594
595    // ********************************************************************************************
596    // ********************************************************************************************
597    // Elements By Name
598    // ********************************************************************************************
599    // ********************************************************************************************
600
601
602    /**
603     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
604     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_COUNT_NOTE>
605     *
606     * @param html This may be any vectorized-html page, or sub-page.
607     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
608     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
609     * @see InnerTagCount
610     */
611    public static int countElementsByName(Vector<HTMLNode> html, String name)
612    { return InnerTagCount.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
613
614    /**
615     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
616     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
617     *
618     * @param html This may be any vectorized-html page, or sub-page.
619     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
620     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
621     * @see InnerTagFind
622     */
623    public static int[] findElementsByName(Vector<HTMLNode> html, String name)
624    { return InnerTagFind.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
625
626    /**
627     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
628     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
629     *
630     * @param html This may be any vectorized-html page, or sub-page.
631     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
632     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
633     * @see InnerTagGet
634     */
635    public static Vector<TagNode> getElementsByName(Vector<HTMLNode> html, String name)
636    { return InnerTagGet.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
637
638    /**
639     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
640     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
641     *
642     * @param html This may be any vectorized-html page, or sub-page.
643     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
644     * 
645     * @return The total number of HTML Nodes that were removed from the
646     * input-{@code Vector 'html'}
647     * 
648     * @see InnerTagRemove
649     */
650    public static int removeElementsByName(Vector<HTMLNode> html, String name)
651    { return InnerTagRemove.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
652
653    /**
654     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
655     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
656     *
657     * @param html This may be any vectorized-html page, or sub-page.
658     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
659     * 
660     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
661     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
662     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
663     * {@code Vector}-index from whence it came.
664     * 
665     * @see InnerTagPeek
666     */
667    public static Vector<TagNodeIndex> peekElementsByName(Vector<HTMLNode> html, String name)
668    { return InnerTagPeek.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
669
670    /**
671     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
672     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
673     *
674     * @param html This may be any vectorized-html page, or sub-page.
675     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
676     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
677     * @see InnerTagPoll
678     */
679    public static Vector<TagNode> pollElementsByName(Vector<HTMLNode> html, String name)
680    { return InnerTagPoll.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
681
682
683    // ********************************************************************************************
684    // ********************************************************************************************
685    // Elements By Name, Inclusive
686    // ********************************************************************************************
687    // ********************************************************************************************
688
689
690    /**
691     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
692     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
693     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
694     *
695     * @param html This may be any vectorized-html page, or sub-page.
696     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
697     * 
698     * @return A "list of lists" where each {@code DotPair} element contains the starting and
699     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each
700     * match of the input parameter criteria-specifications.
701     * 
702     * @see InnerTagFindInclusive
703     */
704    public static Vector<DotPair> findElementsByNameInclusive(Vector<HTMLNode> html, String name)
705    { return InnerTagFindInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
706
707    /**
708     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
709     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
710     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
711     *
712     * @param html This may be any vectorized-html page, or sub-page.
713     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
714     * @return A "list of lists" for each opening and closing HTML Element match.
715     * @see InnerTagGetInclusive
716     */
717    public static Vector<Vector<HTMLNode>> getElementsByNameInclusive
718        (Vector<HTMLNode> html, String name)
719    { return InnerTagGetInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
720
721    /**
722     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
723     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
724     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
725     *
726     * @param html This may be any vectorized-html page, or sub-page.
727     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
728     * 
729     * @return The total number of HTML Nodes that were removed from the
730     * input-{@code Vector 'html'}
731     * 
732     * @see InnerTagRemoveInclusive
733     */
734    public static int removeElementsByNameInclusive(Vector<HTMLNode> html, String name)
735    { return InnerTagRemoveInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
736
737    /**
738     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
739     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
740     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
741     *
742     * @param html This may be any vectorized-html page, or sub-page.
743     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
744     * 
745     * @return A "list of lists" for each opening and closing HTML Element match.  Instances
746     * of {@code 'SubSection'} contain both the html sub-page as a {@code Vector}, and the
747     * matching {@code 'DotPair' Vector} index-pointer from the original {@code Vector} from
748     * whence they came.
749     * 
750     * @see InnerTagPeekInclusive
751     */
752    public static Vector<SubSection> peekElementsByNameInclusive
753        (Vector<HTMLNode> html, String name)
754    { return InnerTagPeekInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
755
756    /**
757     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
758     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
759     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
760     *
761     * @param html This may be any vectorized-html page, or sub-page.
762     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
763     * @return A "list of lists" for each opening and closing HTML Element match.
764     * @see InnerTagPollInclusive
765     */
766    public static Vector<Vector<HTMLNode>> pollElementsByNameInclusive
767        (Vector<HTMLNode> html, String name)
768    { return InnerTagPollInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
769}