You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2002/10/13 14:56:42 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections ArrayStack.java
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>