package Torello.Java.Additional;

import Torello.Java.*;
import Torello.JavaDoc.LinkJavaSource;

/**
 * This is a parent class of the 'Multiple Return Type' classes. ({@code Ret0 ... Ret8})  This
 * class provides some basic functionality to its descendants, namely: {@link #toString()}, 
 * {@link #hashCode()} and {@link #equals(Object)}.
 */
public abstract class MultiType
    implements java.io.Serializable, Cloneable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID>  */
    protected static final long serialVersionUID = 1;

    MultiType() { }


    // This, admittedly is a little obnoxious, but it allows there to be a "parent" super-type of
    // both RetN and TupleN.  Since only one of these is Read-Write, their "get-array" method is
    // not completely identical.  The Immutable-ReadOnly one can cache the array, while the
    // Read-Write version has to recreate the array everytime.

    abstract Object[] asArrayInternal();
    abstract Object[] asArrayMain();

    /**
     * All implementations of this {@code abstract} can indicate which of the {@link RetN} or
     * {@link TupleN} instances they are, by returning the number of fields they hold using this
     * method.
     * 
     * @return The number of fields contained by the class that is implementing {@code 'this'}
     * instance.  So for example, an instance of {@link Tuple5} would produce {@code '5'}, if this
     * method were called; and {@link Ret3} would produce {@code '3'}, and so on and so forth.
     */
    public abstract int n();

    /**
     * Retrieve the contents of the instance-descendant class, as an array.
     * 
     * @return Returns the {@code 'this'} instance' fields {@code 'a', 'b', 'c'} etc... as an
     * {@code Object[]} array.
     */
    public Object[] asArray()
    { return asArrayMain(); }

    /**
     * This will return an instance of {@code Object} which represents the
     * <CODE>i<SUP>th</SUP></CODE> instance-field from whatever {@link RetN} or {@link TupleN}
     * implementation this method has been invoked.
     * 
     * <BR /><BR />If {@code 'this'} instance were a {@link Ret5}, and {@code '3'} were passed to
     * parameter {@code 'i'}, then the value in {@link Ret5#c} would be returned.
     * 
     * <BR /><BR />If a call to {@code 'get'} is made from {@link Tuple2}, and {@code '3'} were
     * passed to {@code 'i'}, then an {@code IndexOutOfBoundsException} would throw.
     * 
     * @param i This specifies which field of the instance is being requested.
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color:red;'>Important:</B> Unlike a Java array, when a {@code '1'} is passed to
     * this parameter, it is requesting the first field in this instance.  Passing a value of
     * {@code '0'} shall cause an {@code IndexOutOfBoundsException} throw.
     * </DIV>
     * 
     * @return This returns the <CODE>i<SUP>th</SUP></CODE> field of this class.
     * 
     * @throws IndexOutOfBoundsException if {@code 'i'} is zero or negative, or greater than
     * the value of {@code 'N'} for whichever {@link RetN} or {@link TupleN} class is being used.
     * 
     * <BR /><BR />If {@code 'this'} is an instance of {@link Tuple5}, then a value of 6 or greater
     * would force this exception to throw.
     * 
     * @see #get(int, Class)
     * @see #GET(int)
     */
    public abstract Object get(int i);

    // This does a check for the above method that is needed by both TupleN and RetN
    void CHECK_GET(int i)
    {
        if (i < 1)
        {
            // This is actually unreachable code, because Ret0's & Tuple0's "get" check for this
            // case, and throw the exception themselves.  I'm leaving this here anyways, as a
            // reminder to what is going on.  (By "unreachable" - I'm talking about the first 'if'
            // branch, not the 'else')

            if (n() == 0) throw new IndexOutOfBoundsException 
                ("You may not invoke 'get' on a Tuple or Ret of size 0");

            else throw new IndexOutOfBoundsException(
                "You have passed " + i + " to parameter i.  This number must be " +
                ((n() > 1)
                    ? ("between 1 and " + n())
                    : "must be exactly 1")
            );
        }

        else if (i > n())
        {
            // Same as above, this 'if' will never execute, because Ret0.get() checks for this
            // already itselve (as does Tuple0.get).  The following 'else' would execute if the
            // user screwed up, and called "get(i)", with an 'i' that was out of range.

            if (n() == 0) throw new IndexOutOfBoundsException 
                ("You may not invoke 'get' on a Tuple or Ret of size 0");

            else throw new IndexOutOfBoundsException(
                "You have requested the " + StrPrint.ordinalIndicator(i) + " field of " +
                "this class instance-fields, but unfortunately there " + 
                ((n() > 1)
                    ? ("are only " + n() + " fields.")
                    : ("is only 1 field.")
                )
            );
        }
    }

    /**
     * This provides a quick way to cast the field to the requested class.  This may be quicker
     * typing than using an actual cast, because it will not generate a compiler warning about
     * unchecked casts.  If the cast fails, it will throw the usual {@code ClassCastException}.
     * 
     * @param i This specifies which field of the implementing {@code RetN} is being requested.
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color:red;'>Important:</B> Unlike a Java array, when a {@code '1'} is passed to
     * this parameter, it is requesting the first field in the {@code RetN}.  Passing a value of
     * {@code '0'} shall case an {@code IndexOutOfBoundsException} exception.
     * </DIV>
     * 
     * @return This returns the <CODE>i<SUP>th</SUP></CODE> field of this class.
     * 
     * @throws IndexOutOfBoundsException if {@code 'i'} is zero or negative, or greater than
     * the value of {@code 'N'} for whichever {@code RetN} class is being used.  If
     * {@code 'this'} is an instance of {@code Ret5}, then a value of 6 or greater will cause this
     * exception to throw.
     * 
     * @throws ClassCastException If the field cannot be cast to the class provided.
     * 
     * @see #get(int)
     * @see #GET(int)
     */
    public final <T> T get(int i, Class<T> c) { return c.cast(get(i)); }

    /**
     * This is <I><B STYLE='color:red;'>more magic</B></I> with Java's Type-Inferencing being
     * applied to a Generic-Cast.  Note that this method works a lot like (but not identical to)
     * the later Java {@code 'var'} syntax.  Here, Java's Type-Inference Mechanism (inside the
     * compile-time, not run-time, logic) will cast the result of this method to whatever type is
     * on the left hand-side of the assignment.
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color:red;'>Type-Inferencing:</B> Remember that the Java-Compiler will output a
     * Compile-Time Error if it appears that it cannot infer type-parameter {@code 'T'}.
     * </DIV>
     * 
     * <BR /><DIV CLASS=JDHintAlt>
     * <B STYLE='color:red;'>Run-Time Casting:</B> This method will throw a Run-Time
     * {@code 'ClassCastException'}, if the cast fails.
     * </DIV>
     *
     * @param <T> This Type-Parameter is inferred by whatever assignment is taking place, or however
     * the result of this method is being applied, programatically.  More can be read about Java's
     * Compile-Time Type-Inferencing Mechanism on the Oracle Website.
     * 
     * @param i This specifies which field of the implementing {@code RetN} is being requested.
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color:red;'>Important:</B> Unlike a Java array, when a {@code '1'} is passed to
     * this parameter, it is requesting the first field in the {@code RetN}.  Passing a value of
     * {@code '0'} shall case an {@code IndexOutOfBoundsException} exception.
     * </DIV>
     * 
     * @return This returns the <CODE>i<SUP>th</SUP></CODE> field of this class.
     * 
     * @throws IndexOutOfBoundsException if {@code 'i'} is zero or negative, or greater than
     * the value of {@code 'N'} for whichever {@code RetN} class is being used.  If
     * {@code 'this'} is an instance of {@code Ret5}, then a value of 6 or greater will cause this
     * exception to throw.
     * 
     * @throws ClassCastException If the <CODE>i<SUP>th</SUP></CODE> field of this class cannot be
     * cast to <I>the type that is inferred for Type-Parameter {@code 'T'}.</I>
     */
    @SuppressWarnings("unchecked")
    public final <T> T GET(int i) { return (T) get(i); }

    /**
     * Compares {@code 'this'} with another Java Object for equality.
     * @param other Any Java Object.
     * @return If {@code 'this'} instance is equal to the {@code 'other'} instance.
     */
    public boolean equals(Object other)
    {
        if (this == other) return true;

        if (! (other instanceof MultiType)) return false;

        MultiType o = (MultiType) other;

        if (o.n() != this.n()) return false;

        Object[] theseFields = asArray();
        Object[] thoseFields = o.asArray();


        // Keep this in mind - Three lines ago, the value of n() was already checked!
        // if (theseFields.length != thoseFields.length) throw new UnreachableError();

        for (int i=0; i < theseFields.length; i++)

            if (theseFields[i] == thoseFields[i])
                continue;

            else if (
                        ((theseFields[i] != null) && (thoseFields[i] != null))
                        &&
                        (theseFields[i].getClass() == thoseFields[i].getClass())
                        &&
                        theseFields[i].equals(thoseFields[i])
                    )
                continue;

            else
                return false;

        return true;
    }

    /**
     * Builds a hash-code to fulfill Java's {@code java.lang.Object} requirement.  This variant of
     * a hash function simply computes a hashcode for the first two non-null fields of this 
     * instance, and returns their sum.
     * 
     * <BR /><BR />If there aren't at least two non-null fields in this instance, then the hashcode
     * for however many have been computed (READ: either 0, or 1) is returned.
     * 
     * @return a hash-code that may be used for sets and maps like {@code java.util.Hashtable} and
     * {@code java.util.HashSet}.
     */
    @Override
    public int hashCode()
    {
        // This is the value returned.
        int hashCode    = 0;
        int count       = 0;

        for (Object field : asArray())

            if (field != null)
            {
                hashCode += field.hashCode();

                // Once two Hash Code's have been computed return the 'SUM' of them.
                if (++count == 2) return hashCode;
            }

        return hashCode;
    }

    /**
     * Converts this instance of the implementing {@code RetN} to a {@code String}.
     * @return This instance-object as a {@code String}.
     */
    @Override
    @LinkJavaSource(handle="MultiTypeToString")
    public String toString()
    { return MultiTypeToString.run(this.asArray(), this.n()); }

    /**
     * Clones the contents of {@code 'this'} instance of.
     * @return A clone copy of {@code 'this'} object.
     */
    public abstract Object clone();
}