package Torello.HTML;

import java.util.Vector;
import java.util.Properties;

import Torello.HTML.HelperPackages.Attributes.*;

import Torello.Java.LV;
import Torello.Java.StrFilter;
import Torello.Java.Additional.Ret2;
import Torello.Java.Function.IntTFunction;

/**
 * Utilities for getting, setting and removing attributes from the {@link TagNode} elements in a
 * Web-Page {@code Vector}.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=ATTRIBUTES>
 * @see AUM
 */
@Torello.JavaDoc.StaticFunctional
public class Attributes
{
    private Attributes() { }


    // ***************************************************************************************
    // ***************************************************************************************
    // Update Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * <BR />Passes: Simple Update Lambda that <B>always</B> assigns {@code 'itValue'} to the
     * Attribute
     * <BR />Iterates: The entire {@code html}-page,  Passes {@code 0, -1} to {@code sPos, ePos}
     * @see #update(Vector, AUM, int, int, String, IntTFunction, SD)
     */
    public static int[] update
        (Vector<? super TagNode>    html,
        AUM                         mode,
        String                      innerTag,
        String                      itValue,
        SD                          quote)
    {
        return Update.update
            (html, mode, 0, -1, innerTag, (int index, TagNode tn) -> itValue, quote);
    }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * <BR />Passes: Simple Update Lambda that <B>always</B> assigns {@code 'itValue'} to the
     * Attribute
     * <BR />Iterates: The {@code html}-page from {@code dp.start} (inclusive) to {@code dp.end}
     * (also inclusive)
     * @see #update(Vector, AUM, int, int, String, IntTFunction, SD)
     */
    public static int[] update(
            Vector<? super TagNode> html,
            AUM                     mode,
            DotPair                 dp,
            String                  innerTag,
            String                  itValue,
            SD                      quote
        )
    {
        return Update.update(
            html, mode, dp.start, dp.end + 1, innerTag,
            (int index, TagNode tn) -> itValue, quote
        );
    }

    /**
     * Convenience Method.
     * <BR />Receives: An Attribute-Update Lambda-Function {@code 'newITValueStrGetter'}
     * <BR />Iterates: The entire {@code html}-page,  Passes {@code 0, -1} to {@code sPos, ePos}
     * @see #update(Vector, AUM, int, int, String, IntTFunction, SD)
     */
    public static int[] update(
            Vector<? super TagNode>         html,
            AUM                             mode,
            String                          innerTag,
            IntTFunction<TagNode, String>   newITValueStrGetter,
            SD                              quote
        )
    { return Update.update(html, mode, 0, -1, innerTag, newITValueStrGetter, quote); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * <BR />And-Receives: An Attribute-Update Lambda-Function {@code 'newITValueStrGetter'}
     * <BR />Iterates: The {@code html}-page from {@code dp.start} (inclusive) to {@code dp.end}
     * (also inclusive)
     * @see #update(Vector, AUM, int, int, String, IntTFunction, SD)
     */
    public static int[] update(
            Vector<? super TagNode>         html,
            AUM                             mode,
            DotPair                         dp,
            String                          innerTag,
            IntTFunction<TagNode, String>   newITValueStrGetter,
            SD                              quote
        )
    {
        return Update.update
            (html, mode, dp.start, dp.end + 1, innerTag, newITValueStrGetter, quote);
    }

    /**
     * Convenience Method.
     * <BR />Receives: HTML-{@code Vector} starting &amp; ending indices
     * ({@code sPos} and {@code ePos}).
     * <BR />Passes: Simple Update Lambda that <B>always</B> assigns {@code 'itValue'} to the
     * Attribute
     * <BR />Iterates: The {@code html}-page from {@code sPos} (inclusive) to {@code ePos}
     * (exclusive)
     * @see #update(Vector, AUM, int, int, String, IntTFunction, SD)
     */
    public static int[] update(
            Vector<? super TagNode> html,
            AUM                     mode,
            int                     sPos,
            int                     ePos,
            String                  innerTag, 
            String                  itValue,
            SD                      quote
        )
    {
        return Update.update
            (html, mode, sPos, ePos, innerTag, (int index, TagNode tn) -> itValue, quote);
    }

    /**
     * Will update any HTML {@code TagNode's} present in the vector-parameter {@code 'html'}
     * according to passed <B>{@code AUM}</B> mode and the {@code 'innerTag'} parameter.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=update DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * 
     * @param html <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param mode <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_MODE_PARAM>
     * @param sPos <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * 
     * @param innerTag This is the <B STYLE="color: red;">name</B> of the HTML attribute that needs
     * to be changed, added, or removed.
     * 
     * @param newITValueStrGetter <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_NEW_ITSTR_FUNC>
     * 
     * @param quote <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_QUOTE_PARAM>
     * 
     * @return This method shall return an integer-{@code array} index-list whose values identify
     * which HTML {@code Vector} Elements were changed as a result of this method invocation.
     *
     * <BR /><BR /><B>NOTE:</B> One minor subtlety, there could be cases where a new HTML Element
     * {@code 'TagNode'} reference / object were instantiated or 'created,' even though the actual
     * {@code String} that comprised the {@code HTMLNode} itself were identical to the original 
     * {@code HTMLNode.str String}.  In the {@code 'AUM'} enumerated-type, when {@code AUM.Set}
     * is invoked, the original {@code String} data for an attribute is always clobbered, even in
     * cases where an identical version of the {@code String} is replaced or substituted.
     * 
     * @throws QuotesException              <EMBED CLASS='external-html' DATA-FILE-ID=QEX>
     * @throws InnerTagKeyException         <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws IndexOutOfBoundsException    <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * 
     * @see AUM#update(TagNode, String, String, SD)
     * @see LV
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     */
    public static int[] update(
            Vector<? super TagNode>         html,
            AUM                             mode,
            int                             sPos,
            int                             ePos,
            String                          innerTag,
            IntTFunction<TagNode, String>   newITValueStrGetter,
            SD                              quote
        )
    { return Update.update(html, mode, sPos, ePos, innerTag, newITValueStrGetter, quote); }

    /**
     * Convenience Method.
     * <BR />Receives: An {@code int[]}-Array which identifes which nodes in the {@code Vector} to
     * update.
     * <BR />Passes: Simple Update Lambda that <B>always</B> assigns {@code 'itValue'} to the
     * Attribute
     * <BR />Iterates: All {@code Vector}-indices pointed to by the values in {@code 'posArr'}
     * @see #update(Vector, AUM, int, int, String, IntTFunction, SD)
     */
    public static int[] update(
            Vector<? super TagNode> html,
            AUM                     mode,
            int[]                   posArr, 
            String                  innerTag, 
            String                  itValue,
            SD                      quote
        )
    {
        return Update.update
            (html, mode, posArr, innerTag, (int index, TagNode tn) -> itValue, quote);
    }

    /**
     * Will update any HTML {@code TagNode's} present in the vector-parameter {@code 'html'}
     * according to a passed <B>{@code 'AUM'}</B> mode and the {@code 'innerTag'} parameter.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=update DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param mode      <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_MODE_PARAM>
     * @param posArr    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POS_ARR_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_UPDATE_AUM_EXAMPLE>
     *
     * @param innerTag This is the <B STYLE="color: red;">name</B> of the HMTL attribute that needs
     * to be changed, added, or removed.
     * 
     * @param newITValueStrGetter <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_NEW_ITSTR_FUNC>
     * 
     * @param quote <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_QUOTE_PARAM>
     * 
     * @return This method shall return an integer-{@code array} index-list whose values identify
     * which HTML {@code Vector} Elements were changed as a result of this method invokation.
     *
     * <BR /><BR /><B>NOTE:</B> One minor subtlety, there could be cases where a new HTML Element
     * {@code 'TagNode'} reference / object were instantiated or 'created,' even though the actual
     * {@code String} that comprised the {@code HTMLNode} itself were identical to the original 
     * {@code HTMLNode.str String}.  In the {@code 'AUM'} enumerated-type, when {@code AUM.Set}
     * is invoked, the original {@code String} data for an attribute is always clobbered, even in
     * cases where an identical version of the {@code String} is replaced or substituted.
     * 
     * @throws QuotesException          <EMBED CLASS='external-html' DATA-FILE-ID=QEX>
     * @throws InnerTagKeyException     <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws TagNodeExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * 
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * 
     * @see AUM#update(TagNode, String, String, SD)
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     */
    public static int[] update(
            Vector<? super TagNode>         html,
            AUM                             mode,
            int[]                           posArr, 
            String                          innerTag,
            IntTFunction<TagNode, String>   newITValueStrGetter,
            SD                              quote
        )
    { return Update.update(html, mode, posArr, innerTag, newITValueStrGetter, quote); }


    // ***************************************************************************************
    // ***************************************************************************************
    // Remove All Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * @see #removeAll(Vector, int, int)
     */
    public static int[] removeAll(Vector<? super TagNode> html)
    { return RemoveAll.removeAll(html, 0, -1); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * @see #removeAll(Vector, int, int)
     */
    public static int[] removeAll(Vector<? super TagNode> html, DotPair dp)
    { return RemoveAll.removeAll(html, dp.start, dp.end + 1); }

    /**
     * The purpose of this method is to remove all attributes / Inner-Tag
     * <B STYLE="color: red;">key-value pairs</B> from each and every non-{@code 'TextNode'} and
     * non-{@code 'CommentNode'} HTML Element found on the vectorized-html page parameter
     * {@code 'html'}. The removal process is limited to the range specified by method-parameters
     * {@code sPos, ePos.} 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Attribute Removal Specifics:</B>
     * 
     * <BR />This method will remove each and every {@code class=... id=... src=... alt=...}
     * {@code href=... onclick=... etc...} attribute from all {@link TagNode}-instances whose 
     * {@code Vector}-index location inside {@code 'html'} falls between {@code 'sPos'} and
     * {@code 'ePos'}.
     * 
     * <BR /><BR />When this method exists, all {@link TagNode} instances inside {@code 'html'}
     * that fall within the specified sub-range will be attribute-free.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_REMOVEALL_EXAMPLE1>
     * 
     * @param html <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param sPos <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * 
     * @return An integer array of {@code 'Vector'}-index positions / locations for each and every
     * HTML {@code 'TagNode'} whose attributes have been removed.
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * 
     * @see TagNode#removeAllAV
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see LV
     */
    public static int[] removeAll
        (Vector<? super TagNode> html, int sPos, int ePos)
    { return RemoveAll.removeAll(html, sPos, ePos); }

    /**
     * The purpose of this method is to remove all attributes / Inner-Tag
     * <B STYLE="color: red;">key-value pairs</B> from each and every non-{@code 'TextNode'} and
     * non-{@code 'CommentNode'} HTML Element found on the vectorized-html page parameter
     * {@code 'html'}. The removal process is limited to the only removing attributes from elements
     * pointed to by the contents of passed-parameter {@code 'posArr'}
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Attribute Removal Specifics:</B>
     * 
     * <BR />This method will remove each and every {@code class=... id=... src=... alt=...}
     * {@code href=... onclick=... etc...} attribute from all {@link TagNode}-instances whose 
     * {@code Vector}-index location within {@code 'html'} are indices among those listed by
     * the index-list {@code int[]}-Array {@code 'posArr'}.
     * 
     * <BR /><BR />When this method exits, all {@link TagNode} instances inside {@code 'html'}
     * specified by {@code 'posArr'} will be attribute-free.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param posArr    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POS_ARR_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_REMOVEALL_EXAMPLE2>
     * 
     * @return An integer array of {@code 'Vector'}-index positions / locations for each and every
     * HTML {@code 'TagNode'} whose attributes have been removed.
     * 
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * 
     * @throws TagNodeExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * 
     * @see TagNode#removeAllAV()
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     */
    public static int[] removeAll(Vector<? super TagNode> html, int[] posArr)
    { return RemoveAll.removeAll(html, posArr); }


    // ***************************************************************************************
    // ***************************************************************************************
    // Remove Data-Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * @see #removeData(Vector, int, int)
     */
    public static int[] removeData(Vector<? super TagNode> html)
    { return RemoveData.removeData(html, 0, -1); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * @see #removeData(Vector, int, int)
     */
    public static int[] removeData(Vector<? super TagNode> html, DotPair dp)
    { return RemoveData.removeData(html, dp.start, dp.end + 1); }

    /**
     * The purpose of this method is to remove all HTML <B STYLE="color: red;">data</B>-attribute
     * <B STYLE="color: red;">key-value</B> pairs from {@code 'TagNode'} Elements contained inside
     * parameter {@code 'html'}.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * 
     * @param html  <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param sPos  <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos  <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * @return      <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *              <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_DATA_ATTR_RET_NOTE>
     *              <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POSARR_SHORT_EXPL>
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * 
     * @see TagNode#removeDataAttributes()
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see LV
     */
    public static int[] removeData(Vector<? super TagNode> html, int sPos, int ePos)
    { return RemoveData.removeData(html, sPos, ePos); }

    /**
     * The purpose of this method is to remove all HTML <B STYLE="color: red;">data</B>-attribute
     * <B STYLE="color: red;">key-value</B> pairs from {@code 'TagNode'} Elements contained inside
     * parameter {@code 'html'}.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param posArr    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POS_ARR_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_DATA_ATTR_EXAMPLE>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_DATA_ATTR_RET_NOTE>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POSARR_SHORT_EXPL>
     * 
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * 
     * @throws TagNodeExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * 
     * @see TagNode#removeDataAttributes()
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     */
    public static int[] removeData(Vector<? super TagNode> html, int[] posArr)
    { return RemoveData.removeData(html, posArr); }


    // ***************************************************************************************
    // ***************************************************************************************
    // Remove Specified Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * @see #remove(Vector, int, int, String[])
     */
    public static int[] remove(Vector<? super TagNode> html, String... innerTags)
    { return Remove.remove(html, 0, -1, innerTags); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * @see #remove(Vector, int, int, String[])
     */
    public static int[] remove(Vector<? super TagNode> html, DotPair dp, String... innerTags)
    { return Remove.remove(html, dp.start, dp.end + 1, innerTags); }

    /**
     * This will remove all copies of the attributes whose <B STYLE="color: red;">names</B> are
     * listed among the by {@code String[]} array parameter {@code 'innerTags'} from the
     * vectorized-html web-page parameter {@code 'html'}.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param innerTags <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INNERTAGS_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_SE_RESTRICT_REM>
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_VARARGS_S_RET_NOTE>
     * 
     * @throws InnerTagKeyException         <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws IndexOutOfBoundsException    <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * @throws IllegalArgumentException     If parameter {@code 'innerTags'} has zero elements.
     * 
     * @see TagNode#removeAttributes(String[])
     * @see LV
     * @see TagNode#hasOR(boolean, String[])
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see InnerTagKeyException#check(String[])
     */
    public static int[] remove
        (Vector<? super TagNode> html, int sPos, int ePos, String... innerTags)
    { return Remove.remove(html, sPos, ePos, innerTags); }

    /**
     * This will remove all copies of the attributes whose <B STYLE="color: red;">names</B> are
     * listed among the by {@code String[]} array parameter {@code 'innerTags'} from the
     * vectorized-html web-page parameter {@code 'html'}.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param innerTags <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INNERTAGS_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_PA_RESTRICT_REM>
     * @param posArr    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POS_ARR_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_VARARGS_S_EXAMPLE>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_VARARGS_S_RET_NOTE>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POSARR_SHORT_EXPL>
     * 
     * @throws InnerTagKeyException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * 
     * @throws TagNodeExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * @throws IllegalArgumentException If parameter {@code 'innerTags'} has zero elements.
     * 
     * @see TagNode#removeAttributes(String[])
     * @see TagNode#hasOR(boolean, String[])
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see InnerTagKeyException#check(String[])
     */
    public static int[] remove(Vector<? super TagNode> html, int[] posArr, String... innerTags)
    { return Remove.remove(html, posArr, innerTags); }


    // ***************************************************************************************
    // ***************************************************************************************
    // Retrieve Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * @see #retrieve(Vector, int, int, String)
     */
    public static Ret2<int[], String[]> retrieve(Vector<? super TagNode> html, String attribute)
    { return Retrieve.retrieve(html, 0, -1, attribute); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * @see #retrieve(Vector, int, int, String)
     */
    public static Ret2<int[], String[]> retrieve
        (Vector<? super TagNode> html, DotPair dp, String attribute)
    { return Retrieve.retrieve(html, dp.start, dp.end + 1, attribute); }

    /**
     * The purpose of this method is to retrieve the <B STYLE="color: red">value</B> of each
     * attribute in each {@code TagNode} in an HTML {@code Vector} (or sub-{@code Vector}) that
     * contained such an attribute.  
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=retrieval DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVEC>
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * @param attribute <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_ATTR_RETR_SE_PARAM>
     * 
     * @throws InnerTagKeyException If the attribute <B STYLE="color: red;">name</B> passed to
     * this parameter does not contain the <B STYLE="color: red;">name</B> of a valid HTML5
     * attribute, then this exception shall throw.
     * 
     * @throws IndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_RETRIEVE_SE_RET>
     * 
     * @see TagNode#AV(String)
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see InnerTagKeyException#check(String[])
     * @see LV
     */
    public static Ret2<int[], String[]> retrieve
            (Vector<? super TagNode> html, int sPos, int ePos, String attribute)
    { return Retrieve.retrieve(html, sPos, ePos, attribute); }

    /**
     * This shall visit each {@link TagNode} indicated by the {@code int[]}-Array parameter
     * {@code 'posArr'}), and then query those {@code TagNode's} for the
     * Attribute-<B STYLE="color: red;">value</B> of the attribute named by
     * {@code String}-Parameter {@code 'attribute'}
     * 
     * <BR /><BR />The <B STYLE="color: red;">value</B> of each of these attributes will be
     * recorded to a parallel {@code String}-array and returned.  This {@code String[]} array shall
     * be parallel to the input {@code Vector}-index {@code 'posArr'} parameter.
     * 
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=retrieval DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * 
     * @param html <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVEC>
     * 
     * @param posArr This shall be a list of {@code Vector}-indices that contain opening
     * {@code TagNode} elements.  The <B STYLE="color: red;">value</B> of the attribute provided by
     * parameter {@code 'attribute'} will be returned in a parallel {@code String[]} array for each
     * {@code TagNode} identified by {@code 'posArr'}.
     * 
     * @param attribute <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_ATTR_RETR_PA_PARAM>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_RETRIEVE_PA_RET>
     * 
     * @throws InnerTagKeyException If the {@code String} provided to parameter {@code 'attribute'}
     * is not a valid HTML-5 attribute-<B STYLE="color: red;">name</B>, then this exception shall
     * thow.
     * 
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * 
     * @throws TagNodeExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * 
     * @see InnerTagKeyException#check(String[])
     * @see TagNode#AV(String)
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     */
    public static String[] retrieve(Vector<? super TagNode> html, int[] posArr, String attribute)
    { return Retrieve.retrieve(html, posArr, attribute); }


    // ***************************************************************************************
    // ***************************************************************************************
    // Functional Interface Filter
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Lambda-target for creating attribute-filters.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTRIBUTES_FILTER>
     */
    @FunctionalInterface
    public interface Filter
    { 
        /**
         * This receives the contents of a {@code 'TagNode'} - after the html-tag and the
         * inner-tags have been extracted.  This method is intended to be used to selectively
         * remove specific inner-tags / attributes that the programmer would like to see removed.
         * 
         * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=FUNC_INTER_METH>
         * 
         * @param htmlTag When this method is implemented by a class, or by a lambda-expression,
         * the user will receive a copy of a TagNode's {@code TagNode.tok} field through this
         * parameter.  The class or lambda-expression which implements method
         * {@code 'filter(...)'} may use the {@code String} that is passed via the
         * {@code 'htmlTag'} parameter to, possibly - if needed, help decide which attributes to
         * remove from the {@code java.util.Properties} parameter {@code 'attributes'}
         *
         * @param attributes When this method, {@code 'filter(...)'}, is implemented by a class or
         * a lambda-expression, he or she is tasked with eliminating any attributes in this 
         * {@code Properties} class that he wishes to filter.
         * 
         * <BR /><BR /><B><SPAN STYLE="color: red;">NOTE:</B></SPAN> The 
         * <B STYLE="color: red;">key-value</B> pairs of this {@code java.util.Properties} method
         * are generated by calling
         * {@link TagNode#allAV(boolean, boolean)}.  The <B STYLE="color: red;">values</B>
         * returned by that method will all have their original quotation-marks included in the 
         * <CODE><B STYLE="color: red;">'value'</B> String</CODE>.
         * 
         * <BR /><BR /><B>ALSO:</B> This class is intended to function as a filter, and should be
         * used to remove property <B STYLE="color: red;">key-value</B> pairs from the attributes
         * parameter received here.  However, there is nothing stopping the programmer from
         * modifying the contents by adding properties, or even changing the
         * <B STYLE="color: red;">values</B> of the properties.
         *
         * @return This method must return a boolean indicating whether or not the attributes
         * parameter has been changed in any way.  If {@code FALSE} were returned, but the class or
         * lambda-expression which implements this method has modified the attributes 
         * {@code Properties} instance, the changes that were made would be lost, and the 
         * vectorized-html page that contained the {@code TagNode} wouldn't be updated with the
         * new {@code TagNode}.
         *
         * @see TagNode#allAV(boolean, boolean)
         * @see TagNode#tok
         */
        public boolean filter(String htmlTag, Properties attributes);
    }


    // ***************************************************************************************
    // ***************************************************************************************
    // Use BiPredicate to Filter Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * @see #update(Vector, int, int, Filter)
     */
    public static int[] update(Vector<? super TagNode> html, Filter f)
    { return UpdateWithFilter.update(html, 0, -1, f); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * @see #update(Vector, int, int, Filter)
     */
    public static int[] update(Vector<? super TagNode> html, DotPair dp, Filter f)
    { return UpdateWithFilter.update(html, dp.start, dp.end + 1, f); }

    /**
     * Modifies the contents of each instance of a {@code 'TC.OpeningTags'} element found in the
     * input {@code Vector}.  The type of update that's performed is defined by the parameter
     * {@code Filter 'f'}. Each time a {@code TagNode} found in the input vectorized-html web-page,
     * or html sub-list, is changed or modified the, original {@code TagNode} will be removed and
     * replaced by a new, modified {@code TagNode} instance.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=filtering DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * 
     * @param html  <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param f     <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_FILTER_PARAM>
     *              <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_SE_RESTRICT_REM>
     * @param sPos  <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos  <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * 
     * @throws InnerTagKeyException         <EMBED CLASS='external-html' DATA-FILE-ID=ITKEX>
     * @throws IndexOutOfBoundsException    <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * @throws QuotesException              <EMBED CLASS='external-html' DATA-FILE-ID=QEX> 
     * 
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_FILTER_RET_NOTE>
     * 
     * @see TagNode#allAV(boolean, boolean)
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see LV
     */
    public static int[] update(Vector<? super TagNode> html, int sPos, int ePos, Filter f)
    { return UpdateWithFilter.update(html, sPos, ePos, f); }

    /**
     * Filters the contents of each instance of a {@code 'TC.OpeningTags'} element in the input
     * {@code Vector}.  The type of filter performed is defined by the parameter
     * {@code Filter 'f'}. Each time a {@code TagNode} in the input vectorized-html web-page, or
     * html sub-list, is changed or modified the original {@code TagNode} will be removed and
     * replaced by a new, updated or modified {@code TagNode} instance.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=filtering DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_FILTER_EXAMPLE>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param f         <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_FILTER_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_PA_RESTRICT_REM>
     * @param posArr    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POS_ARR_PARAM>
     *
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * 
     * @throws InnerTagKeyException     <EMBED CLASS='external-html' DATA-FILE-ID=ITKEX>
     * @throws QuotesException          <EMBED CLASS='external-html' DATA-FILE-ID=QEX>
     * @throws TagNodeExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * 
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_FILTER_RET_NOTE>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POSARR_SHORT_EXPL>
     * 
     * @see TagNode#allAV(boolean, boolean)
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     */
    public static int[] update(Vector<? super TagNode> html, int[] posArr, Filter f)
    { return UpdateWithFilter.update(html, posArr, f); }


    // ***************************************************************************************
    // ***************************************************************************************
    // Use Attribute White-Lists to Filter Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * @see #filter(Vector, int, int, String[])
     */
    public static int[] filter(Vector<? super TagNode> html, String... innerTagWhiteList)
    { return WhiteListFilter.filter(html, 0, -1, innerTagWhiteList); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * @see #filter(Vector, int, int, String[])
     */
    public static int[] filter
        (Vector<? super TagNode> html, DotPair dp, String... innerTagWhiteList)
    { return WhiteListFilter.filter(html, dp.start, dp.end + 1, innerTagWhiteList); }

    /**
     * Filters the contents of each instance of a {@code 'TC.OpeningTags'} element in the input
     * {@code Vector} using an attribute {@code 'white-list'}.  All input-{@code Vector TagNode's}
     * that have attributes whose <B STYLE="color: red;">names</B> are not members of the inner-tag
     * {@code white-list} will be removed, and a new {@code TagNode} whose only attributes are
     * members of the innerTag {@code white-list} will replace the old {@code TagNode}.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * 
     * @param html              <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param innerTagWhiteList <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_WHITE_LIST_PARAM>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_SE_RESTRICT_REM>
     * @param sPos              <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos              <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * 
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_WHITE_L_RET_NOTE>
     * 
     * @see TagNode#allAN(boolean, boolean)
     * @see TagNode#isTagNode()
     * @see TagNode#removeAttributes(String[])
     * @see TagNode#isClosing
     * @see LV
     */
    public static int[] filter
        (Vector<? super TagNode> html, int sPos, int ePos, String... innerTagWhiteList)
    { return WhiteListFilter.filter(html, sPos, ePos, innerTagWhiteList); }

    /**
     * Filters the contents of each instance of a {@code 'TC.OpeningTags'} element in the input
     * {@code Vector} using an attribute {@code 'white-list'}.  All input-{@code Vector TagNode's}
     * that have attributes whose <B STYLE="color: red;">names</B> are not members of the inner-tag
     * {@code white-list} will be removed, and a new {@code TagNode} whose only attributes are
     * members of the innerTag {@code white-list} will replace the old {@code TagNode}.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=removal DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * 
     * @param html              <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param innerTagWhiteList <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_WHITE_LIST_PARAM>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_PA_RESTRICT_REM>
     * @param posArr            <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POS_ARR_PARAM>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_WHITE_LIST_EXAMPLE>
     * 
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * @throws TagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * 
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_WHITE_L_RET_NOTE>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POSARR_SHORT_EXPL>
     * 
     * @see TagNode#allAN(boolean, boolean)
     * @see TagNode#removeAttributes(String[])
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     */
    public static int[] filter
        (Vector<? super TagNode> html, int[] posArr, String... innerTagWhiteList)
    { return WhiteListFilter.filter(html, posArr, innerTagWhiteList); }


    // ***************************************************************************************
    // ***************************************************************************************
    // Use class StrFilter to Filter Attributes
    // ***************************************************************************************
    // ***************************************************************************************


    /**
     * Convenience Method.
     * @see #filter(Vector, int, int, StrFilter)
     */
    public static int[] filter(Vector<? super TagNode> html, StrFilter filter)
    { return UsingStrFilter.filter(html, 0, -1, filter); }

    /**
     * Convenience Method.
     * <BR />Receives: {@code DotPair}
     * @see #filter(Vector, int, int, StrFilter)
     */
    public static int[] filter(Vector<? super TagNode> html, DotPair dp, StrFilter filter)
    { return UsingStrFilter.filter(html, dp.start, dp.end + 1, filter); }

    /**
     * Filters the contents of each instance of a {@code 'TC.OpeningTags'} element in the input 
     * {@code Vector} using a {@link StrFilter}.  All input-{@code Vector TagNode's} which have
     * attributes will have the list of attribute-<B STYLE="color: red;">names</B> tested against
     * the provided {@code StrFilter.test(attribute)} predicate.
     *
     * <BR /><BR />If any attribute whose <B STYLE="color: red;">name</B> fails the
     * {@code Predicate} test, then that attribute will be removed.  After testing all of a
     * {@code TagNode's} inner-tags, if any of those attributes did fail the
     * {@code StrFilter.test(...)} method, a new {@code TagNode} will be constructed leaving those
     * out.  Finally, the old {@code TagNode} will be removed from input HTML {@code Vector}, and
     * replaced with the new one.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=filtering DATA-FILE-ID=ATTR_RESTRICT_SE_POS>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param filter    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_STR_FILTER_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_SE_RESTRICT_REM>
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSVEC>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSVEC>
     * 
     * @throws IndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=VIOOBEX>
     * 
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_STR_FILT_RET_NOTE>
     * 
     * @see TagNode#allAN()
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see TagNode#removeAttributes(String[])
     * @see LV
     */
    public static int[] filter
        (Vector<? super TagNode> html, int sPos, int ePos, StrFilter filter)
    { return UsingStrFilter.filter(html, sPos, ePos, filter); }

    /**
     * Filters the contents of each instance of a {@code 'TC.OpeningTags'} element in the input 
     * {@code Vector} using a {@link StrFilter}.  All input-{@code Vector TagNode's} which have
     * attributes will have the list of attribute-<B STYLE="color: red;">names</B> tested against
     * the provided {@code StrFilter.test(attribute)} predicate.
     *
     * <BR /><BR />If any attribute whose <B STYLE="color: red;">name</B> fails the
     * {@code Predicate} test, then that attribute will be removed.  After testing all of a
     * {@code TagNode's} inner-tags, if any of those attributes did fail the
     * {@code StrFilter.test(...)} method, a new {@code TagNode} will be constructed leaving those
     * out.  Finally, the old {@code TagNode} will be removed from input HTML {@code Vector}, and
     * replaced with the new one.
     *
     * <EMBED CLASS='external-html' DATA-PROC_TYPE=filtering DATA-FILE-ID=ATTR_RESTRICT_POSARR>
     * 
     * @param html      <EMBED CLASS='external-html' DATA-FILE-ID=HTMLVECSUP>
     * @param filter    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_STR_FILTER_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_PA_RESTRICT_REM>
     * @param posArr    <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POS_ARR_PARAM>
     *                  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_STR_FILT_EXAMPLE>
     * 
     * @throws ArrayIndexOutOfBoundsException
     * <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_AIOOB_EX>
     * @throws OpeningTagNodeExpectedException
     * <EMBED CLASS='external-html' DATA-FILE-ID=OPEN_TNE_EX>
     * 
     * @throws TagNodeExpectedException <EMBED CLASS='external-html' DATA-FILE-ID=TNE_EX>
     * 
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_INT_ARR_RET>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_STR_FILT_RET_NOTE>
     *          <EMBED CLASS='external-html' DATA-FILE-ID=ATTR_POSARR_SHORT_EXPL>
     * 
     * @see TagNode#allAN()
     * @see TagNode#isTagNode()
     * @see TagNode#isClosing
     * @see TagNode#removeAttributes(String[])
     */
    public static int[] filter(Vector<? super TagNode> html, int[] posArr, StrFilter filter)
    { return UsingStrFilter.filter(html, posArr, filter); }

}