package Torello.JavaDoc;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;
import Torello.Java.*;
import Torello.Java.Additional.*;

import static Torello.Java.C.*;

import Torello.JDUInternal.GeneralPurpose.Messager;

import Torello.JDUInternal.ParseHTML.SignatureParse;
import Torello.JDUInternal.ParseJavaSource.JavaSourceCodeFile;

import java.util.*;
import java.util.stream.*;

import java.util.function.Function;

/**
 * This class stores the HTML for a Summary-Table - which is the table at the top of a Java Doc
 * Page listing all of one type of entities present in the CIET/Type.  
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=PROG_MOD_HTML>
 * <EMBED CLASS='external-html' DATA-FILE-ID=SUMM_TABLE_HTML>
 * 
 * @param <ENTITY> This will take one of six type's: {@link Method}, {@link Constructor},
 * {@link Field}, {@link EnumConstant}, {@link AnnotationElem} or {@link NestedType}.   The HTML
 * contained by this class correspond directly to the HTML contained by a Summary-Table of one of
 * section of one of these Entities / Members.
 */
@JDHeaderBackgroundImg(EmbedTagFileID="REFLECTION_HTML_CLASS")
public class SummaryTableHTML<ENTITY extends Declaration>
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // Main CommentNode Marker's for Finding Summaries (Formerly of class "Summaries.java")
    // ********************************************************************************************
    // ********************************************************************************************


    // Copied from the now-legacy class Summaries
    private static final String[] MARKERS =
    {
        // public static final String JAVADOC_CONSTRUCTOR_SUMMARY_MARKER =
        "==== CONSTRUCTOR SUMMARY ====",

        // private static final String JAVADOC_FIELD_SUMMARY_MARKER =
        "==== FIELD SUMMARY ====",

        // public static final String JAVADOC_METHOD_SUMMARY_MARKER =
        "==== METHOD SUMMARY ====",

        // public static final String JAVADOC_NESTED_CLASS_SUMMARY_MARKER =
        "==== NESTED CLASS SUMMARY ====",

        // public static final String JAVADOC_ENUM_CONST_SUMMARY_MARKER =
        "==== ENUM CONSTANT SUMMARY ====",

        // public static final String JAVADOC_OPTIONAL_ANNOTATION_ELEMENT_SUMMARY_MARKER =
        "==== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY ====",

        // public static final String JAVADOC_REQUIRED_ANNOTATION_ELEMENT_SUMMARY_MARKER =
        "==== ANNOTATION TYPE REQUIRED MEMBER SUMMARY ===="
    };


    // ********************************************************************************************
    // ********************************************************************************************
    // The Main Fields of this Class.
    // ********************************************************************************************
    // ********************************************************************************************


    /** Indicates what type of Summary-Table this is (Methods, Fields, Constructor's, etc). */
    public final Entity tableType;

    /** The opening {@code <TABLE>} tag, for a Summary-Section Table */
    public final TagNodeIndex tableOpen;

    /** The closing {@code </TABLE>} tag, for a Summary-Section Table */
    public final TagNodeIndex tableClose;

    // The First Row / Title Row of a Summary-Section Table
    // Package-Private *AND* final
    //
    // EXPORTED BY THE EXPORT_PORTAL, Used in: CleanSummaries and RearrangeEntitySummaries

    final Vector<HTMLNode> headerRow;

    // The Red Banner-H3, with Cinzel-Font that says "Method Summary" or "Field Summary"
    // Package-Private *AND* final
    //
    // EXPORTED BY THE EXPORT_PORTAL, Used in: CSSTagsTopAndSumm

    final TagNodeIndex cinzelH3;

    // The HTML Row's of every row in the table, except the initial header-row,
    // and this is "Package-Visible".  There is a getter below.

    private Vector<Vector<HTMLNode>> tableRows = new Vector<>();

    // The actual Reflection-Declaration for each of these rows.  For Inner-Classes the type
    // parameter 'ENTITY' is String.  For the other 5 it is their 'Declaration' inheriting class.
    // This is also Package-Visible only.

    private Vector<ENTITY> rowEntities = new Vector<>();

    // back-pointer to the JavaDocHTMLFile that contained this Summary-Table
    private final JavaDocHTMLFile jdhf;


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Number of Rows
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve the total number of Table-Rows in the Summary-Table.
     * @return The number of HTML {@code <TR>...</TR>} elements in this Summary-Table
     */
    public int numRows() { return tableRows.size(); }

    /**
     * Retrieve the number of Table-Rows that have Title-Bars in this Summary-Table.
     * @return The number of HTML {@code <TR>...</TR>} elements in this Summary-Table which contain
     * Title-Bars, rather than entity/member signature URL-Links.
     */
    public int numTitleBarRows()
    {
        int counter = 0;
        for (ENTITY e : rowEntities) if (e == null) counter++;
        return counter;
    }

    /**
     * Retrieve the number of Entity/Member Signatures which occupy a Table-Row in this
     * Summary-Table
     * @return The number of HTML {@code <TR>...</TR>} elements in this Summary-Table which contain
     * entity/member signature URL-Links.
     */
    public int numSignatureRows()
    {
        int counter = 0;
        for (ENTITY e : rowEntities) if (e != null) counter++;
        return counter;
    }

    /**
     * This method simply scans the internal {@code 'rowEntities'} list / {@code Vector} to check
     * each element to determine if it contains one of the User-Provided descriptive orange-banner
     * titles, or contains an actual Entity/Member {@code URL}-Link.
     * 
     * <BR /><BR />The members of a type are listed in enum {@link Entity}.  JavaDoc Upgrader
     * refers to Class or Interface members as "Entities."  A Summary-Table on a Java-Doc Page -
     * <I>after a Summary HTML Table Sort - will have some HTML Table-Rows with Members / Entities,
     * and some Rows having orange-colored horizontal banner Title-Bars</I>.
     * 
     * <BR /><BR />When the HTML Table-Row ({@code '<TR> ... </TR>'}) has an {@code <A>-URL}
     * link to one of the members of the class (a method, field, constructor, etc...), the returned
     * array will contain {@code TRUE} for that index.  When the row contains a Title-Bar, the
     * array-index for that row will contain {@code FALSE}.
     * 
     * @return A {@code boolean[]}-Array whose length is equal to the number of rows in this
     * Summary-Table, and whose {@code boolean} values are {@code TRUE} if the Table-Row contains
     * a {@code URL}-Link to one of the entities (Methods, Constructors, Fields, etc...) of the
     * CIET / Type.
     */
    public boolean[] memberRows()
    {
        boolean[]   ret = new boolean[rowEntities.size()];
        int         i   = 0;

        for (ENTITY e : rowEntities) ret[i++] = (e != null);

        return ret;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Getters by index / row number
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * If you have a chosen / desired HTML Summary-Table Row (with a selected summary
     * element/item) - you may pass the table-row index of that item to retrieve the
     * {@code rowIndex}<SUP>th</SUP> instance of {@link ReflHTML} that contains the
     * Detail-Element Parsed-HTML corresponding to that row.
     * 
     * @param rowIndex Any one of the Summary-HTML Table-Rows.  Each Summary-Table Row is either a
     * Title-Bar {@code <TR>} / Row, or it is a {@link Entity} / Member Table {@code <TR>} Row.  
     * {@link Entity}-Rows are HTML {@code <TR>}-Rows that simply contain an Anchor {@code <A>} 
     * link to one of this CIET's Members / Entites.
     * 
     * <BR /><BR />For example, if {@code 'this'} Summary-Table instance were for Method's, and the
     * Table-Row index for the {@code 'toString()'} Method were passed to parameter
     * {@code 'rowIndex'}, this method would return the {@link ReflHTML} for the {@code toString}
     * Method.
     * 
     * <BR /><BR />The returned {@link ReflHTML} instance would contain all of the parsed
     * HTML information for the method {@code toString}.
     * 
     * <BR /><BR />If this parameter points to a Table-Row that contains an Orange-Colored 
     * Title-Bar (generated by the Summary-Sorters), rather than an Entity/Member Signature,
     * then this method will return null.
     * 
     * @return The parsed detailed HTML explanation for the Summary-Table item chosen by parameter
     * {@code 'rowIndex'}.
     *
     * <BR /><BR /><B STYLE='color: red;'>IMPORTANT:</B> When parameter {@code 'rowIndex'} is
     * passed a value that <I>is not out of bounds for the {@code 'rowEntities'} vector</I>,
     * but is a row that contains an orange Title-Bar, in such cases there is no detail-member
     * (no instance of {@code ReflHTML}) to return.  When a {@code 'rowIndex'} for a Title-Bar
     * row is passed, this method will return null, gracefully.
     * 
     * @throws IndexOutOfBoundsException If {@code rowIndex} is not properly chosen as per the
     * number of rows in the table.  If there are {@code '10'} rows-items in this table, then the
     * {@code rowIndex} parameter should be between {@code '0'} and {@code '9'}.
     */
    @SuppressWarnings("unchecked")  // NOTE: The cast on the 'return' line.  It *IS* checked
                                    // but the compiler isn't smart enough to see that!
    public ReflHTML<ENTITY> getRowDetail(int rowIndex)
    {
        // Look up the "rowIndex" row in the "rowEntities" vector which just contains the list of
        // rows on this Summary HTML Table.  The "ENTITY" is one of the 5 reflected-HTML classes
        // used by this package (Method, Field, Constructor etc...)

        ENTITY selectedEntityMember = rowEntities.elementAt(rowIndex);

        // Some rows contain only title information.  In such cases, there is no detail-element
        // associated with this table-row.  It is just a title!!  When the user has passed a title
        // row to parameter 'rowIndex', just return null.

        if (selectedEntityMember == null) return null;

        // Use JavaDocHTMLFile.findReflHTML(int, Class) to get the ReflHTML needed.
        // NOTE: this.tableType.upgraderReflectionClass <==> ENTITY.class

        return (ReflHTML<ENTITY>) jdhf.findReflHTML
            (selectedEntityMember.id, this.tableType.upgraderReflectionClass);
    }

    /**
     * Retrieve the {@code i}<SUP>th</SUP> HTML {@code <TR>} (row) from  {@code this} Summary-Table
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>{@link Entity}-Member Rows:</B>
     * 
     * <BR />If {@code 'rowIndex'} is pointing to one of the entities / members of the class (such
     * as a Field, Method or Constructor etc...), then the HTML {@code <A ...>} Anchor-{@code URL}
     * for that {@link Entity} is returned.  The returned HTML-{@code Vector} will contain
     * everything between the {@code <TR>} and the {@code </TR>} for that Table-Row.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Title-Bar Rows:</B>
     *  
     * <BR />Not every row in a Summary-Table is guaranteed to have an Entity/Member Signature
     * instance.  Bear in mind that whenever a user sorts Summary-Table Row's into Categories or
     * Sections, then any &amp; all Section / Category Title-Bar Rows will be present in the
     * Summary-Table HTML.
     * 
     * <BR /><BR />Title-Bar rows are the horizontal, fading-orange bars that line the Table of
     * Contents (Summary-Tables).  These orange-colored banners have a brief, one-sentence
     * description for a small group of methods, fields or constructors.
     * 
     * <BR /><BR />If parameter {@code 'rowIndex'} is pointing to a Title-Bar, then the parsed
     * HTML-{@code Vector} for that Title-Bar is returned. 
     * 
     * <BR /><BR />In all other cases, the entity/member Signature is returned as a  result from a
     * call to this method.
     * 
     * @param rowIndex The row number to retrieve
     * @return All HTML between the {@code <TR>} and the {@code </TR>} for one table-summary row.
     * 
     * @throws IndexOutOfBoundsException If {@code 'rowIndex'} is not within the bounds of the list
     * of rows
     */
    public Vector<HTMLNode> getRowHTML(int rowIndex)
    { return tableRows.elementAt(rowIndex); }

    /**
     * Retrieve the {@code i}<SUP>th</SUP> entity.  The returned instance will be one of the six
     * subclasses of class {@code Declaration}, as decided by the type-parameter {@code ENTITY}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>{@link Entity}-Member Rows:</B>
     * 
     * <BR />If {@code 'rowIndex'} is pointing to one of the entities / members of the class (such
     * as a Field, Method or Constructor etc...), then the reflected-class for that {@link Method},
     * {@link Field}, {@link Constructor} is returned.  If {@code 'this'} Summary-Table has
     * Generic-Type {@code SummaryTableHTML<Field>}, then the returned {@link ENTITY} will be a
     * {@link Field} class instance.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Title-Bar Rows:</B>
     * 
     * <BR />Not every row in a Summary-Table is guaranteed to have an Entity/Member Signature
     * instance.  Bear in mind that whenever a user sorts Summary-Table Row's into Categories or
     * Sections, then any &amp; all Section / Category Title-Bar Rows will be present in the
     * Summary-Table HTML.
     * 
     * <BR /><BR />Title-Bar rows are the horizontal, fading-orange bars that line the Table of
     * Contents (Summary-Tables).  These orange-colored banners have a brief, one-sentence
     * description for a small group of methods, fields or constructors.
     * 
     * <BR /><BR />If parameter {@code 'rowIndex'} is pointing to a Title-Bar, <I>then this method
     * shall default and return null!</I>
     * 
     * @param rowIndex The entity-number (row-number) to retrieve from {@code this} Summary-Table.
     * 
     * @return The refected-information for one Summary-Table row.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     * 
     * @throws IndexOutOfBoundsException If {@code 'rowIndex'} is not within the bounds of the list
     * of rows
     */
    public ENTITY getRowEntity(int rowIndex)
    { return rowEntities.elementAt(rowIndex); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Getters by index / row number, USING Ret2's for more complete information.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve <B STYLE='color: red;'><I>both</I></B> the row-HTML
     * <B STYLE='color: red;'><I>and</I></B> the reflected-entity information for the
     * {@code i}<SUP>th</SUP> row in {@code this} Summary-Table.
     * 
     * <BR /><BR />Not every row in a Summary-Table is guaranteed to have a Member Signature.  
     * When Summary-Table's are sorted into categories or sections, then a Summary-Table may also
     * have a Title-Bar row.  It is (hopefully) obvious that a Title-Bar row would not contain an
     * associated {@code 'ENTITY'} (Method, Field, Constructor, etc...).
     * 
     * @param rowIndex The entity-number / row-number to retrieve from {@code this} Summary-Table.
     * 
     * @return An instance of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_ENTITY_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     * 
     * @throws IndexOutOfBoundsException If {@code 'rowIndex'} is not within the bounds of the list
     * of rows
     */
    public Ret2<ENTITY, Vector<HTMLNode>> getRowEntityAndHTML(int rowIndex)
    { return new Ret2<>(rowEntities.elementAt(rowIndex), tableRows.elementAt(rowIndex)); }

    /**
     * Retrieve <B STYLE='color: red;'><I>both</I></B> the row-HTML
     * <B STYLE='color: red;'><I>and</I></B> and the corresponding / matching instance of 
     * {@link ReflHTML} for the {@code i}<SUP>th</SUP> row in {@code this} Summary-Table
     * 
     * <BR /><BR />Not every row in a Summary-Table is guaranteed to have a Member Signature.  
     * When Summary-Table's are sorted into categories or sections, then a Summary-Table may also
     * have a Title-Bar row.  It is (hopefully) obvious that a Title-Bar row would not contain an
     * associated {@code 'ReflHTML'} HTML Data-Object either.
     * 
     * @param rowIndex The entity-number / row-number to retrieve from {@code this} Summary-Table.
     * 
     * @return An instance of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_REFL_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     * 
     * @throws IndexOutOfBoundsException If {@code i} is not within the bounds of the list of rows
     * @see #getRowDetail(int)
     */
    public Ret2<ReflHTML<ENTITY>, Vector<HTMLNode>> getRowDetailAndHTML(int rowIndex)
    { return new Ret2<>(getRowDetail(rowIndex), tableRows.elementAt(rowIndex)); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Stream's
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * A {@code Stream} that contains {@code this} Summary-Table's rows, as Vectorized-HTML
     *
     * @return A stream of Vectorized-HTML Table-Rows for {@code this} Summary-Table.
     *
     * <BR /><BR />Note that a Java {@code Stream} is easily converted into just about any
     * necessary data-type, as explained in the table below:
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=STREAM_CONVERT_T>
     */
    public Stream<Vector<HTMLNode>> rowHTMLStream() { return tableRows.stream(); }

    /**
     * A {@code Stream} that contains all Summary-Table row-entities, as instances of the reflected
     * information class {@code ENTITY} (this class' sole type-parameter).
     * 
     * <BR /><BR />Generic Type-Parameter {@code ENTITY} will be one of the six concrete subclasses
     * of class {@link Declaration}.
     * 
     * @return A stream of entities contained by {@code this} Summary-Table.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     *
     * <BR /><BR />Note that a Java {@code Stream} is easily converted into just about any
     * necessary data-type, as explained in the table below:
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=STREAM_CONVERT_T>
     */
    public Stream<ENTITY> rowEntityStream() { return rowEntities.stream(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Entire Table
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve a {@code Stream} that contains <B><I>every</I></B> Summary-Table Row.
     * 
     * <BR /><BR />The specific contents of this {@code Stream} are instances of {@link Ret2},
     * which contain <B STYLE='color: red;'><I>both</I></B> the reflected-entity information
     * (instance of Type-Parameter {@code ENTITY}) <B STYLE='color: red;'><I>and</I></B> the
     * Vectorized-HTML Table-Row, as well.
     * 
     * @return A Java Stream containing instances of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_ENTITY_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     */
    public Stream<Ret2<ENTITY, Vector<HTMLNode>>> entityAndHTMLStream()
    {
        Stream.Builder<Ret2<ENTITY, Vector<HTMLNode>>> b = Stream.builder();

        for (int rowIndex=0; rowIndex < rowEntities.size(); rowIndex++)
            b.accept(new Ret2<>(rowEntities.elementAt(rowIndex), tableRows.elementAt(rowIndex)));

        return b.build();
    }

    /**
     * Retrieve the entire list of Table-Rows in this HTML Summary-Table into a {@code Vector}.
     * 
     * @return A Java Stream containing instances of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_REFL_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     */
    public Stream<Ret2<ReflHTML<ENTITY>, Vector<HTMLNode>>> reflAndHTMLStream()
    {
        Stream.Builder<Ret2<ReflHTML<ENTITY>, Vector<HTMLNode>>> b = Stream.builder();

        for (int rowIndex=0; rowIndex < rowEntities.size(); rowIndex++)
            b.accept(new Ret2<>(getRowDetail(rowIndex), tableRows.elementAt(rowIndex)));

        return b.build();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: FIND-METHODS
    // ********************************************************************************************
    // ********************************************************************************************


    private void CHECK_IS_CALLABLE()
    {
        if (this.tableType.isCallable()) return;

        String kind = this.tableType.upgraderReflectionClass.getSimpleName();

        throw new UpgradeException(
            "This 'find' method may only be used on SummaryTableHTML instances for Method or " +
                "Constructor Summary Tables.\n" +
            "This is a SummaryTableHTML<" + kind + "> instance, and this find method may not be " +
                "used.\n" +
            "CIET/Type Member Names for " + kind + "'s cannot be overloaded, so therefore you " +
                "should use the simple/standard find(String) method instead."
        );
    }

    private void CHECK_NUM_PARAMS(int numParams)
    {
        if (numParams < 1) throw new IllegalArgumentException(
            "This find method will only search for Callable's (Method's and Constructor's) that" +
            "accept at least 1 parameter.  You have passed [" + numParams + "] to parameter " +
            "'numParams'.  This is not allowed." +
            ((numParams == 0)
                ? "\nWhen searching for a zero-argument Callable, use " +
                    "SummaryTableHTML.find(String)"
                : "")
        );
    }

    /**
     * Retrieves the first Entity/Member whose name matches {@code name}.  When searching a
     * {@code SummaryTableHTML<Field>}, {@code SummaryTableHTML<EnumConstant>} or 
     * {@code SummaryTableHTML<AnnotationElem>}, the name of the entity/member will uniquely
     * identify it amongst the others in the table.
     * 
     * <BR /><BR />Due to Java's function overloading, there may be many cases where a
     * member {@code 'name'} is not sufficient to uniquely identify it (for Method's and 
     * Constructor's).  In such cases (e.g. overloaded methods) this method simply return the index
     * of the first match it finds.
     * 
     * @param name The name of the entity / member, as a {@code java.lang.String}
     * 
     * @return The index of the (first) HTML Table-Row that contains the specified {@link Entity}.
     * If this Summary-Table does not have any member-signatures by that {@code 'name'}, then
     * {@code -1} will be returned.
     */
    public int find(String name)
    {
        ENTITY e = null;

        for (int i=0; i < rowEntities.size(); i++)

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if ((e = rowEntities.elementAt(i)) != null)
                if (e.name.equals(name))
                    return i;

        return -1;
    }

    /**
     * Retrieves the first Entity/Member whose name matches {@code 'methodOrCtorName'}.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * 
     * @throws SummaryTableException <EMBED CLASS='external-html' DATA-FILE-ID=ST_SUMM_EX>
     * 
     * @return The index of the first HTML Table-Row that matches this specified name.  If this
     * Summary-Table does not have any (Method or Constructor) Member-Signatures by that name,
     * then {@code -1} is returned.
     */
    public int findFirst(String methodOrCtorName)
    {
        CHECK_IS_CALLABLE();

        ENTITY e = null;

        for (int i=0; i < rowEntities.size(); i++)

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if ((e = rowEntities.elementAt(i)) != null)
                if (e.name.equals(methodOrCtorName))
                    return i;

        return -1;
    }

    /**
     * Retrieves the first Entity/Member whose name matches {@code 'methodOrCtorName'}, 
     * and accepts {@code 'numParams'} parameters.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * @throws SummaryTableException <EMBED CLASS='external-html' DATA-FILE-ID=ST_SUMM_EX>
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=ST_IAEX>
     * 
     * @return The index of the first HTML Table-Row that matches the provided specifications.  If
     * this Summary-Table does not have any Member-Signatures with that name and accepting the
     * specified number of parameters, then this method returns {@code -1}.
     */
    public int findFirst(String methodOrCtorName, int numParams)
    {
        CHECK_IS_CALLABLE();
        CHECK_NUM_PARAMS(numParams);

        for (int i=0; i < rowEntities.size(); i++)
        {
            ENTITY e = rowEntities.elementAt(i);

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if (e == null) continue;

            if (e.name.equals(methodOrCtorName))
                if (((Callable) e).numParameters() == numParams)
                    return i;
        }

        return -1;
    }

    /**
     * Retrieves all Entities/Member Table-Row Indices whose name matches
     * {@code 'methodOrCtorName'}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=ST_FIND_ALL_RET>
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * int[] tableRows = methodSummTable.findAll("someMethodName").toArray();
     * }</DIV>
     * 
     * @throws SummaryTableException <EMBED CLASS='external-html' DATA-FILE-ID=ST_SUMM_EX>
     */
    public IntStream findAll(String methodOrCtorName)
    {
        CHECK_IS_CALLABLE();

        IntStream.Builder   b = IntStream.builder();
        ENTITY              e = null;

        for (int i=0; i < rowEntities.size(); i++)

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if ((e = rowEntities.elementAt(i)) != null)
                if (e.name.equals(methodOrCtorName))
                    b.accept(i);

        return b.build();
    }

    /**
     * Retrieves the first Entity/Member Table-Row Index whose name matches
     * {@code 'methodOrCtorName'},  and accepts {@code 'numParams'} parameters.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * @param numParams <EMBED CLASS='external-html' DATA-FILE-ID=ST_NUM_PARAMS>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=ST_FIND_ALL_RET>
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * int[] tableRows = methodSummTable.findAll("someMethodName", 1).toArray();
     * }</DIV>
     * 
     * @throws SummaryTableException <EMBED CLASS='external-html' DATA-FILE-ID=ST_SUMM_EX>
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=ST_IAEX>
     */
    public IntStream findAll(String methodOrCtorName, int numParams)
    {
        CHECK_IS_CALLABLE();
        CHECK_NUM_PARAMS(numParams);

        IntStream.Builder b = IntStream.builder();

        for (int i=0; i < rowEntities.size(); i++)
        {
            ENTITY e = rowEntities.elementAt(i);

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if (e == null) continue;

            if (e.name.equals(methodOrCtorName))
                if (((Callable) e).numParameters() == numParams)
                    b.accept(i);
        }

        return b.build();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    // Package-Private: Only used in RearrangeEntitySummaries
    // EXPORTED BY THE EXPORT_PORTAL

    void setTableRows(Vector<Vector<HTMLNode>> tableRows, Vector<ENTITY> rowEntities)
    {
        this.tableRows      = tableRows;
        this.rowEntities    = rowEntities;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // STATIC BUILDER-GETTER FOR THIS CLASS (the constructor is private)
    // ********************************************************************************************
    // ********************************************************************************************


    // This method is called by JavaDocHTMLFile, and it builds / parses all of the
    // SummaryTableHTML's in one step.  This is because looking for them would be less efficient if
    // searching for the 'markers' were done seven different times, rather than all at once, using
    // a single serach.
    //
    // These seven returned-tables are assigned to the JavaDocHTMLFile fields for each of the
    // summary-table kinds/types.

    @SuppressWarnings("rawtypes")
    static Ret7<
            SummaryTableHTML<Method>,
            SummaryTableHTML<Field>,
            SummaryTableHTML<Constructor>,
            SummaryTableHTML<EnumConstant>,
            SummaryTableHTML<AnnotationElem>,
            SummaryTableHTML<AnnotationElem>,
            SummaryTableHTML<NestedType>
        >
    parseAllSummaryTables
        (Vector<HTMLNode> fileVec, JavaSourceCodeFile jscf, JavaDocHTMLFile jdhf)
    {
        // These are all inserted
        SummaryTableHTML<Method>            retMethodSummaryTable        = null;
        SummaryTableHTML<Field>             retFieldSummaryTable         = null;
        SummaryTableHTML<Constructor>       retConstructorSummaryTable   = null;
        SummaryTableHTML<EnumConstant>      retECSummaryTable            = null;
        SummaryTableHTML<AnnotationElem>    retOAESummaryTable           = null;
        SummaryTableHTML<AnnotationElem>    retRAESummaryTable           = null;
        SummaryTableHTML<NestedType>        retNTSummaryTable            = null;

        // Retrieve all the pointers to the Summary-Sections.  They all begin with the Java Doc
        // HTML Comment <!-- == Method Summary == --> (with the word "Method" replaced by whatever
        // type of summary it actually is)
        //
        // This is a method that used to be in the old "Summaries.java" (deprecated)

        int[] markerPosArr = /* Summaries.allEntityMarkers(fileVec); */
            CommentNodeFind.all(fileVec, TextComparitor.CN_OR, MARKERS);

        // Loop through all of the HTML Comments like: <!-- == Method Summary == -->
        for (int i=0; i < markerPosArr.length; i++)
        {
            int markerPos = markerPosArr[i];

            /*
            System.out.println(
                BGREEN + "Marker Pos: " + markerPos + RESET + ' ' +
                fileVec.elementAt(markerPos).str
            );
            */

            // The <H3> looks like these (after inserting the CSS Tag 'C26'), which is done later
            // The <H3> should be within the next 30 nodes...
            //
            // <h3 class=C26>Optional Element Summary</h3> 
            // <h3 class=C26>Method Summary</h3>
            //
            // NOTE: This *ALSO* could be the "<H3> ... inherited from </H3>"" if it did not have
            //       any actual entities declared in its own type.  If it is an *ONLY* inherited 
            //       then the <H3> will be closer to 30 nodes away, not 20.

            int pos = TagNodeFind.first
                (fileVec, markerPos, markerPos + 30, TC.OpeningTags, "h3");

            // This is the Red-Banner H3 CINZEL Title-Bar saying "Method Summaries"
            TagNodeIndex openingH3 = new TagNodeIndex(pos, (TagNode) fileVec.elementAt(pos));

            if (pos == -1)
                Messager.assertFailHTML("Summary Marker is not followed by an <H3>", null);

            // If this is *ACCIDENTALLY* left-off, *AND* this is one of those cases, where there
            // are only *INHERITED* methods (no actual methods defined), then the FindInclusive
            // will return the table for the *NEXT MARKER* - which is a mistake!
            //
            // This sets the FindInclusive for <TABLE>...</TABLE> to limit the search-range
            // to the start of the NEXT-MARKER-POS (or PAGE-END, if this is the last marker).

            int endSearchPos = ((i+1) < markerPosArr.length) ? markerPosArr[i+1] : -1;

            // Now, the Summary Table should be directly below the <H3> Tag, use the restricted
            // range that was just computed in the previous line.

            DotPair tableLocation = InnerTagFindInclusive.first
                (fileVec, pos, endSearchPos, "table", "class", TextComparitor.C, "memberSummary");

            if (tableLocation == null)
            {
                // There are classes which do not define any methods at all, but stil have a
                // Summary-Section for methods.  If a Type inherits from another type, the method
                // Summary Section will have a small list at the bottom of all the methods that
                // are inherited from it's super-class or interface.
                //
                // In such cases, this is not an error, but it is also not a summary table.  In
                // these cases, just 'continue' and there will not be an instantiated Summary Table
                // for the particular entity, of this particular Type/CIET.
                //
                // Start at the current <H3> position - *PLUS ONE* - and look for the next <H3>.
                // That <H3> will have text that says "inherited from"

                int checkIfInheritedPos = TagNodeFind.first
                    (fileVec, pos+1, pos + 30, TC.OpeningTags, "h3");

                // System.out.println(fileVec.elementAt(pos+1).str);

                // If this marker didn't have a table, **AND** doesn't have anything it inherited,
                // then this has to be an unhandled / assertion-fail

                if (! fileVec.elementAt(checkIfInheritedPos + 1).str.contains("inherited from"))
                    Messager.assertFailHTML
                        ("Summary <H3> not followed by <TABLE CLASS=memberSummary>", null);

                // NOTE: the "else" here is that the constructor will just set the "Opening H3"
                //       parameter (this.cinzelH3), and then exit immediately, before setting
                //       all the other fields to null
            }

            // This could easily be 'switched' based on the marker-kind, but it would still be a
            // string assignment, since the "get all markers" just returns a vector-index location,
            // rather than the name of the marker.
            //
            // NOTE: If the "tableLocation" is null (because there were only inherited-entities,
            //       from the super-class, and no declared entities, then the SummaryTableHTML
            //       constructor just sets the openingH3, and exits);

            switch (fileVec.elementAt(pos + 1).str)
            {
                case "Method Summary": retMethodSummaryTable = new SummaryTableHTML<>
                        (fileVec, tableLocation, openingH3, Entity.METHOD, jscf, jdhf);
                    break;

                case "Constructor Summary": retConstructorSummaryTable = new SummaryTableHTML<>
                        (fileVec, tableLocation, openingH3, Entity.CONSTRUCTOR, jscf, jdhf);
                    break;

                case "Field Summary": retFieldSummaryTable = new SummaryTableHTML<>
                        (fileVec, tableLocation, openingH3, Entity.FIELD, jscf, jdhf);
                    break;

                case "Enum Constant Summary": retECSummaryTable = new SummaryTableHTML<>
                        (fileVec, tableLocation, openingH3, Entity.ENUM_CONSTANT, jscf, jdhf);
                    break;

                case "Optional Element Summary": retOAESummaryTable = new SummaryTableHTML<>
                        (fileVec, tableLocation, openingH3, Entity.ANNOTATION_ELEM, jscf, jdhf);
                    break;

                case "Required Element Summary": retRAESummaryTable = new SummaryTableHTML<>
                        (fileVec, tableLocation, openingH3, Entity.ANNOTATION_ELEM, jscf, jdhf);
                    break;

                case "Nested Class Summary": retNTSummaryTable = new SummaryTableHTML<>
                        (fileVec, tableLocation, openingH3, Entity.INNER_CLASS, jscf, jdhf);
                    break;

                default: Messager.assertFailHTML
                    ("Unrecognized Summary Table Type", fileVec.elementAt(pos + 1).str);
            }
        }

        // Just return these built summary table.  It is likely that many of these will be null.
        return new Ret7<>(
            retMethodSummaryTable,
            retFieldSummaryTable,
            retConstructorSummaryTable,
            retECSummaryTable,
            retOAESummaryTable,
            retRAESummaryTable,
            retNTSummaryTable
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // private constructor
    // ********************************************************************************************
    // ********************************************************************************************


    @SuppressWarnings("unchecked") // The (ENTITY) getter.apply(row); line...
    private SummaryTableHTML(
            Vector<HTMLNode>    fileVec,    
            DotPair             tableLocation,
            TagNodeIndex        openingH3,
            Entity              tableType,
            JavaSourceCodeFile  jscf,
            JavaDocHTMLFile     jdhf
        )
    {
        this.jdhf = jdhf;

        // This literally just sets the TagNodeIndex field "cinzelH3" - which is the title /
        // header / banner in red with rounded corners.  The rest is null.
        //
        // 'tableLocation' will be null whenever there is a Summary-Table whose only contents
        // are the "Inherited Entities" (Type's that inherit, methods for example, but do not
        // declare any methods of their own).

        if (tableLocation == null)
        {
            this.cinzelH3   = openingH3;
            this.tableType  = tableType;

            // Set this stuff to null, and exit
            this.tableOpen = this.tableClose = null;
            this.headerRow = null;

            return;
        }

        // These were built directly above, the element being retrieved is guaranteed to be a <TABLE>
        // ... unless InnerTagFindInclusive is broken (and it isn't)... or the page suddenly changed ...
        // (which it can't, this is a private method) ... no need to do assert's here

        this.tableOpen = new TagNodeIndex
            (tableLocation.start, fileVec.elementAt(tableLocation.start).ifTagNode());

        this.tableClose = new TagNodeIndex
            (tableLocation.end, fileVec.elementAt(tableLocation.end).ifTagNode());

        // This specifies which type of Summary-Table this is... Method, Field, Enum-Constant...
        this.tableType = tableType;

        // This is the CINZEL-font Banner-Header-Label that just says "Method Summaries"
        // or "Field Summaries" or "Optional Annotation Element Summaries"

        this.cinzelH3 = openingH3;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Build a "Getter" for Converting a Summary-Row into an **ENTITY** / Reflection instance
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // By using a 'getter' function, this switch-statement can be run *OUTSIDE OF THE LOOP*.
        // The other way to do this, is put the switch inside the loop, and it will be executed
        // for every row in the table, rather than only once.

        Function<String, ENTITY> getter = null;

        switch (tableType)
        {

            // The following notice was placed in each of these switch/case statements.
            // It applies to all 6 of them, but is only left here at the top:
            //
            // This is called twice:
            //      Once from JavaDocHTMLFile: using the Detail-HTML-Signature
            //      Once from SummaryTableHTML: using the Summary-HTML-Signature
            //
            // MESSAGER:
            //  1) INVOKES:     assertFailHTML
            //  2) INVOKED-BY:  SummaryTableHTML-Constructor & JavaDocHTMLFile-Constructor
            //  3) RETURNS:     HTML-Parsed (stripped) Torello.JavaDoc.Method
            //  4) THROWS:      JavaDocHTMLParseException (assertFailHTML)

            case METHOD:

                getter = (String row) ->
                    (ENTITY) SignatureParse.parseMethodSignature(row, jscf, jdhf);

                break;

            case CONSTRUCTOR:

                getter = (String row) ->
                    (ENTITY) SignatureParse.parseConstructorSignature(row, jscf, jdhf);

                break;

            case FIELD:

                // NOTE: 'true' is passed to the 'hasGenericParameters' boolean
                //
                // Passing 'true' seems like cheating, but that's what RearrangeEntitySummaries
                // was doing.  Actually, it is irrelevant because HERE, the Field that is
                // returned was RETRIEVED not GENERATED - and that literally, just requires the
                // name of the field.  *AND* when getting the name of the field from the
                // signature, the 'generic-parameters' are not important.

                getter = (String row) ->
                    (ENTITY) SignatureParse.parseFieldSignature(row, true, jscf, jdhf);

                break;

            case ENUM_CONSTANT:

                getter = (String row) ->
                    (ENTITY) SignatureParse.parseECSignature(row, jscf, jdhf);

                break;

            case ANNOTATION_ELEM:

                getter = (String row) ->
                    (ENTITY) SignatureParse.parseAESignature(row, jscf, jdhf);

                break;

            case INNER_CLASS:

                getter = (String row) ->
                    (ENTITY) SignatureParse.parseNTSignature(row, jscf, jdhf);

                break;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Retrieve / extract all Summary Table-Row's
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Retrieve all Table row <TR>'s
        //
        // Before the Summary-Table has been modified by the Java Doc Upgrader, the entries in the
        // table are all the <TR>'s (it's that simple)... Creating <TR>'s that have titles, and
        // other non-entity contents is *NOT* done *UNTIL* RearrangeEntitySumamries

        Vector<Vector<HTMLNode>> rows = TagNodeGetL1Inclusive.all
            (fileVec, tableLocation.start, tableLocation.end, "tr");

        // Now, iterate through all of the <TR>'s.  The first <TR> needs to be assigned to the
        // NodeIndex that will hold the FIRST ROW.  If the table isn't sorted, it will need to be
        // retained to be re-inserted.

        // this.headerRow = rows.elementAt(0);

        int firstRowEndTR = TagNodeFind.first
            (fileVec, tableLocation.start, tableLocation.end, TC.ClosingTags, "TR");

        this.headerRow = Util.cloneRange(fileVec, tableLocation.start + 1, firstRowEndTR + 1);

        // Skip the header-row, it was just saved in the previous line
        boolean first = true;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 
        // These temporary loop-variables are needed to do the CSS-ID insert (or lack-thereof)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 

        ENTITY  entity = null;
        String  abbrev = this.tableType.abbrev; // Two-character CSS-ID abbreviation-string

        boolean startingPosIsEnumOrCtorCheck =
            (this.tableType == Entity.ENUM_CONSTANT) ||
            (this.tableType == Entity.CONSTRUCTOR);

        boolean detailsRemoved =
                ((this.tableType == Entity.METHOD)          && jdhf.methodDetailsRemoved)
            ||  ((this.tableType == Entity.CONSTRUCTOR)     && jdhf.constructorDetailsRemoved)
            ||  ((this.tableType == Entity.FIELD)           && jdhf.fieldDetailsRemoved)
            ||  ((this.tableType == Entity.ENUM_CONSTANT)   && jdhf.ecDetailsRemoved)
            ||  ((this.tableType == Entity.ANNOTATION_ELEM) && jdhf.aeDetailsRemoved);

        // System.out.println
        //      ("Starting: " + BRED + "table has " + rows.size() + " rows." + RESET);

        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 
        // Iterate the Summary <TABLE> rows, and insert them into 'tableRows' and 'rowEntites'
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 
        //
        // NOTE: This loop is *ALSO* where the Summary-Row CSS-ID is inserted.  An ID is not
        //       inserted (on the off chance / kind-of rare) that the relevant Details-Section
        //       was requested to be removed by the user.

        for (Vector<HTMLNode> row : rows)

            if (first) first = false;

            else
            {
                // System.out.println("ROW HTML:\n" + Util.pageToString(row.html));
                String rowStr = extractSignature(row, this.tableType);
                // System.out.println("rowStr: " + BYELLOW + rowStr + RESET + '\n');


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // Here the List of HTML-Rows and the List of Row-ENTITY (Vector) are filled up
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                // This is the internal-Vector that contains all of the Summary-Table Row HTML
                this.tableRows.add(row);

                // Use the "getter" to extract / retrieve the ENTITy (Method, Field, Constructor,
                // EnumConstant, etc...)

                entity = getter.apply(rowStr);

                // Save the ENTITY into the parallel 'rowEntities' Vector
                this.rowEntities.add(entity);


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // CSS Entity-Row-ID - This CSS-ID is used by the NavButtons Bar
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                //
                // This CSS-ID is inserted into the Summary-Row <A> Anchor: <A ID=entityID ...>
                // This CSS-ID is the exact same ID that is later added to the <A HREF=entityID>
                // for the Double-Up Arrow Button (⇈) of the corresponding ReflHTML Detail-Section

                TagNode tn          = null;
                boolean insertedID  = false;

                int i = startingPosIsEnumOrCtorCheck
                    ? 0
                    : TagNodeFind.nth(row, 2, TC.OpeningTags, "td", "th") + 1;

                INNER:
                for (; i < row.size(); i++)

                    if ((tn = row.elementAt(i).openTag()) != null)
                        if (tn.tok.equals("a"))
                        {
                            row.setElementAt(tn.setID(abbrev + entity.id, null), i);
                            insertedID = true;
                            break INNER;
                        }

                if (! insertedID) if (! detailsRemoved) Messager.assertFailHTML(
                    "Failed to Insert CSS-ID [" + abbrev + entity.id + "] into Summary " +
                    "Table Row", rowStr
                );
            }
    }

    // *** THIS MAY NEED TO CHANGE ***
    // CURRENTLY: In Java Doc for Java 11, the first two columns hold the return type and the
    //            rest of the signature.
    //
    // COPIED DIRECTLY FROM 'RearrangeEntitySummaries' CHANGED FOR USING 'dp' INSTEAD OF
    // Vector

    private String extractSignature(Vector<HTMLNode> tableRow, Entity tableType)
    {
        Vector<DotPair> cols = TagNodeFindInclusive.all(tableRow, "td", "th");

        StringBuffer    sb  = new StringBuffer();
        TextNode        txn = null;

        DotPair dp = cols.elementAt(0);

        for (int i=dp.start+1; i < dp.end; i++)
            if ((txn = tableRow.elementAt(i).ifTextNode()) != null)
                sb.append(txn.str);

        // Enum-Constants have one row of 'constant-name' and then one row of description.  The
        // others have two rows: a row of 'type/modifiers' and a row of 'signature/name'

        if (tableType == Entity.ENUM_CONSTANT) return sb.toString().trim();

        // Constructors may have two or three rows.  If there is a modifier, then there are three,
        // if there are no modifiers for the constructors, then there are only two.  If there are
        // two, exit now

        if (tableType == Entity.CONSTRUCTOR) if (cols.size() == 2) return sb.toString().trim();

        sb.append(' ');

        dp = cols.elementAt(1);

        for (int i=dp.start+1; i < dp.end; i++)
            if ((txn = tableRow.elementAt(i).ifTextNode()) != null)
                sb.append(txn.str);

        return sb.toString().trim();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // REBUILD THE JAVADOC PAGE
    // ********************************************************************************************
    // ********************************************************************************************


    // Used in the method below
    private static final TextNode NEW_LINE = new TextNode("\n");

    // Method below too
    private static final Vector<Replaceable> EMPTY_VECTOR = new Vector<>();

    Vector<Replaceable> allReplaceables()
    {
        // There are summary-tables whose only contents are the "Inherited Entities".  When that
        // occurs, the 'tableOpen' and 'tableClose' NodeIndex-instances will be null

        if (tableOpen == null) return EMPTY_VECTOR;

        Vector<HTMLNode>    newTable            = new Vector<>();
        DotPair             oldTableLocation    = new DotPair(tableOpen.index, tableClose.index);

        newTable.add(tableOpen.n);
        newTable.add(NEW_LINE);
        newTable.addAll(headerRow);
        newTable.add(NEW_LINE);

        for (Vector<HTMLNode> row : tableRows)
        {
            newTable.addAll(row);
            newTable.add(NEW_LINE);
        }

        newTable.add(tableClose.n);
        newTable.add(NEW_LINE);

        Vector<Replaceable> ret = new Vector<>();
        ret.add(cinzelH3);
        ret.add(Replaceable.create(oldTableLocation, newTable));

        return ret;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // THE NEW-THING: Garbage-Collector Helper?
    // ********************************************************************************************
    // ********************************************************************************************
    // 
    // Does this help?  Is this "good" for the Garbage-Collect?  Is this going to speed it up,
    // or slow it down?  This is just a "C-Styled" FREE or DESTORY method...
    // It isn't publicly visible anyway...

    void clear()
    {
        // public final TagNodeIndex tableOpen;
        if (tableOpen != null) tableOpen.n = null;

        // public final TagNodeIndex tableClose;
        if (tableClose != null) tableClose.n = null;
    
        // final Vector<HTMLNode> headerRow;
        if (headerRow != null) headerRow.clear();

        // final TagNodeIndex cinzelH3;
        if (cinzelH3 != null) cinzelH3.n = null;
    
        // private Vector<Vector<HTMLNode>> tableRows = new Vector<>();
        if (tableRows != null)
        {
            for (Vector<HTMLNode> v : tableRows) if (v != null) v.clear();

            tableRows.clear();
            tableRows = null;
        }
    
        // private Vector<ENTITY> rowEntities = new Vector<>();
        if (rowEntities != null) { rowEntities.clear(); rowEntities = null; }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // DEBUG-PRINTING
    // ********************************************************************************************
    // ********************************************************************************************


    private static final String STARS =
        BYELLOW + "\n*****************************************\n" + RESET;

    /**
     * Prints an abbreviated-version of the contents of this instance, to a user-provided
     * {@code Appendable}.  If the HTML requires more than four lines of text, only the first four
     * lines are printed.
     * 
     * @param a This may be any Java Appendable.  If an {@code IOException} is thrown while writing
     * to this {@code Appendable}, it will be caught an wrapped in an
     * {@code IllegalArgumentException}, with the {@code IOException} set as the {@code cause}.
     * 
     * @throws IllegalArgumentException If {@code 'a'} throws an {@code IOException}
     * 
     * @see StrPrint#firstNLines(String, int)
     * @see Util#pageToString(Vector)
     * @see StrIndent#indent(String, int)
     */
    public void debugPrint(Appendable a)
    {
        try
        {
            if (tableType != null) a.append
                (BCYAN + "this.tableType: " + RESET + this.tableType.toString() + "\n");
            else
                a.append(BRED + "this.tableType is null" + RESET);

            if (tableOpen != null) a.append
                (BCYAN + "this.tableOpen: " + RESET + this.tableOpen.n.str + "\n");
            else
                a.append(BRED + "this.tableOpen is null" + RESET);

            if (tableClose != null) a.append
                (BCYAN + "this.tableClose: " + RESET + this.tableClose.n.str + "\n");
            else
                a.append(BRED + "this.tableClose is null" + RESET);

            if (cinzelH3 != null) a.append
                (BCYAN + "this.cinzelH3: " + RESET + this.cinzelH3.n.str + "\n");
            else
                a.append(BRED + "this.cinzelH3 is null" + RESET);

            if (headerRow != null) a.append(
                STARS + BCYAN + "this.headerRow:" + RESET + STARS +
                StrPrint.firstNLines(Util.pageToString(headerRow), 4) +
                '\n'
            );

            for (int i=0; i < tableRows.size(); i++)

                a.append(
                    BCYAN + "TABLE ROW " + (i+1) + RESET + '\n' +
                    BGREEN + "HTML:\n" + RESET +
                    StrIndent.indent
                        (Util.pageToString(tableRows.elementAt(i)).replace("\n", "\\n"), 4) +
                    '\n' +
                    BGREEN + "ENTITY:\n" + RESET +
                    StrIndent.indent
                        (rowEntities.elementAt(i).toString(PF.UNIX_COLORS | PF.JOW_INSTEAD), 4) +
                    '\n'
                );
        }
        catch (java.io.IOException ioe)
        {
            throw new IllegalArgumentException(
                ioe
            );
        }
    }

    
    /**
     * A really great way to view the contents of this class - <I>in just one page of text</I>.
     * 
     * @param numCharsWide The maximum line width to be printed to terminal.  This
     * number must be between 60 and 150, or else an exception shall throw.
     * 
     * @return The contents of this class-instance, as a {@code String}
     * 
     * @throws IllegalArgumentException If the parameter 'numCharsWide' was not passed a value 
     * within the aforementioned range.
     * 
     * @see StrPrint#printListAbbrev(Iterable, int, int, boolean, boolean, boolean)
     * @see StrPrint#printListAbbrev(Iterable, IntTFunction, int, int, boolean, boolean, boolean)
     */
    public String debugPrintDense(final int numCharsWide)
    {
        if ((numCharsWide < 60) || (numCharsWide > 150)) throw new IllegalArgumentException
            ("Parameter 'numCharsWide' wasn't passed a value between 60 and 150: " + numCharsWide);

        return
            "rowEntities.size(): " + rowEntities.size() + '\n' +
            "rowEntities Vector Contents:" + // '\n' is automatically added
                StrPrint.printListAbbrev(rowEntities, numCharsWide, 4, false, true, true) + '\n' +
            "tableRows.size(): " + tableRows.size() + '\n' +
            "tableRows Vector Contents:" + // '\n' is automatically added
                StrPrint.printListAbbrev(
                    tableRows,
                    (int i, Vector<HTMLNode> tableRow) -> Util.pageToString(tableRow),
                    numCharsWide, 4, false, true, true
                );
    }

    /**
     * Converts the contents of this class into a {@code String}
     * @return A Printable-{@code String}
     * @see #debugPrintDense(int)
     */
    public String toString()
    {
        return
            "tableType:  " + tableType + '\n' +
            "tableOpen:  " + tableOpen.toString() + '\n' +
            "tableClose: " + tableClose.toString() + '\n' +
            "headerRow:  " + StrPrint.abbrevEndRDSF(Util.pageToString(headerRow), 120, false) +
                '\n' +
            debugPrintDense(120);
    }
}