java/util/Stack.java

/*
 * %W% %E%
 *
 * Copyright 2007 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 is
 * provided by the {@link Deque} interface and its implementations, which
 * should be used in preference to this class.  For example:
 * <pre>   {@code
 *   Deque<Integer> stack = new ArrayDeque<Integer>();}</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.5
Committed:	Sun Jan 7 07:38:27 2007 UTC (17 years, 4 months ago) by jsr166
Branch:	MAIN
Changes since 1.4:	+1 -1 lines
Log Message:	copyright year update
#	Content
1	/*
2	* %W% %E%
3	*
4	* Copyright 2007 Sun Microsystems, Inc. All rights reserved.
5	* 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 is
22	* provided by the {@link Deque} interface and its implementations, which
23	* should be used in preference to this class. For example:
24	* <pre> {@code
25	* Deque<Integer> stack = new ArrayDeque<Integer>();}</pre>
26	*
27	* @author Jonathan Payne
28	* @version %I%, %G%
29	* @since JDK1.0
30	*/
31	public
32	class Stack<E> extends Vector<E> {
33	/**
34	* Creates an empty Stack.
35	*/
36	public Stack() {
37	}
38
39	/**
40	* Pushes an item onto the top of this stack. This has exactly
41	* the same effect as:
42	* <blockquote><pre>
43	* addElement(item)</pre></blockquote>
44	*
45	* @param item the item to be pushed onto this stack.
46	* @return the <code>item</code> argument.
47	* @see java.util.Vector#addElement
48	*/
49	public E push(E item) {
50	addElement(item);
51
52	return item;
53	}
54
55	/**
56	* Removes the object at the top of this stack and returns that
57	* object as the value of this function.
58	*
59	* @return The object at the top of this stack (the last item
60	* of the <tt>Vector</tt> object).
61	* @exception EmptyStackException if this stack is empty.
62	*/
63	public synchronized E pop() {
64	E obj;
65	int len = size();
66
67	obj = peek();
68	removeElementAt(len - 1);
69
70	return obj;
71	}
72
73	/**
74	* Looks at the object at the top of this stack without removing it
75	* from the stack.
76	*
77	* @return the object at the top of this stack (the last item
78	* of the <tt>Vector</tt> object).
79	* @exception EmptyStackException if this stack is empty.
80	*/
81	public synchronized E peek() {
82	int len = size();
83
84	if (len == 0)
85	throw new EmptyStackException();
86	return elementAt(len - 1);
87	}
88
89	/**
90	* Tests if this stack is empty.
91	*
92	* @return <code>true</code> if and only if this stack contains
93	* no items; <code>false</code> otherwise.
94	*/
95	public boolean empty() {
96	return size() == 0;
97	}
98
99	/**
100	* Returns the 1-based position where an object is on this stack.
101	* If the object <tt>o</tt> occurs as an item in this stack, this
102	* method returns the distance from the top of the stack of the
103	* occurrence nearest the top of the stack; the topmost item on the
104	* stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt>
105	* method is used to compare <tt>o</tt> to the
106	* items in this stack.
107	*
108	* @param o the desired object.
109	* @return the 1-based position from the top of the stack where
110	* the object is located; the return value <code>-1</code>
111	* indicates that the object is not on the stack.
112	*/
113	public synchronized int search(Object o) {
114	int i = lastIndexOf(o);
115
116	if (i >= 0) {
117	return size() - i;
118	}
119	return -1;
120	}
121
122	/** use serialVersionUID from JDK 1.0.2 for interoperability */
123	private static final long serialVersionUID = 1224463164541339165L;
124	}