package Torello.Java.Additional;

import java.lang.reflect.Field;

/**
 * The classes {@code Tuple1} and {@link Tuple0} are here merely for the convenience and the
 * possibility that an unknown sized tuple might be needed, and on occasion that unknown sized 
 * reference would contain only one (or even zero) elements.
 * 
 * <BR /><BR />There are otherwise very few uses for a 1 or 0 sized {@code Tuple}.
 * 
 * <EMBED CLASS=globalDefs DATA-KIND=Tuple DATA-N=1>
 * <EMBED CLASS='external-html' DATA-FILE-ID=MUTABLE_TUPLE>
 * @param <A> The type of the <B STYLE='color:red'>only</B> member-field ('{@link #a}').
 */
public class Tuple1<A>
    extends TupleN
    implements java.io.Serializable, Cloneable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID>  */
    protected static final long serialVersionUID = 1;

    /** This holds a pointer the first and only field / instance. */
    public A a;

    /** Constructs this object */
    public Tuple1(A a) { this.a = a; }

    /** Constructs this object.  Initializes the field to null. */
    public Tuple1() { this.a = null; }

    /**
     * Returns {@code '1'}, indicating how many fields are declared by this class.
     * @return As an instance of {@code Tuple1}, this method returns {@code '1'};
     */
    public int n() { return 1; }

    // Super-class uses this for toString, equals, and hashCode
    // There is an optimization, so if this is requested multiple times, it is saved in a
    // transient field.

    final Object[] asArrayInternal()
    { return new Object[] { a }; }

    public Tuple1<A> clone()
    { return new Tuple1<>(this.a); }

    /**
     * Returns this {@code Tuple1} instance's only field - field {@link #a}.  This method may only
     * be invoked on an input value of {@code '1'}, or else it throws.  A {@code Tuple1} instance
     * has only a single field that may be retrieved.
     * 
     * <BR /><BR />This method must be included to properly, fully, implement the ancestor 
     * {@link MultiType} interface.
     * 
     * @param i This must be passed {@code '1'}, or else this method throws IOOBEX.
     * 
     * @returns The reference contained by field {@link #a}.  If this method returns, its returned
     * type will always be {@link <A>}.
     * 
     * @throws IndexOutOfBoundsException As this {@code Tuple1} instance has but a single field,
     * <I>this exceptions throws for all values of {@code 'i'} - except {@code '1'}</I>.
     */
    public A get(final int i)
    {
        if (i != 1) throw new IndexOutOfBoundsException(
            "This is an instance of Tuple1, and therefore '1' is the only valid value which may " +
            "be passed to 'i'"
        );

        return a;
    }

    public Ret1<A> toImmutable()
    { return new Ret1<>(this.a); }
}