Package net.algart.arrays

Interface Stack

All Known Subinterfaces:

BitStack, ByteStack, CharStack, DoubleStack, FloatStack, IntStack, LongStack, MutableArray, MutableBitArray, MutableByteArray, MutableCharArray, MutableDoubleArray, MutableFloatArray, MutableIntArray, MutableLongArray, MutableObjectArray<E>, MutableObjectInPlaceArray<E>, MutablePArray, MutablePFixedArray, MutablePFloatingArray, MutablePIntegerArray, MutablePNumberArray, MutableShortArray, ObjectStack<E>, ShortStack

public interface Stack

Resizable stack of any elements.

Stack is a restricted version (inheritor) of MutableArray interface, allowing only access to the top element.

Please keep in mind: this package does not contain classes that implements Stack but not implements MutableArray. It means that the following operation usually works successfully:

 void someMyMethod(Stack stack) {
     MutableArray a = (MutableArray)stack;
     ... // access to any non-top elements
 }

Of course, it is not an example of good programming style, and there are no guarantees that such operator will not throw ClassCastException. But such an operation is usually posssible. Please compare:

 void someMyMethod(Array readOnlyArray) {
     MutableArray a = (MutableArray)readOnlyArray;
     ... // attempt to modify elements
 }

This code will throw ClassCastException, if the caller of someMyMethod does not forget to use asImmutable() method for creating readOnlyArray argument.

If this stack elements are primitive values (byte, short, etc.), the stack must implement one of BitStack, CharStack, ByteStack, ShortStack, IntStack, LongStack, FloatStack, DoubleStack subinterfaces. In other case, the stack must implement ObjectStack subinterface.

Objects, implementing this interface, are not thread-safe, but are thread-compatible and can be synchronized manually if multithread access is necessary.

Author:

Daniel Alievsky

Method Summary

Modifier and Type	Method	Description
Stack	clear()	Removes all elements from the stack
long	length()	Returns the number of elements in this stack.
Object	popElement()	Removes the element at the top of this stack and returns it, or throws EmptyStackException if the stack is empty.
void	pushElement(Object value)	Appends value element to the top of this stack.
void	removeTop()	Removes the element at the top of this stack and returns it, or throws EmptyStackException if the stack is empty.

Method Details

length

long length()

Returns the number of elements in this stack.

Returns:

the number of elements in this stack.

popElement

Object popElement()

Removes the element at the top of this stack and returns it, or throws EmptyStackException if the stack is empty.

It this object is an AlgART array, implementing MutableArray interface, and it is not empty, the same action may be performed by the following code:

 Object result = array.getElement(array.length()-1);
 array.length(array.length()-1);
 

It is a low-level method. For stacks of primitive elements, implementing one of corresponding interfaces BitStack, CharStack, ByteStack, ShortStack, IntStack, LongStack, FloatStack, DoubleStack, we recommend to use more efficient equivalent method of that interfaces: BitStack.popBit(), CharStack.popChar(), ByteStack.popByte(), ShortStack.popShort(), IntStack.popInt(), LongStack.popLong(), FloatStack.popFloat(), DoubleStack.popDouble(). For other stacks, implementing ObjectStack, we recommend to use ObjectStack.pop().

Returns:

the element at the top of this stack (it is removed from the stack by this method).

Throws:

EmptyStackException - if this stack is empty.

pushElement

void pushElement(Object value)

Appends value element to the top of this stack.

It this object is an AlgART array, implementing MutableArray interface, the same action may be performed by the following code:

 array.length(array.length()+1);
 array.setElement(array.length()-1, value);
 

It is a low-level method. For stacks of primitive elements, implementing one of corresponding interfaces BitStack, CharStack, ByteStack, ShortStack, IntStack, LongStack, FloatStack, DoubleStack, we recommend to use more efficient equivalent method of that interfaces: BitStack.pushBit(boolean), CharStack.pushChar(char), ByteStack.pushByte(byte), ShortStack.pushShort(short), IntStack.pushInt(int), LongStack.pushLong(long), FloatStack.pushFloat(float), DoubleStack.pushDouble(double). For other stacks, implementing ObjectStack, we recommend to use ObjectStack.push(Object).

Parameters:

value - to be added to the top of this stack.

Throws:

ClassCastException - if it is a stack of primitive elements and value is not a corresponding wrapped class (Boolean, Integer, etc.).

ArrayStoreException - if it is a stack of non-primitive elements and value is not an instance of the class of stack elements.

TooLargeArrayException - if the resulting stack length is too large for this type of stacks.

removeTop

void removeTop()

Removes the element at the top of this stack and returns it, or throws EmptyStackException if the stack is empty. This method differs from popElement() only in that it does not return any result, so it works slightly faster.

Throws:

EmptyStackException - if this stack is empty.

clear

Stack clear()

Removes all elements from the stack

Returns:

a reference to this array.