edu.colorado.collections
Class ObjectStack

java.lang.Object
  edu.colorado.collections.ObjectStack

All Implemented Interfaces:

java.lang.Cloneable

public class ObjectStack
extends java.lang.Object
implements java.lang.Cloneable

An ObjectStack is a stack of references to objects.

Limitations:

(1) The capacity of one of these stacks can change after it's created, but the maximum capacity is limited by the amount of free memory on the machine. The constructor, ensureCapacity, push, and trimToSize will result in an OutOfMemoryError when free memory is exhausted.

(2) A stack's capacity cannot exceed the maximum integer 2,147,483,647 (Integer.MAX_VALUE). Any attempt to create a larger capacity results in a failure due to an arithmetic overflow.

Java Source Code for this class:

http://www.cs.colorado.edu/~main/edu/colorado/collections/ObjectStack.java

See Also:

ObjectLinkedStack, BooleanStack, ByteStack, CharStack, DoubleStack, FloatStack, IntStack, LongStack, ShortStack

Constructor Summary

ObjectStack()
Initialize an empty stack with an initial capacity of 10.

ObjectStack(int initialCapacity)
Initialize an empty stack with a specified initial capacity.

Method Summary

java.lang.Object	clone() Generate a copy of this stack.
void	ensureCapacity(int minimumCapacity) Change the current capacity of this stack.
int	getCapacity() Accessor method to get the current capacity of this stack.
boolean	isEmpty() Determine whether this stack is empty.
java.lang.Object	peek() Get the top item of this stack, without removing the item.
java.lang.Object	pop() Get the top item, removing it from this stack.
void	push(java.lang.Object item) Push a new item onto this stack.
int	size() Accessor method to determine the number of items in this stack.
void	trimToSize() Reduce the current capacity of this stack to its actual size (i.e., the number of items it contains).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectStack

public ObjectStack()

Initialize an empty stack with an initial capacity of 10. Note that the push method works efficiently (without needing more memory) until this capacity is reached.

Parameters:

- - none

Postcondition:

This stack is empty and has an initial capacity of 10.

Throws:

java.lang.OutOfMemoryError - Indicates insufficient memory for: new Object[10].

ObjectStack

public ObjectStack(int initialCapacity)

Initialize an empty stack with a specified initial capacity. Note that the push method works efficiently (without needing more memory) until this capacity is reached.

Parameters:

initialCapacity - the initial capacity of this stack

Precondition:

initialCapacity is non-negative.

Postcondition:

This stack is empty and has the given initial capacity.

Throws:

java.lang.IllegalArgumentException - Indicates that initialCapacity is negative.

java.lang.OutOfMemoryError - Indicates insufficient memory for: new Object[initialCapacity].

Method Detail

clone

public java.lang.Object clone()

Generate a copy of this stack.

Overrides:

clone in class java.lang.Object

Parameters:

- - none

Returns:

The return value is a copy of this stack. Subsequent changes to the copy will not affect the original, nor vice versa. Note that the return value must be type cast to an ObjectStack before it can be used.

Throws:

java.lang.OutOfMemoryError - Indicates insufficient memory for creating the clone.

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Change the current capacity of this stack.

Parameters:

minimumCapacity - the new capacity for this stack

Postcondition:

This stack's capacity has been changed to at least minimumCapacity. If the capacity was already at or greater than minimumCapacity, then the capacity is left unchanged.

Throws:

java.lang.OutOfMemoryError - Indicates insufficient memory for: new Object[minimumCapacity].

getCapacity

public int getCapacity()

Accessor method to get the current capacity of this stack. The push method works efficiently (without needing more memory) until this capacity is reached.

Parameters:

- - none

Returns:

the current capacity of this stack

isEmpty

public boolean isEmpty()

Determine whether this stack is empty.

Parameters:

- - none

Returns:

true if this stack is empty; false otherwise.

peek

public java.lang.Object peek()

Get the top item of this stack, without removing the item.

Parameters:

- - none

Precondition:

This stack is not empty.

Returns:

the top item of the stack

Throws:

java.util.EmptyStackException - Indicates that this stack is empty.

pop

public java.lang.Object pop()

Get the top item, removing it from this stack.

Parameters:

- - none

Precondition:

This stack is not empty.

Postcondition:

The return value is the top item of this stack, and the item has been removed.

Throws:

java.util.EmptyStackException - Indicates that this stack is empty.

push

public void push(java.lang.Object item)

Push a new item onto this stack. If the addition would take this stack beyond its current capacity, then the capacity is increased before adding the new item. The new item may be the null reference.

Parameters:

item - the item to be pushed onto this stack

Postcondition:

The item has been pushed onto this stack.

Throws:

java.lang.OutOfMemoryError - Indicates insufficient memory for increasing the stack's capacity.

Note:

An attempt to increase the capacity beyond Integer.MAX_VALUE will cause the stack to fail with an arithmetic overflow.

size

public int size()

Accessor method to determine the number of items in this stack.

Parameters:

- - none

Returns:

the number of items in this stack

trimToSize

public void trimToSize()

Reduce the current capacity of this stack to its actual size (i.e., the number of items it contains).

Parameters:

- - none

Postcondition:

This stack's capacity has been changed to its current size.

Throws:

java.lang.OutOfMemoryError - Indicates insufficient memory for altering the capacity.