com.sosnoski.util.stack
Class ObjectStack

java.lang.Object
  |
  +--com.sosnoski.util.GrowableBase
        |
        +--com.sosnoski.util.stack.StackBase
              |
              +--com.sosnoski.util.stack.ObjectStack

public class ObjectStack

extends StackBase

Growable Object stack with type specific access methods. This implementation is unsynchronized in order to provide the best possible performance for typical usage scenarios, so explicit synchronization must be implemented by a wrapper class or directly by the application in cases where instances are modified in a multithreaded environment. See the base classes for other details of the implementation.

Version:

1.1

Author:

Dennis M. Sosnoski

Field Summary

protected java.lang.Object[]

m_baseArray The underlying array used for storing the data.

Fields inherited from class com.sosnoski.util.stack.StackBase

m_countPresent

Fields inherited from class com.sosnoski.util.GrowableBase

DEFAULT_SIZE, m_countLimit, m_maximumGrowth

Constructor Summary

ObjectStack()
Default constructor.

ObjectStack(int size)
Constructor with initial size specified.

ObjectStack(int size, int growth)
Constructor with full specification.

ObjectStack(ObjectStack base)
Copy (clone) constructor.

Method Summary

java.lang.Object	clone() Duplicates the object with the generic call.
protected java.lang.Object	getArray() Get the backing array.
java.util.Iterator	iterator() Return an iterator for the Objects in this stack.
java.lang.Object	peek() Copy top value from the stack.
java.lang.Object	peek(int depth) Copy a value from the stack.
java.lang.Object	pop() Pop a value from the stack.
java.lang.Object	pop(int count) Pop multiple values from the stack.
void	push(java.lang.Object value) Push a value on the stack.
protected void	setArray(java.lang.Object array) Set the backing array.
java.lang.Object[]	toArray() Constructs and returns a simple array containing the same data as held in this stack.
java.lang.Object[]	toArray(java.lang.Class type) Constructs and returns a type-specific array containing the same data as held in this growable generic array.

Methods inherited from class com.sosnoski.util.stack.StackBase

buildArray, clear, getAddIndex, isEmpty, size

Methods inherited from class com.sosnoski.util.GrowableBase

buildArray, discardValues, ensureCapacity, growArray, resizeCopy

Methods inherited from class java.lang.Object

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

Field Detail

m_baseArray

protected java.lang.Object[] m_baseArray

The underlying array used for storing the data.

Constructor Detail

ObjectStack

public ObjectStack(int size,
                   int growth)

Constructor with full specification.

Parameters:

size - number of Object values initially allowed in stack

growth - maximum size increment for growing stack

ObjectStack

public ObjectStack(int size)

Constructor with initial size specified.

Parameters:

size - number of Object values initially allowed in stack

ObjectStack

public ObjectStack()

Default constructor.

ObjectStack

public ObjectStack(ObjectStack base)

Copy (clone) constructor.

Parameters:

base - instance being copied

Method Detail

getArray

protected java.lang.Object getArray()

Get the backing array. This method is used by the type-agnostic base class code to access the array used for type-specific storage.

Overrides:

getArray in class GrowableBase

Returns:

backing array object

setArray

protected void setArray(java.lang.Object array)

Set the backing array. This method is used by the type-agnostic base class code to set the array used for type-specific storage.

Overrides:

setArray in class GrowableBase

Parameters:

backing - array object

push

public void push(java.lang.Object value)

Push a value on the stack.

Parameters:

value - value to be added

pop

public java.lang.Object pop()

Pop a value from the stack.

Returns:

value from top of stack

Throws:

java.lang.ArrayIndexOutOfBoundsException - on attempt to pop empty stack

pop

public java.lang.Object pop(int count)

Pop multiple values from the stack. The last value popped is the one returned.

Parameters:

count - number of values to pop from stack (must be strictly positive)

Returns:

value from top of stack

Throws:

java.lang.ArrayIndexOutOfBoundsException - on attempt to pop past end of stack

peek

public java.lang.Object peek(int depth)

Copy a value from the stack. This returns a value from within the stack without modifying the stack.

Parameters:

depth - depth of value to be returned

Returns:

value from stack

Throws:

java.lang.ArrayIndexOutOfBoundsException - on attempt to peek past end of stack

peek

public java.lang.Object peek()

Copy top value from the stack. This returns the top value without removing it from the stack.

Returns:

value at top of stack

Throws:

java.lang.ArrayIndexOutOfBoundsException - on attempt to peek empty stack

iterator

public final java.util.Iterator iterator()

Return an iterator for the Objects in this stack. The iterator returns all values in order the order they were added, but is not "live". Values added to the stack during iteration will not be returned by the iteration, and any other changes to the stack while the iteration is in progress will give indeterminant results.

Returns:

iterator for values in stack

toArray

public java.lang.Object[] toArray()

Constructs and returns a simple array containing the same data as held in this stack. Note that the items will be in reverse pop order, with the last item to be popped from the stack as the first item in the array.

Returns:

array containing a copy of the data

toArray

public java.lang.Object[] toArray(java.lang.Class type)

Constructs and returns a type-specific array containing the same data as held in this growable generic array. All values in this array must be assignment compatible with the specified type. Note that the items will be in reverse pop order, with the last item to be popped from the stack as the first item in the array.

Parameters:

type - element type for constructed array

Returns:

array containing a copy of the data

clone

public java.lang.Object clone()

Duplicates the object with the generic call.

Overrides:

clone in class java.lang.Object

Returns:

a copy of the object