diff options
Diffstat (limited to 'libjava/java/util/Stack.java')
| -rw-r--r-- | libjava/java/util/Stack.java | 121 |
1 files changed, 92 insertions, 29 deletions
diff --git a/libjava/java/util/Stack.java b/libjava/java/util/Stack.java index 963513e..8647fa4 100644 --- a/libjava/java/util/Stack.java +++ b/libjava/java/util/Stack.java @@ -1,42 +1,89 @@ -/* Copyright (C) 1998, 1999 Free Software Foundation +/* Stack.java - Class that provides a Last In First Out (LIFO) + datatype, known more commonly as a Stack + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. - This file is part of libgcj. +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ package java.util; -/** - * @author Warren Levy <warrenl@cygnus.com> - * @date August 20, 1998. - */ /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. * Status: Believed complete and correct */ +/** + * Stack provides a Last In First Out (LIFO) data type, commonly known + * as a Stack. + * + * Stack itself extends Vector and provides the additional methods + * for stack manipulation (push, pop, peek). + * + * @author Warren Levy <warrenl@cygnus.com> + * @date August 20, 1998. + */ public class Stack extends Vector { // Could use Vector methods internally for the following methods // but have used Vector fields directly for efficiency (i.e. this // often reduces out duplicate bounds checking). - public boolean empty() + private static final long serialVersionUID = 1224463164541339165L; + + /** + * This constructor creates a new Stack, initially empty + */ + public Stack() { - return elementCount == 0; + super(); } - public synchronized Object peek() + /** + * Pushes an Object onto the top of the stack. This method is effectively + * the same as addElement(item) + * + * @param item the Object to push onto the stack + * @returns the Object pushed onto the stack + * @see java.util.Vector#addElement(java.util.Object) + */ + public Object push(Object item) { - if (elementCount == 0) - throw new EmptyStackException(); + // When growing the Stack, use the Vector routines in case more + // memory is needed. + // Note: spec indicates that this method *always* returns obj passed in! - return elementData[elementCount - 1]; + addElement(item); + return item; } + /** + * Pops an item from the stack and returns it. The item popped is + * removed from the Stack + * + * @returns the Object popped from the stack + */ public synchronized Object pop() { if (elementCount == 0) @@ -49,28 +96,44 @@ public class Stack extends Vector return obj; } - public Object push(Object obj) + /** + * Returns the top Object on the stack without removing it + * + * @returns the top Object on the stack + */ + public synchronized Object peek() { - // When growing the Stack, use the Vector routines in case more - // memory is needed. - // Note: spec indicates that this method *always* returns obj passed in! + if (elementCount == 0) + throw new EmptyStackException(); - addElement(obj); - return obj; + return elementData[elementCount - 1]; } - public synchronized int search(Object obj) + /** + * Tests if the stack is empty + * + * @returns true if the stack contains no items, false otherwise + */ + public boolean empty() { - // Return the position of obj on the stack as measured from the top; - // i.e. the top element is 1, the next element down is 2, etc. - // If obj is not on the stack, return -1 + return elementCount == 0; + } + /** + * Returns the position of an Object on the stack, with the top + * most Object being at position 1, and each Object deeper in the + * stack at depth + 1 + * + * @param o The object to search for + * @returns The 1 based depth of the Object, or -1 if the Object + * is not on the stack. + */ + public synchronized int search(Object o) + { for (int i = elementCount-1; i >=0; --i) - if (elementData[i].equals(obj)) - return elementCount - i; + if (elementData[i].equals(o)) + return elementCount - i; return -1; } - - private static final long serialVersionUID = 1224463164541339165L; } |