Class Collection
A group of items.
The Collection interface is the base interface for all Monolith collections and represents a group of objects called items or elements.
The Collection interface provides a base set of operations for interacting with any abstract Collection type. Abstract data types, such as Lists or Queues, provide addtional specific operations based on the particular implemented type. Concrete implementations, such as LinkedLists or ArrayLists, ultimately determine the properties of the concrete Collection such as time and space complexity for any operations.
The Collection interface provides certain optional methods. Some Collections, such as immutable or type-restricted data types, may not be able to provide full functionality for these methods. All Collections are guaranteed to provide a required set of behaviors without exception and, unless otherwise noted, a method is required. All Collections should attempt to provide optional functionality, if they're able, regardless.
Implements: Enumerable
Functions
| Collection.new() | Creates a new Collection interface instance. |
Methods
| Collection:Add(item) | Adds an item to the Collection. |
| Collection:AddAll(items) | Adds all provided items to the Collection. |
| Collection:Clear() | Removes everything from the Collection. |
| Collection:Contains(item) | Determines whether the Collection contains an item. |
| Collection:ContainsAll(items) | Determines whether the Collection contains all of the provided items. |
| Collection:ContainsAny(items) | Determines whether the Collection contains any of the provided items. |
| Collection:Count() | Gets the number of items in the Collection. |
| Collection:Empty() | Determines whether the Collection contains no elements. |
| Collection:Enumerator() | Creates an enumerator for the Collection. |
| Collection:Remove(item) | Removes the specified item from the Collection. |
| Collection:RemoveAll(items) | Removes all provided items from the Collection. |
| Collection:RetainAll(items) | Removes all items except those provided from the Collection. |
| Collection:ToArray() | Creates a new array-indexed table of this Collection. |
| Collection:ToTable() | Creates a new table of this Collection. |
Functions
Methods- Collection.new()
-
Creates a new Collection interface instance.
This should only be used when implementing a new Collection.
Access:
-
private
Returns:
-
the new Collection interface
Methods
- Collection:Add(item)
-
Adds an item to the Collection.
This method is optional. All Collection 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 Collection.
Parameters:
- item the item to add
Returns:
-
true if the Collection changed as a result, false otherwise
- Collection:AddAll(items)
-
Adds all provided items to the Collection.
Adds items provided in another Collection in an arbitrary, deterministic
order.
This method is optional. All Collection 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 Collection.
Parameters:
- items the Collection of items to add to this Collection
Returns:
-
true if the Collection changed as a result, false otherwise
- Collection:Clear()
-
Removes everything from the Collection.
This method is optional. All Collection 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 Collection.
- Collection:Contains(item)
-
Determines whether the Collection contains an item.
Parameters:
- item the item to locate in the Collection
Returns:
-
true if the item is in the Collection, false otherwise
- Collection:ContainsAll(items)
-
Determines whether the Collection contains all of the provided items.
Checks for items provided in another Collection in an arbitrary,
deterministic order.
Parameters:
- items the Collection of items to locate in this Collection
Returns:
-
true if all items are in the Collection, false otherwise
- Collection:ContainsAny(items)
-
Determines whether the Collection contains any of the provided items.
Checks for items provided in another Collection in an arbitrary,
deterministic order.
Parameters:
- items the Collection of items to locate in this Collection
Returns:
-
true if any items are in the Collection, false otherwise
- Collection:Count()
-
Gets the number of items in the Collection.
Returns:
-
the number of items
- Collection:Empty()
-
Determines whether the Collection contains no elements.
Returns:
-
true if the Collection empty, false otherwise
- Collection:Enumerator()
-
Creates an enumerator for the Collection.
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
- Collection:Remove(item)
-
Removes the specified item from the Collection.
Removes a single item. If there are multiple of the same item, it removes
only the first encountered.
This method is optional. All Collection 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 Collection.
Parameters:
- item the item to remove from the Collection
Returns:
-
true if the Collection changed as a result, false otherwise
- Collection:RemoveAll(items)
-
Removes all provided items from the Collection.
Removes each instance of a provided item only once for each time provided.
If there are multiple of the same item in this Collection, it removes only
the first encountered for each provided.
This method is optional. All Collection 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 Collection.
Parameters:
- items the Collection of items to remove from this Collection
Returns:
-
true if the Collection changed as a result, false otherwise
- Collection:RetainAll(items)
-
Removes all items except those provided from the Collection.
Retains only the items contained in the specified Collection.
This method is optional. All Collection 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 Collection.
Parameters:
- items the Collection of items to retain in this Collection
Returns:
-
true if the Collection changed as a result, false otherwise
- Collection:ToArray()
-
Creates a new array-indexed table of this Collection.
There is no guaranteed order of the array, but all elements of the
Collection are guaranteed to exist in the array indices of the table, i.e.
all elements can be traversed with ipairs. The ordering is also created
deterministically, i.e. it will be the same each time its created for the
same elements in a particular Collection.
Returns:
-
the array indexed table
See also:
- Collection:ToTable()
-
Creates a new table of this Collection.
This is a more generalized form of ToArray, able to use any indices of
the table provided, not only array indices.
The particular Collection implementation may or may not use non-array indices of the table, i.e. some elements of the table may need to be traversed with pairs rather than ipairs. This may preserve the structure of the particular Collection implementation better than ToArray, e.g. a Map has a near one-to-one correspondence with such a table.
Returns:
-
the table
See also: