commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections ArrayStack.java
Date Sun, 13 Oct 2002 12:56:42 GMT
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:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message