Class Stack<T>

Stacks provide 2 basic operations - push and pop. More...

Declarations

Extended By
`FloatStack` , `IntStack` , `StringStack`

Please note that only documented classes are listed here, there might be undocumented classes that extend this one.

Properties
`IsEmpty : Bool ()`	Return True if the stack is empty, ie: it contains no items, else False.
`Length : Int ()`	Returns the number of items in the stack.
`Length : Void ( length:Int )`	Sets the number of items in the stack.

Constructors
`New ()`	Creates a new empty Stack object.
`New ( data:T[] )`	Creates a new Stack object initialized with an array of values.

Methods
`Backwards : Object ()`	Returns an object that may be used to iterate backwards through the stack with a For EachIn loop.
`Clear : Void ()`	Removes all items from the stack.
`Compare : Int ( lhs:T, rhs:T )`	This method is used by the Sort method to compare elements.
`Contains : Bool ( value:T )`	Returns true if value is contained in the stack.
`Data : T[] ()`	Provides access to the underlying array used to store stack data.
`Equals : Bool ( lhs:T, rhs:T )`	This method is used by the Contains and RemoveEach methods to determine element equality.
`Find : Int ( value:T, start:Int=0 )`	Finds the index of the first element in the stack equal to value.
`FindLast : Int ( value:T )`	Finds the index of the last element in the stack equal to value.
`FindLast : Int ( value:T, start:Int )`	Finds the index of the last element in the stack equal to value.
`Get : T ( index:Int )`	Returns the element at the specified index.
`Insert : Void ( index:Int, value:T )`	Inserts value into the stack, shifting existing elements up if necessary.
`ObjectEnumerator : Object ()`	Returns an enumerator object suitable for use with For EachIn loops.
`Pop : T ()`	Removes the item at the top of the stack and returns it.
`Push : Void ( value:T )`	Pushes a value on the top of the stack.
`Push : Void ( values:T[] )`	Pushes an array of values on the top of the stack starting with element 0.
`Remove : Void ( index:Int )`	Removes the value at the specified index from the stack, shifting existing elements down if necessary.
`RemoveEach : Void ( value:T )`	Finds and removes all elements in the stack equal to value, shifting existing elements down if necessary.
`RemoveFirst : Void ( value:T )`	Finds and removes the first element in the stack equal to value.
`RemoveLast : Void ( value:T )`	Finds and removes the last element in the stack equal to value.
`Set : Void ( index:Int, value:T )`	Overwrites the existing value at index with value.
`Sort : Int ( ascending:Int=True )`	Sorts the stack into ascending or descending order.
`ToArray : T[] ()`	Converts the stack to an array of values.
`Top : T ()`	Returns the item at the top of the stack.

Detailed Discussion

Stacks provide 2 basic operations - push and pop. Pushing an item on a stack adds the item to the top of the stack, while popping an item removes the item from the top of the stack and returns it.

Stacks may also be efficiently indexed using an integer index, and elements may be inserted and removed. This allows stacks to also be used as a dynamic array (an array where the length can change), much like a C++ vector.

Properties Documentation

Method IsEmpty : Bool () Property

Return True if the stack is empty, ie: it contains no items, else False.

Method Length : Int () Property

Returns the number of items in the stack.

Method Length : Void ( length:Int ) Property

Sets the number of items in the stack.

Constructors Documentation

Method New ()

Creates a new empty Stack object.

Method New ( data:T[] )

Creates a new Stack object initialized with an array of values.

Parameters

values - an array of values.

Methods Documentation

Method Backwards : Object ()

Returns an object that may be used to iterate backwards through the stack with a For EachIn loop.

Note that this does not actually reverse or modify the stack in any way.

Example

Function Main()

Local stk:=New StringStack

stk.Push "Hello"
stk.Push "there"
stk.Push "this"
stk.Push "is"
stk.Push "a"
stk.Push "test"

Print "Fowards:"
For Local t$=EachIn stk
Print t
Next

Print ""

Print "Backwards:"
For Local t$=Eachin stk.Backwards()
Print t
Next

End

Method Clear : Void ()

Removes all items from the stack.

Method Compare : Int ( lhs:T, rhs:T )

This method is used by the Sort method to compare elements.

By default, this methods simply generates a runtime error. Extending classes should implement this method if they want to support Sort.

Method Contains : Bool ( value:T )

Returns true if value is contained in the stack.

Method Data : T[] ()

Provides access to the underlying array used to store stack data.

Note: The length of this array may be greater than the actual length of the stack.

Method Equals : Bool ( lhs:T, rhs:T )

This method is used by the Contains and RemoveEach methods to determine element equality.

By default, this method compares lhs and rhs using the '=' operator. Extending classes may override this method to provide their own equality test.

Method Find : Int ( value:T, start:Int=0 )

Finds the index of the first element in the stack equal to value. The stack is searched starting at index start.

If not matching element is found, -1 is returned.

Method FindLast : Int ( value:T )

Finds the index of the last element in the stack equal to value.

If not matching element is found, -1 is returned.

Method FindLast : Int ( value:T, start:Int )

Finds the index of the last element in the stack equal to value. The stack is searched starting at index start.

If not matching element is found, -1 is returned.

Method Get : T ( index:Int )

Returns the element at the specified index.

An index of 0 represents the bottom of the stack, and an index of Length-1 represents the top.

Parameters

index - valid integer index. Must be >=0 and See also

Set

Method Insert : Void ( index:Int, value:T )

Inserts value into the stack, shifting existing elements up if necessary.

This will increase the length of the stack by 1.

An index of 0 represents the bottom of the stack, and an index of length-1 represents the top.

Parameters

index - valid integer index. Must be >=0 and

value - value to insert.

Method ObjectEnumerator : Object ()

Returns an enumerator object suitable for use with For EachIn loops.

Method Pop : T ()

Removes the item at the top of the stack and returns it.

This will decrease the length of the stack by 1.

If the stack is empty, the behaviour of Pop is undefined.

Method Push : Void ( value:T )

Pushes a value on the top of the stack.

This will increase the length of the stack by 1.

Parameters

value - value to push.

Method Push : Void ( values:T[] )

Pushes an array of values on the top of the stack starting with element 0.

This will increase the length of the stack by the length of the array.

Parameters

values - values to push.

Method Remove : Void ( index:Int )

Removes the value at the specified index from the stack, shifting existing elements down if necessary.

This will decrease the length of the stack by 1.

An index of 0 represents the bottom of the stack, and an index of length-1 represents the top.

Parameters

index - valid integer index. Must be>=0 and

Method RemoveEach : Void ( value:T )

Finds and removes all elements in the stack equal to value, shifting existing elements down if necessary.

This will decrease the length of the stack by the number of occurances of value in the stack.

Parameters

value - value to remove.

Method RemoveFirst : Void ( value:T )

Finds and removes the first element in the stack equal to value.

Method RemoveLast : Void ( value:T )

Finds and removes the last element in the stack equal to value.

Method Set : Void ( index:Int, value:T )

Overwrites the existing value at index with value.

An index of 0 represents the bottom of the stack, and an index of stack length-1 represents the top.

Parameters

index - valid integer index. Must be >=0 and < stack length.

value - value to set.

Method Sort : Int ( ascending:Int=True )

Sorts the stack into ascending or descending order.

The stack must implement the Compare method.

Method ToArray : T[] ()

Converts the stack to an array of values.

Method Top : T ()

Returns the item at the top of the stack.

If the stack is empty, the behaviour of Top is undefined.