// The Science of Computing Stack class.

// History:
//   August 2003 -- Created by Greg Scragg.
//   October 2003 -- updates to several methods by GWS
//   February 2004 -- updated references and variable names to correspond to text changes.
//   May 2004 -- Documentation and Java usage cleaned up by Doug Baldwin.
//   November 2004 -- Method name "makeNewObject" corrected to "makeNewList"
//     by Doug Baldwin.


package geneseo.cs.sc;


/**
 * Represents stacks of arbitrary objects. This class reflects a view of a stack
 * as a kind of list, albeit one with some unique operations (push, pop, etc.),
 * and in which some of the traditional list operations (find, delete, etc.) do
 * nothing. The overall result is a class whose instances behave like standard
 * stacks.
 * <p>This class was created to support the text <cite>Algorithms &amp; Data
 * Structures: The Science of Computing</cite> by Doug Baldwin and Greg Scragg.
 * All references herein to &quot;the text&quot; refer to that book. This stack
 * class is the one described in Chapter 12, including full implementations of
 * some methods that were &quot;left to an exercise&quot; in the text.</p>
 */

public class Stack extends List {


    /**
     * Initialize an empty stack. For example
     * <p><code>Stack s = new Stack();</code></p>
     */
    
    public Stack() {
        super();
    }
    
    
    /**
     * Create a new list that is an instance of <code>Stack</code>,
     * as required of any subclass of <code>List</code>. Clients of
     * <code>Stack</code> generally do not send this message themselves,
     * but code inside inherited methods relies on it.
     * @return A new, empty, <code>Stack</code> object
     */
     
    public List makeNewList() {
        return new Stack();
    }
    

    /**
     * Adds an object to a stack. The added object becomes the stack's
     * top element. For example
     * <p><code>s.push( "hello" );</code></p>
     * @param newItem The object to add to the stack.
     */

    public void push(Object newItem) {
        this.addItem(newItem);
    }
    

    /**
     * Retrieve and remove the top object from a stack. For example,
     * <p><code>Object top = s.pop();</code></p>
     * <p>This message has a precondition that the stack is not empty.</p>
     * @return The top item from the stack.
     */

    public Object pop() {
        Object temp = this.getFirst();
        this.removeItem();
        return temp;
    }
    

    /**
     * Print a stack. For example
     * <p><code>s.printStack();</code></p> 
     */

    public void printStack() {
        this.printList();
    }
    

    /******************************************************************************/
    // Dummy methods to prevent illegal (non stack-like) operations
    
    /**
     * Warns the user that concatenation is not a standard stack operation.
     */

    public void concat(List extraList) {
        System.err.println( "Concatenation not allowed on stacks" );
    } 


    /**
     * Warns the user that searching is not a standard stack operation.
     * @return <code>false</code>, indicating that all attempts to search stacks fail.
     */
     
    public boolean find(Object target) {
        System.err.println( "Searching not allowed on stacks" );
        return false;
    }


    /**
     * Warns the user that general deletion is not a standard stack operation.
     */

    public void delete(Object value) {
        System.err.println( "General deletion not allowed on stacks" );
    }

}