package Torello.Java.Additional;

import Torello.Java.FileRW;
import Torello.Java.LFEC;
import Torello.Java.Additional.Ret2;
import Torello.Java.ReadOnly.ReadOnlyList;

import Torello.JavaDoc.CSSLinks;
import Torello.JavaDoc.LinkJavaSource;

import java.util.stream.Stream;
import java.util.Objects;

import static Torello.Java.C.BCYAN;
import static Torello.Java.C.RESET;
import static Torello.JavaDoc.Entity.FIELD;

/**
 * A Data-Class for representing a Java {@code '.class'} File's Constant-Pool.
 * <EMBED CLASS='external-html' DATA-FILE-ID=CP_TOP_TABLE>
 */
public class ConstantPool
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Static Inner Class: Reference
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * A Data-Class which can represent:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B>{@link TAG_FIELD_REF}</B> (9)</LI>
     * <LI><B>{@link TAG_METHOD_REF}</B> (10)</LI>
     * <LI><B>{@link TAG_INTERFACE_METHOD_REF}</B> (11)</LI>
     * </UL>
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_REF_CGPT_DESC>
     */
    @CSSLinks(FileNames="ConstantPool.css")
    public static class Reference
    {
        // ****************************************************************************************
        // ****************************************************************************************
        // Instance Fields
        // ****************************************************************************************
        // ****************************************************************************************


        /** The Constant-Pool Table-Index where this {@code Reference} is located */
        public final int tableIndex;

        /** 
         * The Constant-Pool Tg-Kind associated with this instance.  This Java {@code 'byte'} may
         * take only one of only three values: 
         * 
         * <BR /><BR /><UL CLASS=JDUL>
         * <LI><B>{@link TAG_FIELD_REF}</B> (9)</LI>
         * <LI><B>{@link TAG_METHOD_REF}</B> (10)</LI>
         * <LI><B>{@link TAG_INTERFACE_METHOD_REF}</B> (11)</LI>
         * </UL>
         * 
         * <EMBED CLASS='external-html' DATA-FILE-ID=CP_IN_TYPE_TAG_NOTE>
         */
        public final byte tag;

        /**
         * The {@code 'className'} field specifies in which class (where) the Method or Field has
         * actuallly been defined.  For most methods and fields, the {@code 'className'} is the 
         * same as the actual class whose Constant-Pool was loaded into an instance of
         * {@code ConstantPool}.
         * 
         * <BR /><BR />If the field or method reference is defined in an ancestor or parent class,
         * then this field would contain the name of that ancestor.
         */
        public final String ownerClassName;

        /**
         * Constant-Pool Table-Index where owner's {@code className 'Class Constant'} was
         * stored
         */
        public final int ownerClassIndex;

        /**
         * Constant-Pool Table-Index identifying where the {@code UTF-8} Class'
         * <B STYLE='color; red;'>Name-As-A-{@code String}</B> is located.
         */
        public final int ownerClassNameUTF8Index;

        /**
         * An intermediate Constant-Pool Index-Pair that points to a Name UTF-8 Constant, and 
         * a Type-Descriptor Constant.
         */
        public final int nameAndTypeIndex;

        /**
         * This is just the name of the Method or Field.  Some common method names are (just for
         * example) {@cpde 'toString'} and {@code 'equals'}.  This particular Nested-Type has three
         * fields of it's own, named: {@code 'className, 'name'} and {@code 'descriptor'}.
         */
        public final String name;

        /**
         * Constant-Pool Table-Index identifying where the {@code UTF-8} Method's or Field's
         * <B STYLE='color; red;'>Name-As-A-{@code String}</B> is located.
         */
        public final int nameUTF8Index;

        /**
         * This is the descriptor of a method or field, which is Java single-line description
         * which includes type-information stored as a simple {@code String}.  A descriptor is of
         * the format:
         * 
         * <BR /><BR /><UL CLASS=JDUL>
         * <LI>For a method, the descriptor specifies the parameter types and return type.</LI>
         * <LI>For a field, the descriptor specifies the field type.</LI>
         * </UL>
         */
        public final String descriptor;

        /**
         * Constant-Pool Table-Index identifying where the {@code UTF-8} Descriptor's
         * <B STYLE='color; red;'>Description-As-A-{@code String}</B> is located.
         */
        public final int descriptorUTF8Index;


        // ****************************************************************************************
        // ****************************************************************************************
        // Package-Private Constructor
        // ****************************************************************************************
        // ****************************************************************************************


        Reference(
                final ReadOnlyList<Byte>    tags,
                final ReadOnlyList<Object>  values,
                final int                   tableIndex
            )
        {
            this.tableIndex = tableIndex;

            // May only be one of three values: TAG_FIELD_REF, TAG_METHOD_REF or
            // TAG_INTERFACE_METHOD_REF
            // 
            // public final byte tag;

            this.tag = tags.get(tableIndex);

            // temporary variable
            @SuppressWarnings("unchecked")
            final Ret2<Integer, Integer> methodOrFieldConstantR2 =
                (Ret2<Integer, Integer>) values.get(tableIndex);

            this.ownerClassIndex = methodOrFieldConstantR2.a;


            // Constant-Pool Table-Index identifying where the UTF-8 Class'
            // Name-As-A-String is located.
            // 
            // public final byte ownerClassNameUTF8Index;

            this.ownerClassNameUTF8Index = (Integer) values.get(Reference.this.ownerClassIndex);


            // The 'className' field specifies in which class (where) the Method or Field has
            // actuallly been defined.
            // 
            // If the field or method reference is defined in an ancestor or parent class,
            // then this field would contain the name of that ancestor.
            // 
            // public final String ownerClassName;

            this.ownerClassName = (String) values.get(this.ownerClassNameUTF8Index);

            // public final int nameAndTyeIndex;
            this.nameAndTypeIndex = methodOrFieldConstantR2.b;

            // Temporary Local Variable
            @SuppressWarnings("unchecked")
            final Ret2<Integer, Integer> nameAndTypeConstantR2 =
                (Ret2<Integer, Integer>) values.get(methodOrFieldConstantR2.b);


            // Constant-Pool Table-Index identifying where the UTF-8 Method's or Field's
            // Name-As-A-String is located.
            // 
            // public final byte nameUTF8Index;

            this.nameUTF8Index = nameAndTypeConstantR2.a;


            // This is just the name of the Method or Field.  Some common method names are (for
            // example) 'toString' and 'equals'.  This particular Nested-Type has three fields of
            // it's own, named: 'className, 'name' and 'descriptor'.
            // 
            // public final String name;

            this.name = (String) values.get(this.nameUTF8Index);


            // Constant-Pool Table-Index identifying where the UTF-8 Descriptor's
            // Description-As-A-String is located.
            //
            // public final byte descriptorUTF8Index;

            this.descriptorUTF8Index = nameAndTypeConstantR2.b;


            // This is the descriptor of a method or field.  A descriptor is of the format:
            // * For a method, the descriptor specifies the parameter types and return type.
            // * For a field, the descriptor specifies the field type.
            // 
            // public final String descriptor;

            this.descriptor = (String) values.get(this.descriptorUTF8Index);
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // java.lang.Object
        // ****************************************************************************************
        // ****************************************************************************************


        /**
         * Converts {@cpode 'this'} instance into a {@code java.lang.String}.
         * @return The data-content of this record, as a {@code String}, for printing.
         */
        public final String toString()
        {
            return
                "Reference:\n" +
                "{\n" +
                "    tag:             " + tag + " - " + ConstantPool.tagNames.get(tag) + '\n' +
                "    Table-Index:     " + this.tableIndex + '\n' +                
                "    ownerClassName:  " + this.ownerClassName + '\n' +
                "    name:            " + this.name + '\n' +
                "    descriptor:      " + this.descriptor + '\n' +
                "}";
        }

        /**
         * Checks for {@code Object}-equality between {@code 'this'} instance and {@code 'other'}.
         * 
         * @param other This may be any Java-{@code Object}, but only an instance of
         * {@code ConstantPool.Reference} will permit this method to return {@code TRUE}.
         * 
         * @return {@code TRUE} if-and-only-if parameter {@code 'other'} is an instance of
         * {@code Reference} and has identical field values.
         */
        public boolean equals(Object other)
        {
            if (!(other instanceof Reference)) return false;

            Reference r = (Reference) other;

            return
                    (this.tag == r.tag)

                &&  Objects.equals(this.ownerClassName, r.ownerClassName)
                &&  (this.ownerClassIndex           == r.ownerClassIndex)
                &&  (this.ownerClassNameUTF8Index   == r.ownerClassNameUTF8Index)

                &&  Objects.equals(this.name, r.name)
                &&  (this.nameUTF8Index == r.nameUTF8Index)

                &&  Objects.equals(this.descriptor, r.descriptor)
                &&  (this.descriptorUTF8Index == r.descriptorUTF8Index);
        }

        /**
         * Generates a Hash-Code.
         * @return An integer Hash-Code that may be used by Java's Hashing Data-Structures.
         */
        public int hashCode()
        {
            return this.name.hashCode() +
                this.ownerClassNameUTF8Index +
                this.nameUTF8Index +
                this.descriptorUTF8Index;
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Inner Class: Reference
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * A class representing the "Reference-Kind" values associated with a {@code Method-Handle}.
     * 
     * <p>Method-Handles use "Reference-Kinds" to describe the type of operation they perform, 
     * such as accessing fields or invoking methods.</p>
     */
    @CSSLinks(FileNames="ConstantPool.css")
    public static class MethodHandle
    {
        // ****************************************************************************************
        // ****************************************************************************************
        // Instance Fields
        // ****************************************************************************************
        // ****************************************************************************************


        /** The Constant-Pool Table-Index where this {@code Method-Handle} is located */
        public final int tableIndex;

        /**
         * Contains a Java {@code byte}.  Guaranteed to be equal to one of the 9 {@code static} 
         * {@code byte}-Constant Fields (the various "kinds").
         * 
         * <BR /><BR />The complete list of <CODE>Method Handle</CODE> 'kinds' may be viewed in
         * the documentation for the {@code static} field {@link #handleKindNames}.  The table in
         * the javadoc Documentation-Table there contains 'stringified' versions of all of the 
         * {@code static} 'kind' {@code byte} constants also provided in this class.
         */
        public final byte kind;

        /**
         * Points to a Constant in the Constant-Pool Table.  This Index-Pointer must be a pointer 
         * to one of the following: 
         * {@link #TAG_FIELD_REF Field-Reference}, 
         * {@link #TAG_METHOD_REF Method-Reference} or a
         * {@link #TAG_INTERFACE_METHOD_REF Interface-Method-Reference}
         */
        public final int referencedIndex;

        /**
         * This contains the actual Tag-Kind (as a Java {@code byte}) of the Reference to which 
         * this handle points.  This particular field may hold only one of three different values:
         * <B>
         * {@link #TAG_FIELD_REF 9},
         * {@link #TAG_METHOD_REF 10} or
         * {@link #TAG_INTERFACE_METHOD_REF 11}
         * </B>
         */
        public final byte referencedTagKind;

        /** The name of the method or field to which this reference points, as a {@code String} */
        public final String referencedName;


        // ****************************************************************************************
        // ****************************************************************************************
        // Static, Final Fields: The 9 different Method-Handle "Kinds"
        // ****************************************************************************************
        // ****************************************************************************************


        /** 
         * Reference-Kind value for {@code getField}. 
         * Used to retrieve an instance field from an object.
         */
        public static final byte KIND_GET_FIELD = 1;

        /** 
         * Reference-Kind value for {@code getStatic}. 
         * Used to retrieve a static field from a class.
         */
        public static final byte KIND_GET_STATIC = 2;

        /** 
         * Reference-Kind value for {@code putField}. 
         * Used to assign a value to an instance field.
         */
        public static final byte KIND_PUT_FIELD = 3;

        /** 
         * Reference-Kind value for {@code putStatic}. 
         * Used to assign a value to a static field.
         */
        public static final byte KIND_PUT_STATIC = 4;

        /** 
         * Reference-Kind value for {@code invokeVirtual}. 
         * Used to invoke an instance method via virtual dispatch.
         */
        public static final byte KIND_INVOKE_VIRTUAL = 5;

        /** 
         * Reference-Kind value for {@code invokeStatic}. 
         * Used to invoke a static method.
         */
        public static final byte KIND_INVOKE_STATIC = 6;

        /** 
         * Reference-Kind value for {@code invokeSpecial}. 
         * Used to invoke an instance method directly (e.g., via {@code super} calls).
         */
        public static final byte KIND_INVOKE_SPECIAL = 7;

        /** 
         * Reference-Kind value for {@code newInvokeSpecial}. 
         * Used to invoke a class constructor.
         */
        public static final byte KIND_NEW_INVOKE_SPECIAL = 8;

        /** 
         * Reference-Kind value for {@code invokeInterface}. 
         * Used to invoke a method declared in an interface.
         */
        public static final byte KIND_INVOKE_INTERFACE = 9;


        // ****************************************************************************************
        // ****************************************************************************************
        // Static, Final Fields: Lookup Table
        // ****************************************************************************************
        // ****************************************************************************************


        /**
         * This list is contains exactly 9 non-null entries.  Each entry in this list corresponds
         * to one of the 9 Handle "Kind's"
         * 
         * <EMBED CLASS='external-html' DATA-FILE-ID=CP_MH_KIND_NAMES>
         */
        @SuppressWarnings("unchecked")
        @LinkJavaSource(handle="MethodHandleData")
        public static final ReadOnlyList<String> handleKindNames = 
            (ReadOnlyList<String>) LFEC.readObjectFromFile_JAR
                (ConstantPool.class, "data-files/data5.roaldat", true, ReadOnlyList.class);


        // ****************************************************************************************
        // ****************************************************************************************
        // Package-Private Constructor
        // ****************************************************************************************
        // ****************************************************************************************


        MethodHandle(
                final ReadOnlyList<Byte>    tags,
                final ReadOnlyList<Object>  values,
                final int                   tableIndex
            )
        {
            // The Constant-Pool Table-Index where this Method-Handle is located
            // public final int tableIndex;

            this.tableIndex = tableIndex;


            @SuppressWarnings("unchecked")
            final Ret2<Byte, Integer> methHandleR2 =
                (Ret2<Byte, Integer>) values.get(tableIndex);


            // Contains a Java byte.  Guaranteed to be equal to one of the 9 static
            // byte-Constant Fields (the various "kinds"), listed in this class.
            // 
            // public final byte kind;

            this.kind = methHandleR2.a;


            // Points to a Constant in the Constant-Pool Table.  This Index-Pointer must be a pointer 
            // to one of the following: TAG_FIELD_REF, TAG_METHOD_REF, TAG_INTERFACE_METHD_REF
            // 
            // public final int referencedIndex;

            this.referencedIndex = methHandleR2.b;


            // This contains the actual Tag-Kind (as a Java byte) of the Reference to which 
            // this handle points.  This particular field may hold only one of three different values:
            // TAG_FIELD_REF, TAG_METHOD_REF, TAG_INTERFACE_METHD_REF
            // 
            // public final byte referencedTagKind;

            this.referencedTagKind = tags.get(this.referencedIndex);

            @SuppressWarnings("unchecked")
            final Ret2<Integer, Integer> referenceR2 = (Ret2<Integer, Integer>)
                values.get(this.referencedIndex);

            @SuppressWarnings("unchecked")
            final Ret2<Integer, Integer> nameAndTypeR2 =
                (Ret2<Integer, Integer>) values.get(referenceR2.b);


            // The name of the method or field to which this reference points, as a String
            // public final String referencedName;

            this.referencedName = (String) values.get(nameAndTypeR2.a);
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // java.lang.Object
        // ****************************************************************************************
        // ****************************************************************************************


        /**
         * Checks for {@code Object}-equality between {@code 'this'} instance and {@code 'other'}.
         * 
         * @param other This may be any Java-{@code Object}, but only an instance of
         * {@code ConstantPool.MethodHandle} will permit this method to return {@code TRUE}.
         * 
         * @return {@code TRUE} if-and-only-if parameter {@code 'other'} is an instance of
         * {@code MethodHandle} and has identical field values.
         */
        public boolean equals(Object other)
        {
            if (! (other instanceof MethodHandle)) return false;

            final MethodHandle o = (MethodHandle) other;

            return
                    (this.tableIndex == o.tableIndex)
                &&  (this.kind == o.kind)
                &&  (this.referencedIndex == o.referencedIndex)
                &&  (this.referencedTagKind == o.referencedTagKind)
                &&  Objects.equals(this.referencedName, o.referencedName);
        }

        /**
         * Generates a hash-code.  Fulfills Java's Hash-Code reuirement.
         * @return a good attempt at an efficient, but fair hashcode.
         */
        public int hashCode()
        { return this.tableIndex + this.kind + this.referencedIndex; }

        /**
         * Generate a human readable {@code String}.
         * @return {@code 'this'} instance as a Java String
         */
        public String toString()
        {
            return
                "Method Handle:\n" +
                "{\n" +
                "    Handle's Table-Index:               " + this.tableIndex + '\n' +
                "    Referenced Item's Name:             " + this.referencedName + '\n' +
                "    Handle Kind:                        " + this.kind + '\n' +

                "    Handle Kind's Name:                 " +
                    MethodHandle.handleKindNames.get(this.kind) + '\n' +

                "    Referenced Item's Table-Index:      " + this.referencedIndex + '\n' +
                "    Referenced Item's Kind (as byte):   " + this.referencedTagKind + '\n' +

                "    Referenced Item's Kind (as String): " +
                    ConstantPool.tagNames.get(this.referencedTagKind) + '\n' +
                "}";
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Inner Class: Dynamic
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Used to represent Java {@code '.class'} File Constant's whose Tag-Kind is:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B>{@link #TAG_DYNAMIC}</B> ({@code 17})</LI>
     * <LI><B>{@link #TAG_INVOKE_DYNAMIC}</B> ({@code 18})</LI>
     * </UL>
     */
    public static class Dynamic 
    {
        // ****************************************************************************************
        // ****************************************************************************************
        // Instance Fields
        // ****************************************************************************************
        // ****************************************************************************************


        /** The Constant-Pool Table-Index where this {@code Reference} is located */
        public final int tableIndex;

        /**
         * The Constant-Pool Tg-Kind associated with this instance.  This Java {@code 'byte'} may
         * take one of only two values:
         * 
         * <BR /><BR /><UL CLASS=JDUL>
         * <LI><B>{@link #TAG_DYNAMIC}</B> ({@code 17})</LI>
         * <LI><B>{@link #TAG_INVOKE_DYNAMIC}</B> ({@code 18})</LI>
         * </UL>
         * 
         * <EMBED CLASS='external-html' DATA-FILE-ID=CP_IN_TYPE_TAG_NOTE>
         */
        public final byte tag;

        /**
         * This field will be assigned {@code TRUE} if-and-only-if field {@link #tag} has been
         * assigned <B>{@code 17}</B>.  Tthe only other value which may be assigned to field 
         * {@link #tag} is <B>{@code 18}</B>, when that field is equal to <B>{@code 18}</B>, this
         * field be {@code FALSE}.
         * 
         * <BR /><BR />{@code boolean} fields such as this are here purely to make life easier,
         * occasionally.
         */
        public final boolean dynamicOrInvokeDynamic;

        /**
         * The index into the Bootstrap Method Table, pointing to a bootstrap method
         * definition in the `.class` file attributes.
         */
        public final int bootstrapMethodIndex;

        /**
         * The index into the constant pool, pointing to a {@link #TAG_NAME_AND_TYPE}
         * Record / Structure that provides the name and type descriptor of this entry.
         * 
         * <BR /><BR />The Constant-Pool entry that is stored in the Table-Index specified by
         * the integer in {@code 'nameAndTypeIndex'} is actually a 4 Byte Integer-Pair.  The two
         * integers that comprise a "Name And Type" Constant (a "record" or "Structure") are simply
         * two Index-Pointers back into the Constant-Pool's Table.
         * 
         * <BR /><BR />The first Index-Pointer is to a {@code UTF-8 String} storing the "name" of
         * for the Method of the Method-Handle.  The second Index-Poniter points to a Table-Index 
         * which contains the Method-Type - also stored as a {@code UTF-8 String}.
         */
        public final int nameAndTypeIndex;

        /**
         * The Constant in the Constant-Pool which may be found at the index specified by field 
         * {@link #nameAndTypeIndex} is, itself, a "Record" of sorts; and contains two integer data
         * fields in its Record.  The first integer is a Table Index-Pointer to a "name", and is
         * represented by a {@code UTF-8} Table-Constant.
         * 
         * <BR /><BR />The Constant-Pool Table-Index for the {@code UTF-8 String} Constanta is
         * saved as an integer in this {@code public, final} field.
         * 
         * <BR /><BR />The second integer of the Two-Integer Data-Record
         * ({@link #nameAndTypeIndex}) stores a "Type as a String."  The index for that
         * {@code UTF-8 String}  is stored in the {@code public final} field {@link #typeIndex}.
         */
        public final int nameIndex;

        /**
         * This stores the Java 'type' for a Method-Handle as a {@cde UTF-8} Constant.  You should
         * review the documented explanations for the fields {@link #nameAndTypeIndex} and also for
         * {@link #nameIndex} for more information.
         */
        public final int typeIndex;

        /**
         * This stores the Method-Name of the Bootstrap-Method specified by this Method-Handle
         * instance.
         */
        public final String name;


        // ****************************************************************************************
        // ****************************************************************************************
        // Package-Private Constructor
        // ****************************************************************************************
        // ****************************************************************************************


        Dynamic(
                final ReadOnlyList<Byte>    tags,
                final ReadOnlyList<Object>  values,
                final int                   tableIndex
            )
        {
            // The Constant-Pool Table-Index where this Method-Handle is located
            // public final int tableIndex;

            this.tableIndex = tableIndex;

            this.tag = tags.get(tableIndex);

            this.dynamicOrInvokeDynamic = (this.tag == 17);

            @SuppressWarnings("unchecked")
            final Ret2<Integer, Integer> dynamicR2 =
                (Ret2<Integer, Integer>) values.get(tableIndex);

            this.bootstrapMethodIndex = dynamicR2.a;

            this.nameAndTypeIndex = dynamicR2.b;

            @SuppressWarnings("unchecked")
            final Ret2<Integer, Integer> nameAndTypeR2 =
                (Ret2<Integer, Integer>) values.get(nameAndTypeIndex);

            this.nameIndex = nameAndTypeR2.a;

            this.typeIndex = nameAndTypeR2.b;

            this.name = (String) values.get(this.nameIndex);
        }


        // ****************************************************************************************
        // ****************************************************************************************
        // java.lang.Object
        // ****************************************************************************************
        // ****************************************************************************************


        /** Check whether this instance equals parameter {@code 'other'} */
        public boolean equals(Object other)
        {
            if (! (other instanceof ConstantPool.Dynamic)) return false;

            ConstantPool.Dynamic o = (ConstantPool.Dynamic) other;

            return 
                    (this.tableIndex                == o.tableIndex)
                &&  (this.tag                       == o.tag)
                &&  (this.dynamicOrInvokeDynamic    == o.dynamicOrInvokeDynamic)
                &&  (this.bootstrapMethodIndex      == o.bootstrapMethodIndex)
                &&  (this.nameAndTypeIndex          == o.nameAndTypeIndex)
                &&  (this.nameIndex                 == o.nameIndex)
                &&  (this.typeIndex                 == o.typeIndex)
                &&  Objects.equals(this.name, o.name);
        }

        /** Generate a simple, efficient, hash-code for this instance. */
        public int hashCode()
        { return this.tableIndex + this.bootstrapMethodIndex + this.nameAndTypeIndex; }

        /** Generate a {@code java.lang.String} representation for this instance. */
        public String toString()
        {
            return
                "{\n" +
                "    tableIndex:             " + tableIndex + "\n" +
                "    tag:                    " + tag + " (" + (dynamicOrInvokeDynamic ? "Dynamic" : "Invoke-Dynamic") + ")\n" +
                "    dynamicOrInvokeDynamic: " + dynamicOrInvokeDynamic + "\n" +
                "    name:                   " + name + "\n" +
                "    bootstrapMethodIndex:   " + bootstrapMethodIndex + "\n" +
                "    nameAndTypeIndex:       " + nameAndTypeIndex + "\n" +
                "    nameIndex:              " + nameIndex + "\n" +
                "    typeIndex:              " + typeIndex + "\n" +
                "}";
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Instance Fields: PARALLEL-ARRAYS (all Public-Final Constants & ReadOnly)
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=CP_TABLE_SIZE> */
    public final int tableSize;

    /** <EMBED CLASS='external-html' DATA-FILE-ID=CP_TABLE_SIZE_BYTES> */
    public final int tableSizeBytes;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_TAGS>
     * @see #tagNames
     */
    public final ReadOnlyList<Byte> tags;


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_VALUES>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_VALUES_TYPE_NOTE>
     */
    public final ReadOnlyList<Object> values;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_DEREF_VALUES>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_DEREF_VAL_TABLE>
     */
    @LinkJavaSource(handle="DereferencedValue")
    public final ReadOnlyList<Object> dereferencedValues;

    /** Original Byte-Array Indices */
    public final ReadOnlyList<Integer> indices;

    /** <EMBED CLASS='external-html' DATA-FILE-ID=CP_INDICES_GROUP_BY> */
    public final ReadOnlyList<ReadOnlyList<Integer>> indicesGroupBy;


    // ********************************************************************************************
    // ********************************************************************************************
    // Static-Final Constants / ReadOnly Lookup-Tables as Lists.  (List-Index is the "Lookup Key")
    // ********************************************************************************************
    // ********************************************************************************************


    @SuppressWarnings("rawtypes")
    private static Ret2 dataFileR2 = LFEC.readObjectFromFile_JAR
        (ConstantPool.class, "data-files/data3.r2dat", true, Ret2.class);


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_TAG_NAMES>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_TAG_NAMES_TABLE>
     * @see #tags List of Types/Kinds for each Constant
     * @see #values List of Values for each Constant
     */
    @LinkJavaSource(handle="ConstantPoolData", entity=FIELD, name="tagNames")
    public static final ReadOnlyList<String> tagNames = dataFileR2.GET(1);


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_TAG_WIDTH_BYTES>
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_TAG_WB_TABLE>
     */
    @LinkJavaSource(handle="ConstantPoolData", entity=FIELD, name="tagWidthBytes")
    public static final ReadOnlyList<Byte> tagWidthBytes = dataFileR2.GET(2);


    // Don't need it.  References are loaded into memory now.  Erase it for the G.C.
    static { dataFileR2 = null; }


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Constants: This is the "inverse" of the "tagNames" List
    // ********************************************************************************************
    // ********************************************************************************************
    // 
    // 
    // NOTE: Here is what I said-to / asked Chat-GPT:
    // 
    // It's Monday.  I did a flurry of Round-House Kicks at L.A. Fitness yesterday.  It took 3
    // years of practice (it feels like) to be able to do that.  I have another Java-Doc
    // Help/Question for you.  It is about my ConstantPool class again.  Do you think you could
    // help me write some Java-Doc Comments?  Anywhere between 1 and three lines of Java-Doc would
    // be great.  I cannot think after such a huge breakfast!
    // 
    // Above question was followed-By the list of ...
    // `public static final byte` - Fields **BUT** WITHOUT the Java-Doc comments included below...
    // 
    // Below is how Chat-GPT replied to me (no changes were made to the output - not one character)

    /** 
     * Tag byte indicating the next constant in the table is a UTF-8 encoded {@code String}.
     * Typically used for identifiers such as names or other textual data.
     */
    public static final byte TAG_UTF_8 = 1;

    /** 
     * Tag byte indicating the next constant in the table is a 32-bit integer.
     * Used for numeric constants within the constant pool. 
     */
    public static final byte TAG_INTEGER = 3;

    /** 
     * Tag byte indicating the next constant in the table is a 32-bit floating-point number.
     * Represents constants of the {@code float} data type.
     */
    public static final byte TAG_FLOAT = 4;

    /** 
     * Tag byte indicating the next constant in the table is a 64-bit long integer.
     * Represents constants of the {@code long} data type.
     */
    public static final byte TAG_LONG = 5;

    /** 
     * Tag byte indicating the next constant in the table is a 64-bit double-precision floating-point number.
     * Represents constants of the {@code double} data type.
     */
    public static final byte TAG_DOUBLE = 6;

    /** 
     * Tag byte indicating the next constant in the table is a class reference.
     * Represents a {@code Class} or interface type.
     */
    public static final byte TAG_CLASS = 7;

    /** 
     * Tag byte indicating the next constant in the table is a {@code String} reference.
     * The referenced {@code String} is stored elsewhere in the constant pool.
     */
    public static final byte TAG_STRING = 8;

    /** 
     * Tag byte indicating the next constant in the table is a reference to a field.
     * Used for fields within a {@code Class} or interface.
     */
    public static final byte TAG_FIELD_REF = 9;

    /** 
     * Tag byte indicating the next constant in the table is a reference to a method.
     * Refers to methods defined in a {@code Class}.
     */
    public static final byte TAG_METHOD_REF = 10;

    /** 
     * Tag byte indicating the next constant in the table is a reference to an interface method.
     * Refers to methods declared within an interface.
     */
    public static final byte TAG_INTERFACE_METHOD_REF = 11;

    /** 
     * Tag byte indicating the next constant in the table is a name-and-type descriptor.
     * Encodes the name and type of a field or method.
     */
    public static final byte TAG_NAME_AND_TYPE = 12;

    /** 
     * Tag byte indicating the next constant in the table is a method handle.
     * Represents a reference to a method handle for dynamic invocation.
     */
    public static final byte TAG_METHOD_HANDLE = 15;

    /** 
     * Tag byte indicating the next constant in the table is a method type.
     * Encodes the method's descriptor, including parameter and return types.
     */
    public static final byte TAG_METHOD_TYPE = 16;

    /** 
     * Tag byte indicating the next constant in the table is a dynamic constant.
     * Represents a runtime-computed constant, often linked to lambdas or invokedynamic instructions.
     */
    public static final byte TAG_DYNAMIC = 17;

    /** 
     * Tag byte indicating the next constant in the table is an invoke-dynamic constant.
     * Represents a bootstrap method and dynamic call site for runtime resolution.
     */
    public static final byte TAG_INVOKE_DYNAMIC = 18;

    /** 
     * Tag byte indicating the next constant in the table is a module reference.
     * Encodes the name of a module within the constant pool.
     */
    public static final byte TAG_MODULE = 19;

    /** 
     * Tag byte indicating the next constant in the table is a package reference.
     * Encodes the name of a package within the constant pool.
     */
    public static final byte TAG_PACKAGE = 20;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_CONSTRUCTOR>
     * @param bArr A Class-File which has been loaded from disk into a memory, as a Java
     * {@code byte[]} Array.
     */
    @LinkJavaSource(handle="ConstPoolCtorHelper")
    @LinkJavaSource(handle="ReadConstant")
    @LinkJavaSource(handle="DereferencedValue")
    @LinkJavaSource(handle="Validate")
    public ConstantPool(final byte[] bArr)
    {
        RetN r = ConstPoolCtorHelper.construct(bArr);

        this.tags               = r.GET(1);
        this.values             = r.GET(2);
        this.dereferencedValues = r.GET(3);
        this.indices            = r.GET(4);
        this.indicesGroupBy     = r.GET(5);
        this.tableSizeBytes     = r.GET(6);

        this.tableSize = this.tags.size();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Converts the contents of an instance of this class into a User-Readable {@code String}.
     * @return A Java-{@code String} which explicates a Java {@code '.class'} File's Constant-Pool.
     */
    @LinkJavaSource(handle="CPToString")
    public String toString()
    { return CPToString.str(this.tags, this.values, this.indicesGroupBy); }

    /**
     * Checks for equality with another instance of {@code ConstantPool}.
     * 
     * @param other Any Java-{@code Object}, but only an instance of {@code ConstantPool} whose 
     * {@link #tags} and {@link #values} Array-Lists are equal will cause this method to return
     * {@code TRUE}.
     * 
     * @return {@code TRUE} if and only if the contents {@code 'this'} instance of Constant-Pool 
     * equals those found in parameter {@code 'other'}
     */
    public boolean equals(Object other)
    {
        if (! (other instanceof ConstantPool)) return false;

        ConstantPool o = (ConstantPool) other;

        return
                this.tags.equals(o.tags)
            &&  this.values.equals(o.values)
            &&  this.indices.equals(o.indices);
    }

    /**
     * Java's traditional Hash-Code generator Method.
     * 
     * @return a (plausibly unique) Hash-Code, which may be used for placing instances of
     * {@code ConstantPool} into Hash-Tables.
     */
    public int hashCode()
    {
        // No, this isn't any good... To-Do: Worry about it...
        int hash = 0;
        for (Byte tag : this.tags) if (tag != null) hash += tag;
        return hash;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Some Easy-To-Use and Easy-To-Write Getters
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieves the names of all Field-References which were listed in the Constant-Pool
     * table that was used to build {@code 'this'} instance.
     * 
     * @return A Java-{@code Stream} containing the names of any / all fields from the table.
     */
    @LinkJavaSource(handle="AllNames", name="getAllFieldNames")
    public Stream<String> allFieldNames()
    {
        return AllNames.getAllFieldNames(
            this.indicesGroupBy.get(ConstantPool.TAG_FIELD_REF),
            this.values
        );
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CP_GET_ALL_METHNAME>
     * 
     * @return A Java-{@code Stream<String>} containing the names of any / all methods and
     * "Method References" from the Constant-Pool Table.
     */
    @LinkJavaSource(handle="AllNames", name="getAllMethodNames")
    public Stream<String> allMethodNames()
    {
        return AllNames.getAllMethodNames(
            this.indicesGroupBy.get(ConstantPool.TAG_METHOD_REF),
            this.indicesGroupBy.get(ConstantPool.TAG_INTERFACE_METHOD_REF),
            this.values
        );
    }

    /**
     * All Constants in this Pool whose Tag-Kind are:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B>{@link #TAG_FIELD_REF}</B> (9)</LI>
     * </UL>
     * 
     * @return All Field-References contained by {@code 'this'} table.  The Java {@code Stream}
     * which is returned contains instances of {@link ConstantPool.Reference}.
     * 
     * @see #dereferencedValues
     * @see #indicesGroupBy
     */
    @SuppressWarnings("unchecked")
    public Stream<ConstantPool.Reference> allFields()
    {
        return this.indicesGroupBy
            .get(ConstantPool.TAG_FIELD_REF)
            .stream()
            .map((Integer index) -> (ConstantPool.Reference) this.dereferencedValues.get(index));
    }

    /**
     * All Constants in this Pool whose Tag-Kind are:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B>{@link #TAG_METHOD_REF}</B> (10)</LI>
     * <LI><B>{@link #TAG_INTERFACE_METHOD_REF}</B> (10)</LI>
     * </UL>
     * 
     * @return All Method-References contained by {@code 'this'} table.  The Java {@code Stream}
     * which is returned contains instances of {@link ConstantPool.Reference}. 
     * 
     * @see #dereferencedValues
     * @see #indicesGroupBy
     */
    @SuppressWarnings("unchecked")
    public Stream<ConstantPool.Reference> allMethods()
    {
        return Stream.concat(
                this.indicesGroupBy.get(ConstantPool.TAG_METHOD_REF).stream(),
                this.indicesGroupBy.get(ConstantPool.TAG_INTERFACE_METHOD_REF).stream()
            )
            .map((Integer index) -> (ConstantPool.Reference) this.dereferencedValues.get(index));
    }
}