jaroslav@597: /* jaroslav@597: * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved. jaroslav@597: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@597: * jaroslav@597: * This code is free software; you can redistribute it and/or modify it jaroslav@597: * under the terms of the GNU General Public License version 2 only, as jaroslav@597: * published by the Free Software Foundation. Oracle designates this jaroslav@597: * particular file as subject to the "Classpath" exception as provided jaroslav@597: * by Oracle in the LICENSE file that accompanied this code. jaroslav@597: * jaroslav@597: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@597: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@597: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@597: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@597: * accompanied this code). jaroslav@597: * jaroslav@597: * You should have received a copy of the GNU General Public License version jaroslav@597: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@597: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@597: * jaroslav@597: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@597: * or visit www.oracle.com if you need additional information or have any jaroslav@597: * questions. jaroslav@597: */ jaroslav@597: jaroslav@597: package java.util; jaroslav@597: jaroslav@597: /** jaroslav@597: * The Stack class represents a last-in-first-out jaroslav@597: * (LIFO) stack of objects. It extends class Vector with five jaroslav@597: * operations that allow a vector to be treated as a stack. The usual jaroslav@597: * push and pop operations are provided, as well as a jaroslav@597: * method to peek at the top item on the stack, a method to test jaroslav@597: * for whether the stack is empty, and a method to search jaroslav@597: * the stack for an item and discover how far it is from the top. jaroslav@597: *

jaroslav@597: * When a stack is first created, it contains no items. jaroslav@597: * jaroslav@597: *

A more complete and consistent set of LIFO stack operations is jaroslav@597: * provided by the {@link Deque} interface and its implementations, which jaroslav@597: * should be used in preference to this class. For example: jaroslav@597: * 

   {@code
jaroslav@597:  *   Deque stack = new ArrayDeque();}
jaroslav@597: * jaroslav@597: * @author Jonathan Payne jaroslav@597: * @since JDK1.0 jaroslav@597: */ jaroslav@597: public jaroslav@597: class Stack extends Vector { jaroslav@597: /** jaroslav@597: * Creates an empty Stack. jaroslav@597: */ jaroslav@597: public Stack() { jaroslav@597: } jaroslav@597: jaroslav@597: /** jaroslav@597: * Pushes an item onto the top of this stack. This has exactly jaroslav@597: * the same effect as: jaroslav@597: * 
jaroslav@597:      * addElement(item)
jaroslav@597: * jaroslav@597: * @param item the item to be pushed onto this stack. jaroslav@597: * @return the item argument. jaroslav@597: * @see java.util.Vector#addElement jaroslav@597: */ jaroslav@597: public E push(E item) { jaroslav@597: addElement(item); jaroslav@597: jaroslav@597: return item; jaroslav@597: } jaroslav@597: jaroslav@597: /** jaroslav@597: * Removes the object at the top of this stack and returns that jaroslav@597: * object as the value of this function. jaroslav@597: * jaroslav@597: * @return The object at the top of this stack (the last item jaroslav@597: * of the Vector object). jaroslav@597: * @throws EmptyStackException if this stack is empty. jaroslav@597: */ jaroslav@597: public synchronized E pop() { jaroslav@597: E obj; jaroslav@597: int len = size(); jaroslav@597: jaroslav@597: obj = peek(); jaroslav@597: removeElementAt(len - 1); jaroslav@597: jaroslav@597: return obj; jaroslav@597: } jaroslav@597: jaroslav@597: /** jaroslav@597: * Looks at the object at the top of this stack without removing it jaroslav@597: * from the stack. jaroslav@597: * jaroslav@597: * @return the object at the top of this stack (the last item jaroslav@597: * of the Vector object). jaroslav@597: * @throws EmptyStackException if this stack is empty. jaroslav@597: */ jaroslav@597: public synchronized E peek() { jaroslav@597: int len = size(); jaroslav@597: jaroslav@597: if (len == 0) jaroslav@597: throw new EmptyStackException(); jaroslav@597: return elementAt(len - 1); jaroslav@597: } jaroslav@597: jaroslav@597: /** jaroslav@597: * Tests if this stack is empty. jaroslav@597: * jaroslav@597: * @return true if and only if this stack contains jaroslav@597: * no items; false otherwise. jaroslav@597: */ jaroslav@597: public boolean empty() { jaroslav@597: return size() == 0; jaroslav@597: } jaroslav@597: jaroslav@597: /** jaroslav@597: * Returns the 1-based position where an object is on this stack. jaroslav@597: * If the object o occurs as an item in this stack, this jaroslav@597: * method returns the distance from the top of the stack of the jaroslav@597: * occurrence nearest the top of the stack; the topmost item on the jaroslav@597: * stack is considered to be at distance 1. The equals jaroslav@597: * method is used to compare o to the jaroslav@597: * items in this stack. jaroslav@597: * jaroslav@597: * @param o the desired object. jaroslav@597: * @return the 1-based position from the top of the stack where jaroslav@597: * the object is located; the return value -1 jaroslav@597: * indicates that the object is not on the stack. jaroslav@597: */ jaroslav@597: public synchronized int search(Object o) { jaroslav@597: int i = lastIndexOf(o); jaroslav@597: jaroslav@597: if (i >= 0) { jaroslav@597: return size() - i; jaroslav@597: } jaroslav@597: return -1; jaroslav@597: } jaroslav@597: jaroslav@597: /** use serialVersionUID from JDK 1.0.2 for interoperability */ jaroslav@597: private static final long serialVersionUID = 1224463164541339165L; jaroslav@597: }