Monolith

• Index

Contents

• Functions
• Methods

Classes

• AbstractList
• ArrayList
• ArrayStack
• Collection
• Deque
• Enumerable
• HashMap
• HashSet
• LinkedDeque
• LinkedList
• LinkedQueue
• List
• Map
• Queue
• Set
• Stack

Modules

• Monolith

Class List

An ordered, linear Collection of items.

Lists have a distinct, linear ordering of items that can be accessed by index. Additionally, they have a first and last element, can be sorted, and can be searched.

The List interface provides a base set of operations for interacting with any abstract List type. Abstract data types may provide addtional specific operations based on the particular implemented type. Concrete implementations, such as LinkedLists or ArrayLists, ultimately determine the properties of the concrete List such as time and space complexity for any operations.

The List interface provides certain optional methods in addition to those in Collection. Some Lists, such as immutable or type-restricted data types, may not be able to provide full functionality for these methods. All Lists are guaranteed to provide a required set of behaviors without exception and, unless otherwise noted, a method is required. All Lists should attempt to provide optional functionality, if they're able, regardless.

Implements: Collection, Enumerable

Functions

List.new()

Creates a new List interface instance.

Methods

List:Add(item)	Adds an item to the List.
List:AddAll(items)	Adds all provided items to the List.
List:Clear()	Removes everything from the List.
List:Contains(item)	Determines whether the List contains an item.
List:ContainsAll(items)	Determines whether the List contains all of the provided items.
List:ContainsAny(items)	Determines whether the List contains any of the provided items.
List:Count()	Gets the number of items in the List.
List:Delete(index)	Removes the item at the specified index from the List.
List:Empty()	Determines whether the List contains no elements.
List:Enumerator()	Creates an enumerator for the List.
List:First()	Gets the item at the beginning of the List.
List:Get(index)	Gets the item at the specified index in the List.
List:IndexOf(item, index)	Determines the index of a specific item in the List.
List:Insert(index, item)	Inserts the item into the List at the specified index.
List:InsertAll(index, items)	Inserts all items into the List at the specified index.
List:Last()	Gets the item at the end of the List.
List:LastIndexOf(item)	Determines the last index of a specific item in the List.
List:Pop()	Gets an item from the end and removes that item from the List.
List:Push(item)	Adds an item to the end of the List.
List:Remove(item)	Removes the specified item from the List.
List:RemoveAll(items)	Removes all provided items from the List.
List:RetainAll(items)	Removes all items except those provided from the List.
List:Set(index)	Sets the element at the specified index.
List:Shift()	Gets an item from the beginning and removes that item from the List.
List:Sub(first, last)	Creates a new sub-List of this List.
List:ToArray()	Creates a new array-indexed table of this List.
List:ToTable()	Creates a new table of this List.
List:Unshift(item)	Adds an item to the beginning of the List.

Functions

Methods

List.new()

Creates a new List interface instance. This should only be used when implementing a new List.

Access:

private

Returns:

the new List interface

Methods

List:Add(item)

Adds an item to the List.

This method is optional. All List 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 List.

Inherited from:

Collection

Parameters:

• item the item to add

Returns:

true if the List changed as a result, false otherwise

List:AddAll(items)

Adds all provided items to the List. 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 List 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 List.

Inherited from:

Collection

Parameters:

• items the Collection of items to add to this List

Returns:

true if the List changed as a result, false otherwise

List:Clear()

Removes everything from the List.

This method is optional. All List 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 List.

Inherited from:

Collection

List:Contains(item)

Determines whether the List contains an item.

Inherited from:

Collection

Parameters:

• item the item to locate in the List

Returns:

true if the item is in the List, false otherwise

List:ContainsAll(items)

Determines whether the List 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:

Collection

Parameters:

• items the Collection of items to locate in this List

Returns:

true if all items are in the List, false otherwise

List:ContainsAny(items)

Determines whether the List 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:

Collection

Parameters:

• items the Collection of items to locate in this List

Returns:

true if any items are in the List, false otherwise

List:Count()

Gets the number of items in the List.

Inherited from:

Collection

Returns:

the number of items

List:Delete(index)

Removes the item at the specified index from the List. Shifts other elements to fill the gap left at the index of removal.

This method is optional. All List 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 List.

Parameters:

• index the index of the item to remove from the List

Returns:

true if the List changed as a result, false otherwise

Raises:

if the index is out of bounds of the List

List:Empty()

Determines whether the List contains no elements.

Inherited from:

Collection

Returns:

true if the List empty, false otherwise

List:Enumerator()

Creates an enumerator for the List. The enumerator can be used directly in a generic for loop similar to pairs or ipairs.

Inherited from:

Enumerable

Returns:

1. the enumerator generator
2. the invariant state
3. the control variable state

List:First()

Gets the item at the beginning of the List.

Returns:

the first item in the List

Raises:

if the List is empty

List:Get(index)

Gets the item at the specified index in the List.

Parameters:

• index the index to get

Returns:

the item in the List at the specified index

Raises:

if the index is out of bounds of the List

List:IndexOf(item, index)

Determines the index of a specific item in the List. Starts from a specified index or from the beginning if none is provided.

Parameters:

• item the item to locate
• index the index to start looking from

Returns:

the index of the item in the List if found, 0 otherwise

Raises:

if the index is out of bounds of the List

List:Insert(index, item)

Inserts the item into the List at the specified index. Shifts other elements to make space at the index of insertion.

This method is optional. All List 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 List.

Parameters:

• index the index to insert the item in the List
• item the item to add

Returns:

true if the List changed as a result, false otherwise

Raises:

if the index is out of bounds of the List

List:InsertAll(index, items)

Inserts all items into the List at the specified index. Inserts all items from the provided Collection in an arbitrary, deterministic order. The order is the same as the order of enumeration.

Shifts other elements to make space at the index of insertion.

This method is optional. All List 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 List.

Parameters:

• index the index to insert the items in the List
• items the Collection of items to add to this List

Returns:

true if the List changed as a result, false otherwise

Raises:

if the index is out of bounds of the List

List:Last()

Gets the item at the end of the List.

Returns:

the last item in the List

Raises:

if the List is empty

List:LastIndexOf(item)

Determines the last index of a specific item in the List. Only returns the very last occurrence of the item in the List.

Parameters:

• item the item to locate

Returns:

the index of the item in the List if found, 0 otherwise

List:Pop()

Gets an item from the end and removes that item from the List.

This method is optional. All List 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 List.

Returns:

the item in the List

Raises:

if the List is empty

List:Push(item)

Adds an item to the end of the List.

This method is optional. All List 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 List.

Parameters:

• item the item to add

Returns:

true if the List changed as a result, false otherwise

List:Remove(item)

Removes the specified item from the List. 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 List 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 List.

Inherited from:

Collection

Parameters:

• item the item to remove from the List

Returns:

true if the List changed as a result, false otherwise

List:RemoveAll(items)

Removes all provided items from the List. Removes each instance of a provided item only once for each time provided. If there are multiple of the same item in this List, it removes only the first encountered for each provided.

This method is optional. All List 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 List.

Inherited from:

Collection

Parameters:

• items the Collection of items to remove from this List

Returns:

true if the List changed as a result, false otherwise

List:RetainAll(items)

Removes all items except those provided from the List. Retains only the items contained in the specified Collection. If there are duplicates they are all kept.

This method is optional. All List 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 List.

Inherited from:

Collection

Parameters:

• items the Collection of items to retain in this List

Returns:

true if the List changed as a result, false otherwise

List:Set(index)

Sets the element at the specified index.

This method is optional. All List 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 List.

Parameters:

• index the index to set

Returns:

true if the List changed as a result, false otherwise

Raises:

if the index is out of bounds of the List

List:Shift()

Gets an item from the beginning and removes that item from the List. Shifts other elements to fill the gap left.

This method is optional. All List 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 List.

Returns:

the item in the List

Raises:

if the List is empty

List:Sub(first, last)

Creates a new sub-List of this List. Creates the list that is the portion of this List between the specified indices or from the first sepecified index to the end if only one index is specified.

Parameters:

• first the index to start at
• last the index to end at

Returns:

the new List

Raises:

• if the first index is out of bounds
• if the last index is out of bounds
• if the last index is smaller than the first index

List:ToArray()

Creates a new array-indexed table of this List. The order of the array is the same as the order of the List and uses the same indexing.

Inherited from:

Collection

Returns:

the array indexed table

See also:

ToTable

List:ToTable()

Creates a new table of this List. Lists, being ordered and linear, use no indices that are not array indices, so this provides a table with all the same array indices as ToArray.

Inherited from:

Collection

Returns:

the table

See also:

ToArray

List:Unshift(item)

Adds an item to the beginning of the List. Shifts other elements to make space.

This method is optional. All List 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 List.

Parameters:

• item the item to add

Returns:

true if the List changed as a result, false otherwise