package list;

/**
 * Represents an abstract Scheme-like list, an immutable linear
 * recursive structure of data.
 * Has abstract methods to provide its internal data and structure to the client.
 * Since an AList has an internal structure that is isomorphic to itself, 
 * it's best to implement it using the composite pattern.
 * 
 * @author Dung X. Nguyen
 * @version 1.0
 * @since 09/10/00
 * @Custom Copyright 2000 -All rights reserved
 */
public abstract class AList
{
    /**
     * Returns the first element in this AList, if any.
     * @exception IllegalArgumentException whenever this AList is empty.
     */
    public abstract Object getFirst();

    /**
     * Returns the rest of this AList, if any.
     * @exception IllegalArgumentException whenever this AList is empty.
     */
    public abstract AList getRest();

    /**
     * Returns the number of elements in this AList.
     */
    public abstract int length();

    /**
     * A tail recursive equivalent of the method length().
     */
    public abstract int getLength();

    /**
     * Called by the getLength () in the non-empty parent AList to help compute
     * the length given the accumulated length so far.
     * @param acc the accumulated length.
     */
    protected abstract int getLengthHelp(int acc);

    /**
     * Called by toString () in the non-empty parent AList to help print
     * this AList.
     * @return the String representation of this AList as the rest of the parent AList.
     */
    protected abstract String toStringHelp();

    /**
     * Computes and returns a duplicate copy of this AList, not containing any
     * non-empty substructure of the original AList.
     */
    public abstract AList makeClone();

    /**
     * Finds an returns the element in the list at position n.
     * @param n >= 0, the index of the element in this AList.  n == 0 means the first element.
     * @exception IllegalArgumentException whenever n > the index of the last element in this AList or n<0.
     */
    public abstract Object nthElement(int n);

   /**
    * Finds and returns the last element in this AList, if any.
    * @exception IllegalArgumentException whenever this AList is empty.
    */
    public abstract Object lastElement();

    /**
     * Called by lastElement () in the non-empty parent AList to help
     * find the last element, given the element of the parent AList.
     * @param previous the data element of the parent AList.
     */
    protected abstract Object lastElementHelp(Object previous);
   
    /**
     * Finds and returns the first N elements of this AList.
     * @param n the number of elements from the front of this AList to be returned;
     * n == 0 means the empty list.
     * @exception IllegalArgumentException whenever n > the number of elements in the receiver, or when n<0.
     */
    public abstract AList firstElements(int num_elts);

    /**
     * Computes and returns a copy of this AList in reverse order.
     */
    public abstract AList reverse();

    /**
     * Called by reverse () in the (non-empty) parent list to help reverse
     * the rest of the list, given the reverse of the original list so far.
     * @param stack the reverse of the original list so far.
     * @return the reverse of this AList with stack appended to its tail end.
     */
    protected abstract AList reverseHelp(AList stack);

    /**
     * Computes and returns the appending of this AList with the
     * input parameter.
     * @param rhs the AList to be appended to the right of this AList. 
     */
    public abstract AList append(AList list2);
}