java/util/Stack.java

/*
 * %W% %E%
 *
 * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.util;

/**
 * The <code>Stack</code> class represents a last-in-first-out 
 * (LIFO) stack of objects. It extends class <tt>Vector</tt> with five 
 * operations that allow a vector to be treated as a stack. The usual 
 * <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
 * method to <tt>peek</tt> at the top item on the stack, a method to test 
 * for whether the stack is <tt>empty</tt>, and a method to <tt>search</tt> 
 * the stack for an item and discover how far it is from the top.
 * <p>
 * When a stack is first created, it contains no items. 
 *
 * <p>A more complete and consistent set of LIFO stack operations are
 * available in {@link Deque} interface and its implementations, which
 * should be used in preference to this class.  For example:
 * <pre>
 *   Deque&lt;Integer&gt; stack = new ArrayDeque&lt;Integer&gt();
 * </pre>
 *
 * @author  Jonathan Payne
 * @version %I%, %G%
 * @since   JDK1.0
 */
public
class Stack<E> extends Vector<E> {
    /**
     * Creates an empty Stack.
     */
    public Stack() {
    }

    /**
     * Pushes an item onto the top of this stack. This has exactly 
     * the same effect as:
     * <blockquote><pre>
     * addElement(item)</pre></blockquote>
     *
     * @param   item   the item to be pushed onto this stack.
     * @return  the <code>item</code> argument.
     * @see     java.util.Vector#addElement
     */
    public E push(E item) {
        addElement(item);

        return item;
    }

    /**
     * Removes the object at the top of this stack and returns that 
     * object as the value of this function. 
     *
     * @return     The object at the top of this stack (the last item 
     *             of the <tt>Vector</tt> object).
     * @exception  EmptyStackException  if this stack is empty.
     */
    public synchronized E pop() {
        E       obj;
        int     len = size();

        obj = peek();
        removeElementAt(len - 1);

        return obj;
    }

    /**
     * Looks at the object at the top of this stack without removing it 
     * from the stack. 
     *
     * @return     the object at the top of this stack (the last item 
     *             of the <tt>Vector</tt> object). 
     * @exception  EmptyStackException  if this stack is empty.
     */
    public synchronized E peek() {
        int     len = size();

        if (len == 0)
            throw new EmptyStackException();
        return elementAt(len - 1);
    }

    /**
     * Tests if this stack is empty.
     *
     * @return  <code>true</code> if and only if this stack contains 
     *          no items; <code>false</code> otherwise.
     */
    public boolean empty() {
        return size() == 0;
    }

    /**
     * Returns the 1-based position where an object is on this stack. 
     * If the object <tt>o</tt> occurs as an item in this stack, this 
     * method returns the distance from the top of the stack of the 
     * occurrence nearest the top of the stack; the topmost item on the 
     * stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt> 
     * method is used to compare <tt>o</tt> to the 
     * items in this stack.
     *
     * @param   o   the desired object.
     * @return  the 1-based position from the top of the stack where 
     *          the object is located; the return value <code>-1</code>
     *          indicates that the object is not on the stack.
     */
    public synchronized int search(Object o) {
        int i = lastIndexOf(o);

        if (i >= 0) {
            return size() - i;
        }
        return -1;
    }

    /** use serialVersionUID from JDK 1.0.2 for interoperability */
    private static final long serialVersionUID = 1224463164541339165L;
}
Revision:	1.2
Committed:	Sat Oct 1 21:43:43 2005 UTC (18 years, 7 months ago) by jsr166
Branch:	MAIN
Changes since 1.1:	+3 -3 lines
Log Message:	SCCS keywords
#	User	Rev	Content
1	dl	1.1	/*
2	jsr166	1.2	* %W% %E%
3	dl	1.1	*
4	jsr166	1.2	* Copyright 2005 Sun Microsystems, Inc. All rights reserved.
5	dl	1.1	* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6			*/
7
8			package java.util;
9
10			/**
11			* The <code>Stack</code> class represents a last-in-first-out
12			* (LIFO) stack of objects. It extends class <tt>Vector</tt> with five
13			* operations that allow a vector to be treated as a stack. The usual
14			* <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
15			* method to <tt>peek</tt> at the top item on the stack, a method to test
16			* for whether the stack is <tt>empty</tt>, and a method to <tt>search</tt>
17			* the stack for an item and discover how far it is from the top.
18			* <p>
19			* When a stack is first created, it contains no items.
20			*
21			* <p>A more complete and consistent set of LIFO stack operations are
22			* available in {@link Deque} interface and its implementations, which
23			* should be used in preference to this class. For example:
24			* <pre>
25			* Deque<Integer> stack = new ArrayDeque<Integer&gt();
26			* </pre>
27			*
28			* @author Jonathan Payne
29	jsr166	1.2	* @version %I%, %G%
30	dl	1.1	* @since JDK1.0
31			*/
32			public
33			class Stack<E> extends Vector<E> {
34			/**
35			* Creates an empty Stack.
36			*/
37			public Stack() {
38			}
39
40			/**
41			* Pushes an item onto the top of this stack. This has exactly
42			* the same effect as:
43			* <blockquote><pre>
44			* addElement(item)</pre></blockquote>
45			*
46			* @param item the item to be pushed onto this stack.
47			* @return the <code>item</code> argument.
48			* @see java.util.Vector#addElement
49			*/
50			public E push(E item) {
51			addElement(item);
52
53			return item;
54			}
55
56			/**
57			* Removes the object at the top of this stack and returns that
58			* object as the value of this function.
59			*
60			* @return The object at the top of this stack (the last item
61			* of the <tt>Vector</tt> object).
62			* @exception EmptyStackException if this stack is empty.
63			*/
64			public synchronized E pop() {
65			E obj;
66			int len = size();
67
68			obj = peek();
69			removeElementAt(len - 1);
70
71			return obj;
72			}
73
74			/**
75			* Looks at the object at the top of this stack without removing it
76			* from the stack.
77			*
78			* @return the object at the top of this stack (the last item
79			* of the <tt>Vector</tt> object).
80			* @exception EmptyStackException if this stack is empty.
81			*/
82			public synchronized E peek() {
83			int len = size();
84
85			if (len == 0)
86			throw new EmptyStackException();
87			return elementAt(len - 1);
88			}
89
90			/**
91			* Tests if this stack is empty.
92			*
93			* @return <code>true</code> if and only if this stack contains
94			* no items; <code>false</code> otherwise.
95			*/
96			public boolean empty() {
97			return size() == 0;
98			}
99
100			/**
101			* Returns the 1-based position where an object is on this stack.
102			* If the object <tt>o</tt> occurs as an item in this stack, this
103			* method returns the distance from the top of the stack of the
104			* occurrence nearest the top of the stack; the topmost item on the
105			* stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt>
106			* method is used to compare <tt>o</tt> to the
107			* items in this stack.
108			*
109			* @param o the desired object.
110			* @return the 1-based position from the top of the stack where
111			* the object is located; the return value <code>-1</code>
112			* indicates that the object is not on the stack.
113			*/
114			public synchronized int search(Object o) {
115			int i = lastIndexOf(o);
116
117			if (i >= 0) {
118			return size() - i;
119			}
120			return -1;
121			}
122
123			/** use serialVersionUID from JDK 1.0.2 for interoperability */
124			private static final long serialVersionUID = 1224463164541339165L;
125			}