java/util/Stack.java

/*
 * Copyright (c) 1994, 2005, Oracle and/or its affiliates. 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.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
 * @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.9
Committed:	Sun Sep 5 21:32:19 2010 UTC (13 years, 8 months ago) by jsr166
Branch:	MAIN
Changes since 1.8:	+4 -4 lines
Log Message:	Update legal notices to Oracle wording
#	User	Rev	Content
1	dl	1.1	/*
2	jsr166	1.9	* Copyright (c) 1994, 2005, Oracle and/or its affiliates. All rights reserved.
3	jsr166	1.6	* 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	jsr166	1.9	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22			* or visit www.oracle.com if you need additional information or have any
23			* 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			* @since JDK1.0
47			*/
48			public
49			class Stack<E> extends Vector<E> {
50			/**
51			* Creates an empty Stack.
52			*/
53			public Stack() {
54			}
55
56			/**
57	jsr166	1.3	* Pushes an item onto the top of this stack. This has exactly
58	dl	1.1	* the same effect as:
59			* <blockquote><pre>
60			* addElement(item)</pre></blockquote>
61			*
62			* @param item the item to be pushed onto this stack.
63			* @return the <code>item</code> argument.
64			* @see java.util.Vector#addElement
65			*/
66			public E push(E item) {
67	jsr166	1.7	addElement(item);
68	dl	1.1
69	jsr166	1.7	return item;
70	dl	1.1	}
71
72			/**
73	jsr166	1.3	* Removes the object at the top of this stack and returns that
74			* object as the value of this function.
75	dl	1.1	*
76	jsr166	1.3	* @return The object at the top of this stack (the last item
77	dl	1.1	* of the <tt>Vector</tt> object).
78			* @exception EmptyStackException if this stack is empty.
79			*/
80			public synchronized E pop() {
81	jsr166	1.7	E obj;
82			int len = size();
83	dl	1.1
84	jsr166	1.7	obj = peek();
85			removeElementAt(len - 1);
86	dl	1.1
87	jsr166	1.7	return obj;
88	dl	1.1	}
89
90			/**
91	jsr166	1.3	* Looks at the object at the top of this stack without removing it
92			* from the stack.
93	dl	1.1	*
94	jsr166	1.3	* @return the object at the top of this stack (the last item
95			* of the <tt>Vector</tt> object).
96	dl	1.1	* @exception EmptyStackException if this stack is empty.
97			*/
98			public synchronized E peek() {
99	jsr166	1.7	int len = size();
100	dl	1.1
101	jsr166	1.7	if (len == 0)
102			throw new EmptyStackException();
103			return elementAt(len - 1);
104	dl	1.1	}
105
106			/**
107			* Tests if this stack is empty.
108			*
109	jsr166	1.3	* @return <code>true</code> if and only if this stack contains
110	dl	1.1	* no items; <code>false</code> otherwise.
111			*/
112			public boolean empty() {
113	jsr166	1.7	return size() == 0;
114	dl	1.1	}
115
116			/**
117	jsr166	1.3	* Returns the 1-based position where an object is on this stack.
118			* If the object <tt>o</tt> occurs as an item in this stack, this
119			* method returns the distance from the top of the stack of the
120			* occurrence nearest the top of the stack; the topmost item on the
121			* stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt>
122			* method is used to compare <tt>o</tt> to the
123	dl	1.1	* items in this stack.
124			*
125			* @param o the desired object.
126	jsr166	1.3	* @return the 1-based position from the top of the stack where
127	dl	1.1	* the object is located; the return value <code>-1</code>
128			* indicates that the object is not on the stack.
129			*/
130			public synchronized int search(Object o) {
131	jsr166	1.7	int i = lastIndexOf(o);
132	dl	1.1
133	jsr166	1.7	if (i >= 0) {
134			return size() - i;
135			}
136			return -1;
137	dl	1.1	}
138
139			/** use serialVersionUID from JDK 1.0.2 for interoperability */
140			private static final long serialVersionUID = 1224463164541339165L;
141			}