Class Stack
An ordered, linear, last in first out Collection of items.
Stacks have a distinct ordering of their elements and can be added to at the back and removed from in the back. The combination of these ensures that the last elements added are the first ones out of the Stack.
The Stack interface provides a base set of operations for interacting with any abstract Stack type. Abstract data types may provide addtional specific operations based on the particular implemented type. Concrete implementations, such as ArrayStacks, ultimately determine the properties of the concrete Stack such as time and space complexity for any operations.
The Stack interface provides certain optional methods in addition to those in Collection. Some Stacks, such as immutable or type-restricted data types, may not be able to provide full functionality for these methods. All Stacks are guaranteed to provide a required set of behaviors without exception and, unless otherwise noted, a method is required. All Stacks should attempt to provide optional functionality, if they're able, regardless.
Implements: Collection, Enumerable
Functions
| Stack.new() | Creates a new Stack interface instance. |
Methods
| Stack:Add(item) | Adds an item to the Stack. |
| Stack:AddAll(items) | Adds all provided items to the Stack. |
| Stack:Clear() | Removes everything from the Stack. |
| Stack:Contains(item) | Determines whether the Stack contains an item. |
| Stack:ContainsAll(items) | Determines whether the Stack contains all of the provided items. |
| Stack:ContainsAny(items) | Determines whether the Stack contains any of the provided items. |
| Stack:Count() | Gets the number of items in the Stack. |
| Stack:Empty() | Determines whether the Stack has no elements. |
| Stack:Enumerator() | Creates an enumerator for the Stack. |
| Stack:Last() | Gets the item at the end of the Stack. |
| Stack:Pop() | Gets an item from the end and removes that item from the Stack. |
| Stack:Push(item) | Adds an item to the end of the Stack. |
| Stack:Remove(item) | Removes the specified item from the Stack. |
| Stack:RemoveAll(items) | Removes all provided items from the Stack. |
| Stack:RetainAll(items) | Removes all items except those provided from the Stack. |
| Stack:ToArray() | Creates a new array indexed table of this Stack. |
| Stack:ToTable() | Creates a new table of this Stack. |
Functions
Methods- Stack.new()
-
Creates a new Stack interface instance.
This should only be used when implementing a new Stack.
Access:
-
private
Returns:
-
the new Stack interface
Methods
- Stack:Add(item)
-
Adds an item to the Stack.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Inherited from:
Parameters:
- item the item to add
Returns:
-
true if the Stack changed as a result, false otherwise
- Stack:AddAll(items)
-
Adds all provided items to the Stack.
Adds items provided in another Collection in an arbitrary, deterministic
order. The order is the same as the order of enumeration.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Inherited from:
Parameters:
- items the Collection of items to add to this Stack
Returns:
-
true if the Stack changed as a result, false otherwise
- Stack:Clear()
-
Removes everything from the Stack.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Inherited from:
- Stack:Contains(item)
-
Determines whether the Stack contains an item.
Inherited from:
Parameters:
- item the item to locate in the Stack
Returns:
-
true if the item is in the Stack, false otherwise
- Stack:ContainsAll(items)
-
Determines whether the Stack contains all of the provided items.
Checks for items provided in another Collection in an arbitrary,
deterministic order. The order is the same as the order of enumeration.
Inherited from:
Parameters:
- items the Collection of items to locate in this Stack
Returns:
-
true if all items are in the Stack, false otherwise
- Stack:ContainsAny(items)
-
Determines whether the Stack contains any of the provided items.
Checks for items provided in another Collection in an arbitrary,
deterministic order. The order is the same as the order of enumeration.
Inherited from:
Parameters:
- items the Collection of items to locate in this Stack
Returns:
-
true if any items are in the Stack, false otherwise
- Stack:Count()
-
Gets the number of items in the Stack.
Inherited from:
Returns:
-
the number of items
- Stack:Empty()
-
Determines whether the Stack has no elements.
Inherited from:
Returns:
-
true if the Stack empty, false otherwise
- Stack:Enumerator()
-
Creates an enumerator for the Stack.
The enumerator can be used directly in a generic for loop similar to pairs
or ipairs.
Inherited from:
Returns:
- the enumerator generator
- the invariant state
- the control variable state
- Stack:Last()
-
Gets the item at the end of the Stack.
Returns:
-
the last item in the Stack
Raises:
if the Stack is empty - Stack:Pop()
-
Gets an item from the end and removes that item from the Stack.
Shifts other elements to fill the gap left.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Returns:
-
the item in the Stack
Raises:
if the Stack is empty - Stack:Push(item)
-
Adds an item to the end of the Stack.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Parameters:
- item the item to add
Returns:
-
true if the Stack changed as a result, false otherwise
- Stack:Remove(item)
-
Removes the specified item from the Stack.
Removes only a single item. If there are multiple of the same item, it
removes only the first encountered.
When an item is removed any others are shifted to fill the gap left at the index of removal.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Inherited from:
Parameters:
- item the item to remove from the Stack
Returns:
-
true if the Stack changed as a result, false otherwise
- Stack:RemoveAll(items)
-
Removes all provided items from the Stack.
Removes each instance of a provided item only once for each time provided.
If there are multiple of the same item in this Queue, it removes only
the first encountered for each provided.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Inherited from:
Parameters:
- items the Collection of items to remove from this Stack
Returns:
-
true if the Stack changed as a result, false otherwise
- Stack:RetainAll(items)
-
Removes all items except those provided from the Stack.
Retains only the items contained in the specified Collection. If there are
duplicates they are all kept.
This method is optional. All Stack implementations should attempt to implement this method, but some may be unable to do so or may need to impose additional conditions to do so.
This method should always be overridden regardless of implementation. If unimplemented, it should return an error specific to the optional functionality that can't be provided by this Stack.
Inherited from:
Parameters:
- items the Collection of items to retain in this Stack
Returns:
-
true if the Stack changed as a result, false otherwise
- Stack:ToArray()
-
Creates a new array indexed table of this Stack.
The order of the array is the same as the order of the Stack. The first
element of the Stack will get index 1 and so on.
Inherited from:
Returns:
-
the array indexed table
See also:
- Stack:ToTable()
-
Creates a new table of this Stack.
Stacks, being ordered and linear, need no indices that are not array indices,
so this provides a table with all the same array indices as ToArray.
Inherited from:
Returns:
-
the table
See also: