package Torello.HTML.NodeSearch;

import Torello.HTML.NodeSearch.*;
import Torello.HTML.*;
import java.util.Vector;

/**
 * A 'work-book' class included in the Java-HTML JAR-Library, mostly in order to demonstrate the
 * similarities between searching a Java Script DOM-Tree and searching Vectorized-HTML for tags,
 * text and comments.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=JS>
 */
@Torello.JavaDoc.StaticFunctional
public class JS
{
    private JS() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // Element By Id
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM>
     * 
     * @return The integer vector-index of the first HTML {@code TagNode} Element that matches the
     * specified criteria.
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagFind
     */
    public static int findElementById(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagFind.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * @return The first HTML {@code TagNode} Element that matches the specified criteria.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagGet
     */
    public static TagNode getElementById(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagGet.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * 
     * @return The total number of HTML Nodes that were removed from the
     * input-{@code Vector 'html'}
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagRemove
     */
    public static int removeElementById(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagRemove.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * 
     * @return A first {@code 'TagNode'} element that matches the specified input-criteria,
     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
     * {@code Vector}-index from whence it came.
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagPeek
     */
    public static TagNodeIndex peekElementById(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagPeek.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * @return The first HTML {@code TagNode} Element that matches the specified criteria.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagPoll
     */
    public static TagNode pollElementById(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagPoll.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Element By Id, Inclusive
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * 
     * @return Integer vector-index pointers, for a sublist, that match the specified input
     * criteria.
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagFindInclusive
     */
    public static DotPair findElementByIdInclusive(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagFindInclusive.first  (html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * @return The complete sub-list of {@code HTMLNode's} that match the specified input criteria.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagGetInclusive
     */
    public static Vector<HTMLNode> getElementByIdInclusive(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagGetInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * 
     * @return The total number of HTML Nodes that were removed from the
     * input-{@code Vector 'html'}
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagRemoveInclusive
     */
    public static int removeElementByIdInclusive(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagRemoveInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * 
     * @return Instances of {@code 'SubSection'} contain both the html sub-page as a 
     * {@code Vector}, and the matching {@code 'DotPair' Vector} index-pointer from the original
     * {@code Vector} from whence they came.
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagPeekInclusive
     */
    public static SubSection peekElementByIdInclusive(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagPeekInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_ID_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param id <EMBED CLASS='external-html' DATA-FILE-ID=JS_ID_PARAM> 
     * @return The complete sub-list of {@code HTMLNode's} that match the specified input criteria.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_2_EX>
     * @see InnerTagPollInclusive
     */
    public static Vector<HTMLNode> pollElementByIdInclusive(Vector<HTMLNode> html, String id)
    {
        CSSStrException.check(id);
        return InnerTagPollInclusive.first(html, "id", TextComparitor.EQ_CI_TRM, id);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Elements By TagName
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_COUNT_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodeCount
     */
    public static int countElementsByTagName(Vector<HTMLNode> html, String htmlTok)
    { return TagNodeCount.all(html, TC.OpeningTags, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodeFind
     */
    public static int[] findElementsByTagName(Vector<HTMLNode> html, String htmlTok)
    { return TagNodeFind.all(html, TC.OpeningTags, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodeGet
     */
    public static Vector<TagNode> getElementsByTagName(Vector<HTMLNode> html, String htmlTok)
    { return TagNodeGet.all(html, TC.OpeningTags, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * @return The total number of HTML Nodes that were removed from the input-{@code Vector 'html'}
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodeRemove
     */
    public static int removeElementsByTagName(Vector<HTMLNode> html, String htmlTok)
    { return TagNodeRemove.all(html, TC.OpeningTags, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * 
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
     * {@code Vector}-index from whence it came.
     * 
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodePeek
     */
    public static Vector<TagNodeIndex> peekElementsByTagName(Vector<HTMLNode> html, String htmlTok)
    { return TagNodePeek.all(html, TC.OpeningTags, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodePoll
     */
    public static Vector<TagNode> pollElementsByTagName(Vector<HTMLNode> html, String htmlTok)
    { return TagNodePoll.all(html, TC.OpeningTags, htmlTok); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Elements By TagName, Inclusive
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * 
     * @return A "list of lists" where each {@code DotPair} element contains the starting and
     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each match
     * of the input parameter criteria-specifications.
     * 
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodeFindInclusive
     */
    public static Vector<DotPair> findElementsByTagNameInclusive
        (Vector<HTMLNode> html, String htmlTok)
    { return TagNodeFindInclusive.all(html, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * @return A "list of lists" for each opening and closing HTML Element match.
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodeGetInclusive
     */
    public static Vector<Vector<HTMLNode>> getElementsByTagNameInclusive
        (Vector<HTMLNode> html, String htmlTok)
    { return TagNodeGetInclusive.all(html, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * 
     * @return The total number of HTML Nodes that were removed from the
     * input-{@code Vector 'html'}
     * 
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodeRemoveInclusive
     */
    public static int removeElementsByTagNameInclusive(Vector<HTMLNode> html, String htmlTok)
    { return TagNodeRemoveInclusive.all(html, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * 
     * @return A "list of lists" for each opening and closing HTML Element match.  Instances
     * of {@code 'SubSection'} contain both the html sub-page as a {@code Vector}, and the
     * matching {@code 'DotPair' Vector} index-pointer from the original {@code Vector} from
     * whence they came.
     * 
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodePeekInclusive
     */
    public static Vector<SubSection> peekElementsByTagNameInclusive
        (Vector<HTMLNode> html, String htmlTok)
    { return TagNodePeekInclusive.all(html, htmlTok); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_TN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param htmlTok <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_PARAM>
     * @return A "list of lists" for each opening and closing HTML Element match.
     * @throws HTMLTokException <EMBED CLASS='external-html' DATA-FILE-ID=JS_HTML_TOK_EX>
     * @see TagNodePollInclusive
     */
    public static Vector<Vector<HTMLNode>> pollElementsByTagNameInclusive
        (Vector<HTMLNode> html, String htmlTok)
    { return TagNodePollInclusive.all(html, htmlTok); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Elements By Class-Name
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_COUNT_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagCount
     */
    public static int countElementsByClassName(Vector<HTMLNode> html, String className)
    { return InnerTagCount.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagFind
     */
    public static int[] findElementsByClassName(Vector<HTMLNode> html, String className)
    { return InnerTagFind.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagGet
     */
    public static Vector<TagNode> getElementsByClassName(Vector<HTMLNode> html, String className)
    { return InnerTagGet.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * 
     * @return The total number of HTML Nodes that were removed from the
     * input-{@code Vector 'html'}
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagRemove
     */
    public static int removeElementsByClassName(Vector<HTMLNode> html, String className)
    { return InnerTagRemove.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * 
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
     * {@code Vector}-index from whence it came.
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagPeek
     */
    public static Vector<TagNodeIndex> peekElementsByClassName
        (Vector<HTMLNode> html, String className)
    { return InnerTagPeek.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagPoll
     */
    public static Vector<TagNode> pollElementsByClassName(Vector<HTMLNode> html, String className)
    { return InnerTagPoll.all(html, "class", TextComparitor.C, className); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Elements By Class-Name, Inclusive
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * 
     * @return A "list of lists" where each {@code DotPair} element contains the starting and
     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each
     * match of the input parameter criteria-specifications.
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagFindInclusive
     */
    public static Vector<DotPair> findElementsByClassNameInclusive
        (Vector<HTMLNode> html, String className)
    { return InnerTagFindInclusive.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * @return  A "list of lists" for each opening and closing HTML Element match.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagGetInclusive
     */
    public static Vector<Vector<HTMLNode>> getElementsByClassNameInclusive
        (Vector<HTMLNode> html, String className)
    { return InnerTagGetInclusive.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * 
     * @return The total number of HTML Nodes that were removed from the
     * input-{@code Vector 'html'}
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagRemoveInclusive
     */
    public static int removeElementsByClassNameInclusive(Vector<HTMLNode> html, String className)
    { return InnerTagRemoveInclusive.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * 
     * @return  A "list of lists" for each opening and closing HTML Element match.  Instances of
     * "SubSection" contain both the html sub-page as a vector, and the matching {@code DotPair
     * Vector} index-pointer from the original {@code Vector} from whence they came.
     * 
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagPeekInclusive
     */
    public static Vector<SubSection> peekElementsByClassNameInclusive
        (Vector<HTMLNode> html, String className)
    { return InnerTagPeekInclusive.all(html, "class", TextComparitor.C, className); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_CN_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param className <EMBED CLASS='external-html' DATA-FILE-ID=JS_CLASSNAME_PARAM>
     * @return  A "list of lists" for each opening and closing HTML Element match.
     * @throws CSSStrException <EMBED CLASS='external-html' DATA-FILE-ID=JS_CSS_STR_EX>
     * @see InnerTagPollInclusive
     */
    public static Vector<Vector<HTMLNode>> pollElementsByClassNameInclusive
        (Vector<HTMLNode> html, String className)
    { return InnerTagPollInclusive.all(html, "class", TextComparitor.C, className); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Elements By Name
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_COUNT_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * @return The number of {@code 'TagNode'} elements that match the specified input criteria.
     * @see InnerTagCount
     */
    public static int countElementsByName(Vector<HTMLNode> html, String name)
    { return InnerTagCount.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * @return A list of integer vector-index pointers into the input vector parameter 'html.'
     * @see InnerTagFind
     */
    public static int[] findElementsByName(Vector<HTMLNode> html, String name)
    { return InnerTagFind.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
     * @see InnerTagGet
     */
    public static Vector<TagNode> getElementsByName(Vector<HTMLNode> html, String name)
    { return InnerTagGet.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * 
     * @return The total number of HTML Nodes that were removed from the
     * input-{@code Vector 'html'}
     * 
     * @see InnerTagRemove
     */
    public static int removeElementsByName(Vector<HTMLNode> html, String name)
    { return InnerTagRemove.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_SHORT_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * 
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria,
     * along with the {@code Vector}-index as an integer included in the {@code 'TagNodeIndex'}
     * return-type.  {@code class 'TagNodeIndex'} includes both the {@code 'TagNode'}, and the
     * {@code Vector}-index from whence it came.
     * 
     * @see InnerTagPeek
     */
    public static Vector<TagNodeIndex> peekElementsByName(Vector<HTMLNode> html, String name)
    { return InnerTagPeek.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * @return A list of all {@code 'TagNode'} elements that match the specified input-criteria.
     * @see InnerTagPoll
     */
    public static Vector<TagNode> pollElementsByName(Vector<HTMLNode> html, String name)
    { return InnerTagPoll.all(html, "name", TextComparitor.EQ_CI_TRM, name); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Elements By Name, Inclusive
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_FIND_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * 
     * @return A "list of lists" where each {@code DotPair} element contains the starting and
     * ending index-pointers (as integers, wrapped in a {@code 'DotPair'} instance) for each
     * match of the input parameter criteria-specifications.
     * 
     * @see InnerTagFindInclusive
     */
    public static Vector<DotPair> findElementsByNameInclusive(Vector<HTMLNode> html, String name)
    { return InnerTagFindInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_GET_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * @return A "list of lists" for each opening and closing HTML Element match.
     * @see InnerTagGetInclusive
     */
    public static Vector<Vector<HTMLNode>> getElementsByNameInclusive
        (Vector<HTMLNode> html, String name)
    { return InnerTagGetInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_REMOVE_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * 
     * @return The total number of HTML Nodes that were removed from the
     * input-{@code Vector 'html'}
     * 
     * @see InnerTagRemoveInclusive
     */
    public static int removeElementsByNameInclusive(Vector<HTMLNode> html, String name)
    { return InnerTagRemoveInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_PEEK_LONG_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * 
     * @return A "list of lists" for each opening and closing HTML Element match.  Instances
     * of {@code 'SubSection'} contain both the html sub-page as a {@code Vector}, and the
     * matching {@code 'DotPair' Vector} index-pointer from the original {@code Vector} from
     * whence they came.
     * 
     * @see InnerTagPeekInclusive
     */
    public static Vector<SubSection> peekElementsByNameInclusive
        (Vector<HTMLNode> html, String name)
    { return InnerTagPeekInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_ELEM_BY_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_POLL_NOTE>
     * <EMBED CLASS='external-html' DATA-FILE-ID=JS_INCLUSIVE_NOTE>
     *
     * @param html This may be any vectorized-html page, or sub-page.
     * @param name <EMBED CLASS='external-html' DATA-FILE-ID=JS_NAME_PARAM>
     * @return A "list of lists" for each opening and closing HTML Element match.
     * @see InnerTagPollInclusive
     */
    public static Vector<Vector<HTMLNode>> pollElementsByNameInclusive
        (Vector<HTMLNode> html, String name)
    { return InnerTagPollInclusive.all(html, "name", TextComparitor.EQ_CI_TRM, name); }
}