scolebourne 2002/10/13 05:56:42 Modified: collections/src/java/org/apache/commons/collections ArrayStack.java Log: Enable nulls to be added to the stack Add initial size constructor Tidy javadoc and code layout Revision Changes Path 1.10 +79 -74 jakarta-commons/collections/src/java/org/apache/commons/collections/ArrayStack.java Index: ArrayStack.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ArrayStack.java,v retrieving revision 1.9 retrieving revision 1.10 diff -u -r1.9 -r1.10 --- ArrayStack.java 12 Oct 2002 22:15:19 -0000 1.9 +++ ArrayStack.java 13 Oct 2002 12:56:42 -0000 1.10 @@ -58,174 +58,179 @@ * <http://www.apache.org/>. * */ - - package org.apache.commons.collections; - import java.util.ArrayList; import java.util.EmptyStackException; - /** * An implementation of the {@link java.util.Stack} API that is based on an * <code>ArrayList</code> instead of a <code>Vector</code>, so it is not * synchronized to protect against multi-threaded access. The implementation * is therefore operates faster in environments where you do not need to * worry about multiple thread contention. - * - * The removal order of an <Code>ArrayStack</Code> is based on insertion + * <p> + * The removal order of an <code>ArrayStack</code> is based on insertion * order: The most recently added element is removed first. The iteration - * order is <I>not</I> the same as the removal order. The iterator returns + * order is <i>not</i> the same as the removal order. The iterator returns * elements from the bottom up, whereas the {@link #remove()} method removes * them from the top down. + * <p> + * Unlike <code>Stack</code>, <code>ArrayStack</code> accepts null entries. * - * @since 1.0 * @author Craig R. McClanahan - * @version $Revision$ $Date$ + * @author Paul Jack + * @author Stephen Colebourne + * @since 1.0 + * @version $Id$ * @see java.util.Stack */ - public class ArrayStack extends ArrayList implements Buffer { - final private static long serialVersionUID = 2130079159931574599L; //, local class serialVersionUID = -3491241305852305742 /** - * Constructs a new empty <Code>ArrayStack</Code>. + * Constructs a new empty <code>ArrayStack</code>. The initial size + * is controlled by <code>ArrayList</code> and is currently 10. */ public ArrayStack() { super(); } - // --------------------------------------------------------- Public Methods - + /** + * Constructs a new empty <code>ArrayStack</code> with an initial size. + * + * @param initialSize the initial size to use + * @throws IllegalArgumentException if the specified initial size + * is negative + */ + public ArrayStack(int initialSize) { + super(initialSize); + } /** * Return <code>true</code> if this stack is currently empty. + * <p> + * This method exists for compatability with <code>java.util.Stack</code>. + * New users of this class should use <code>isEmpty</code> instead. + * + * @return true if the stack is currently empty */ public boolean empty() { - - return (size() == 0); - + return isEmpty(); } - /** - * Return the top item off of this stack without removing it. + * Returns the top item off of this stack without removing it. * - * @exception EmptyStackExceptino if the stack is empty + * @return the top item on the stack + * @throws EmptyStackException if the stack is empty */ public Object peek() throws EmptyStackException { - int n = size(); - if (n <= 0) + if (n <= 0) { throw new EmptyStackException(); - else - return (get(n - 1)); - + } else { + return get(n - 1); + } } /** - * Return the n'th item down (zero-relative) from the top of this + * Returns the n'th item down (zero-relative) from the top of this * stack without removing it. * - * @param n Number of items down to go - * - * @exception EmptyStackException if there are not enough items on the + * @param n the number of items down to go + * @return the n'th item on the stack, zero relative + * @throws EmptyStackException if there are not enough items on the * stack to satisfy this request */ public Object peek(int n) throws EmptyStackException { - int m = (size() - n) - 1; - if (m < 0) + if (m < 0) { throw new EmptyStackException(); - else - return (get(m)); - + } else { + return get(m); + } } - /** - * Pop the top item off of this stack and return it. + * Pops the top item off of this stack and return it. * - * @exception EmptyStackException if the stack is empty + * @return the top item on the stack + * @throws EmptyStackException if the stack is empty */ public Object pop() throws EmptyStackException { - int n = size(); - if (n <= 0) + if (n <= 0) { throw new EmptyStackException(); - else - return (remove(n - 1)); - + } else { + return remove(n - 1); + } } - /** - * Push a new item onto the top of this stack. The pushed item is also - * returned. + * Pushes a new item onto the top of this stack. The pushed item is also + * returned. This is equivalent to calling <code>add</code>. * - * @param item Item to be added + * @param item the item to be added + * @return the item just pushed */ public Object push(Object item) { - - if (item == null) - throw new NullPointerException(); add(item); - return (item); - + return item; } - /** - * Return the one-based position of the distance from the top that the + * Returns the one-based position of the distance from the top that the * specified object exists on this stack, where the top-most element is * considered to be at distance <code>1</code>. If the object is not * present on the stack, return <code>-1</code> instead. The * <code>equals()</code> method is used to compare to the items * in this stack. * - * @param o Object to be searched for + * @param object the object to be searched for + * @return the 1-based depth into the stack of the object, or -1 if not found */ - public int search(Object o) { - + public int search(Object object) { int i = size() - 1; // Current index int n = 1; // Current distance while (i >= 0) { - if (o.equals(get(i))) - return (n); + Object current = get(i); + if ((object == null && current == null) || + (object != null && object.equals(current))) { + return n; + } i--; n++; } - return (-1); - + return -1; } - /** - * Returns the element on the top of the stack. + * Returns the element on the top of the stack. * - * @return the element on the top of the stack - * @throws BufferUnderflowException if the stack is empty + * @return the element on the top of the stack + * @throws BufferUnderflowException if the stack is empty */ public Object get() { int size = size(); - if (size == 0) throw new BufferUnderflowException(); + if (size == 0) { + throw new BufferUnderflowException(); + } return get(size - 1); } - - /** - * Removes the element on the top of the stack. + * Removes the element on the top of the stack. * - * @return the removed element - * @throws BufferUnderflowException if the stack is empty + * @return the removed element + * @throws BufferUnderflowException if the stack is empty */ public Object remove() { int size = size(); - if (size == 0) throw new BufferUnderflowException(); + if (size == 0) { + throw new BufferUnderflowException(); + } return remove(size - 1); }
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>