Home » openjdk-7 » java » util » [javadoc | source]

    1   /*
    2    * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * 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.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle 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 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    */
   25   
   26   package java.util;
   27   
   28   /**
   29    * 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    * <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
   33    * 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    * the stack for an item and discover how far it is from the top.
   36    * <p>
   37    * When a stack is first created, it contains no items.
   38    *
   39    * <p>A more complete and consistent set of LIFO stack operations is
   40    * provided by the {@link Deque} interface and its implementations, which
   41    * should be used in preference to this class.  For example:
   42    * <pre>   {@code
   43    *   Deque<Integer> stack = new ArrayDeque<Integer>();}</pre>
   44    *
   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        * Pushes an item onto the top of this stack. This has exactly
   58        * 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           addElement(item);
   68   
   69           return item;
   70       }
   71   
   72       /**
   73        * Removes the object at the top of this stack and returns that
   74        * object as the value of this function.
   75        *
   76        * @return  The object at the top of this stack (the last item
   77        *          of the <tt>Vector</tt> object).
   78        * @throws  EmptyStackException  if this stack is empty.
   79        */
   80       public synchronized E pop() {
   81           E       obj;
   82           int     len = size();
   83   
   84           obj = peek();
   85           removeElementAt(len - 1);
   86   
   87           return obj;
   88       }
   89   
   90       /**
   91        * Looks at the object at the top of this stack without removing it
   92        * from the stack.
   93        *
   94        * @return  the object at the top of this stack (the last item
   95        *          of the <tt>Vector</tt> object).
   96        * @throws  EmptyStackException  if this stack is empty.
   97        */
   98       public synchronized E peek() {
   99           int     len = size();
  100   
  101           if (len == 0)
  102               throw new EmptyStackException();
  103           return elementAt(len - 1);
  104       }
  105   
  106       /**
  107        * Tests if this stack is empty.
  108        *
  109        * @return  <code>true</code> if and only if this stack contains
  110        *          no items; <code>false</code> otherwise.
  111        */
  112       public boolean empty() {
  113           return size() == 0;
  114       }
  115   
  116       /**
  117        * 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        * items in this stack.
  124        *
  125        * @param   o   the desired object.
  126        * @return  the 1-based position from the top of the stack where
  127        *          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           int i = lastIndexOf(o);
  132   
  133           if (i >= 0) {
  134               return size() - i;
  135           }
  136           return -1;
  137       }
  138   
  139       /** use serialVersionUID from JDK 1.0.2 for interoperability */
  140       private static final long serialVersionUID = 1224463164541339165L;
  141   }

Home » openjdk-7 » java » util » [javadoc | source]