home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / util / Stack.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  3.6 KB  |  120 lines
  1. /*
  2.  * @(#)Stack.java    1.21 98/03/18
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * The <code>Stack</code> class represents a last-in-first-out 
  19.  * (LIFO) stack of objects. It extends class <tt>Vector</tt> with five 
  20.  * operations that allow a vector to be treated as a stack. The usual 
  21.  * <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
  22.  * method to <tt>peek</tt> at the top item on the stack, a method to test 
  23.  * for whether the stack is <tt>empty</tt>, and a method to <tt>search</tt> 
  24.  * the stack for an item and discover how far it is from the top.
  25.  * <p>
  26.  * When a stack is first created, it contains no items. 
  27.  *
  28.  * @author  Jonathan Payne
  29.  * @version 1.21, 03/18/98
  30.  * @since   JDK1.0
  31.  */
  32. public
  33. class Stack extends Vector {
  34.     /**
  35.      * Pushes an item onto the top of this stack. This has exactly 
  36.      * the same effect as:
  37.      * <blockquote><pre>
  38.      * addElement(item)</pre></blockquote>
  39.      *
  40.      * @param   item   the item to be pushed onto this stack.
  41.      * @return  the <code>item</code> argument.
  42.      * @see     java.util.Vector#addElement
  43.      */
  44.     public Object push(Object item) {
  45.     addElement(item);
  46.  
  47.     return item;
  48.     }
  49.  
  50.     /**
  51.      * Removes the object at the top of this stack and returns that 
  52.      * object as the value of this function. 
  53.      *
  54.      * @return     The object at the top of this stack (the last item 
  55.      *             of the <tt>Vector</tt> object).
  56.      * @exception  EmptyStackException  if this stack is empty.
  57.      */
  58.     public synchronized Object pop() {
  59.     Object    obj;
  60.     int    len = size();
  61.  
  62.     obj = peek();
  63.     removeElementAt(len - 1);
  64.  
  65.     return obj;
  66.     }
  67.  
  68.     /**
  69.      * Looks at the object at the top of this stack without removing it 
  70.      * from the stack. 
  71.      *
  72.      * @return     the object at the top of this stack (the last item 
  73.      *             of the <tt>Vector</tt> object). 
  74.      * @exception  EmptyStackException  if this stack is empty.
  75.      */
  76.     public synchronized Object peek() {
  77.     int    len = size();
  78.  
  79.     if (len == 0)
  80.         throw new EmptyStackException();
  81.     return elementAt(len - 1);
  82.     }
  83.  
  84.     /**
  85.      * Tests if this stack is empty.
  86.      *
  87.      * @return  <code>true</code> if and only if this stack contains 
  88.      *          no items; <code>false</code> otherwise.
  89.      */
  90.     public boolean empty() {
  91.     return size() == 0;
  92.     }
  93.  
  94.     /**
  95.      * Returns the 1-based position where an object is on this stack. 
  96.      * If the object <tt>o</tt> occurs as an item in this stack, this 
  97.      * method returns the distance from the top of the stack of the 
  98.      * occurrence nearest the top of the stack; the topmost item on the 
  99.      * stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt> 
  100.      * method is used to compare <tt>o</tt> to the 
  101.      * items in this stack.
  102.      *
  103.      * @param   o   the desired object.
  104.      * @return  the 1-based position from the top of the stack where 
  105.      *          the object is located; the return value <code>-1</code>
  106.      *          indicates that the object is not on the stack.
  107.      */
  108.     public synchronized int search(Object o) {
  109.     int i = lastIndexOf(o);
  110.  
  111.     if (i >= 0) {
  112.         return size() - i;
  113.     }
  114.     return -1;
  115.     }
  116.  
  117.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  118.     private static final long serialVersionUID = 1224463164541339165L;
  119. }
  120.