java/util/Stack.java

/*
 * Copyright 1994-2005 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 */

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.7
Committed:	Sun May 18 23:47:56 2008 UTC (16 years ago) by jsr166
Branch:	MAIN
Changes since 1.6:	+17 -17 lines
Log Message:	Sync with OpenJDK; untabify
#	User	Rev	Content
1	dl	1.1	/*
2	jsr166	1.6	* Copyright 1994-2005 Sun Microsystems, Inc. All Rights Reserved.
3			* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4	dl	1.1	*
5	jsr166	1.6	* This code is free software; you can redistribute it and/or modify it
6			* under the terms of the GNU General Public License version 2 only, as
7			* published by the Free Software Foundation. Sun designates this
8			* particular file as subject to the "Classpath" exception as provided
9			* by Sun in the LICENSE file that accompanied this code.
10			*
11			* This code is distributed in the hope that it will be useful, but WITHOUT
12			* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13			* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14			* version 2 for more details (a copy is included in the LICENSE file that
15			* accompanied this code).
16			*
17			* You should have received a copy of the GNU General Public License version
18			* 2 along with this work; if not, write to the Free Software Foundation,
19			* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20			*
21			* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22			* CA 95054 USA or visit www.sun.com if you need additional information or
23			* have any questions.
24	dl	1.1	*/
25
26			package java.util;
27
28			/**
29	jsr166	1.3	* The <code>Stack</code> class represents a last-in-first-out
30			* (LIFO) stack of objects. It extends class <tt>Vector</tt> with five
31			* operations that allow a vector to be treated as a stack. The usual
32	dl	1.1	* <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
33	jsr166	1.3	* method to <tt>peek</tt> at the top item on the stack, a method to test
34			* for whether the stack is <tt>empty</tt>, and a method to <tt>search</tt>
35	dl	1.1	* the stack for an item and discover how far it is from the top.
36			* <p>
37	jsr166	1.3	* When a stack is first created, it contains no items.
38	dl	1.1	*
39	jsr166	1.3	* <p>A more complete and consistent set of LIFO stack operations is
40			* provided by the {@link Deque} interface and its implementations, which
41	dl	1.1	* should be used in preference to this class. For example:
42	jsr166	1.3	* <pre> {@code
43			* Deque<Integer> stack = new ArrayDeque<Integer>();}</pre>
44	dl	1.1	*
45			* @author Jonathan Payne
46	jsr166	1.2	* @version %I%, %G%
47	dl	1.1	* @since JDK1.0
48			*/
49			public
50			class Stack<E> extends Vector<E> {
51			/**
52			* Creates an empty Stack.
53			*/
54			public Stack() {
55			}
56
57			/**
58	jsr166	1.3	* Pushes an item onto the top of this stack. This has exactly
59	dl	1.1	* the same effect as:
60			* <blockquote><pre>
61			* addElement(item)</pre></blockquote>
62			*
63			* @param item the item to be pushed onto this stack.
64			* @return the <code>item</code> argument.
65			* @see java.util.Vector#addElement
66			*/
67			public E push(E item) {
68	jsr166	1.7	addElement(item);
69	dl	1.1
70	jsr166	1.7	return item;
71	dl	1.1	}
72
73			/**
74	jsr166	1.3	* Removes the object at the top of this stack and returns that
75			* object as the value of this function.
76	dl	1.1	*
77	jsr166	1.3	* @return The object at the top of this stack (the last item
78	dl	1.1	* of the <tt>Vector</tt> object).
79			* @exception EmptyStackException if this stack is empty.
80			*/
81			public synchronized E pop() {
82	jsr166	1.7	E obj;
83			int len = size();
84	dl	1.1
85	jsr166	1.7	obj = peek();
86			removeElementAt(len - 1);
87	dl	1.1
88	jsr166	1.7	return obj;
89	dl	1.1	}
90
91			/**
92	jsr166	1.3	* Looks at the object at the top of this stack without removing it
93			* from the stack.
94	dl	1.1	*
95	jsr166	1.3	* @return the object at the top of this stack (the last item
96			* of the <tt>Vector</tt> object).
97	dl	1.1	* @exception EmptyStackException if this stack is empty.
98			*/
99			public synchronized E peek() {
100	jsr166	1.7	int len = size();
101	dl	1.1
102	jsr166	1.7	if (len == 0)
103			throw new EmptyStackException();
104			return elementAt(len - 1);
105	dl	1.1	}
106
107			/**
108			* Tests if this stack is empty.
109			*
110	jsr166	1.3	* @return <code>true</code> if and only if this stack contains
111	dl	1.1	* no items; <code>false</code> otherwise.
112			*/
113			public boolean empty() {
114	jsr166	1.7	return size() == 0;
115	dl	1.1	}
116
117			/**
118	jsr166	1.3	* Returns the 1-based position where an object is on this stack.
119			* If the object <tt>o</tt> occurs as an item in this stack, this
120			* method returns the distance from the top of the stack of the
121			* occurrence nearest the top of the stack; the topmost item on the
122			* stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt>
123			* method is used to compare <tt>o</tt> to the
124	dl	1.1	* items in this stack.
125			*
126			* @param o the desired object.
127	jsr166	1.3	* @return the 1-based position from the top of the stack where
128	dl	1.1	* the object is located; the return value <code>-1</code>
129			* indicates that the object is not on the stack.
130			*/
131			public synchronized int search(Object o) {
132	jsr166	1.7	int i = lastIndexOf(o);
133	dl	1.1
134	jsr166	1.7	if (i >= 0) {
135			return size() - i;
136			}
137			return -1;
138	dl	1.1	}
139
140			/** use serialVersionUID from JDK 1.0.2 for interoperability */
141			private static final long serialVersionUID = 1224463164541339165L;
142			}