Class Map
An unordered Collection of unique key value pairs.
Maps provide no particular ordering of their items, containing keys that are associated with a value. Any particular concrete Map implementation may have an internal ordering, but this ordering does not affect the operation of the Map.
The Map interface provides a base set of operations for interacting with any abstract Map type. Abstract data types may provide addtional specific operations based on the particular implemented type. Concrete implementations, such as HashMaps ultimately determine the properties of the concrete Map such as time and space complexity for any operations.
The Map interface provides certain optional methods in addition to those in Collection. Some Maps, such as immutable or type-restricted data types, may not be able to provide full functionality for these methods. All Maps are guaranteed to provide a required set of behaviors without exception and, unless otherwise noted, a method is required. All Maps should attempt to provide optional functionality, if they're able, regardless.
Implements: Collection, Enumerable
Functions
| Map.fromArray(array) | Creates a new Map from a map-formatted array. |
| Map.fromPairs(collection) | Creates a new Map from a map-formatted Collection. |
| Map.fromTable(table) | Creates a new Map from a map-formatted table. |
| Map.new() | Creates a new Map interface instance. |
Methods
| Map:Add(item) | Adds an item to the Map. |
| Map:AddAll(items) | Adds all provided items to the Map. |
| Map:Clear() | Removes everything from the Map. |
| Map:Contains(item) | Determines whether the Map contains an item. |
| Map:ContainsAll(items) | Determines whether the Map contains all of the provided items. |
| Map:ContainsAllKeys(keys) | Determines whether the Map contains all of the provided keys. |
| Map:ContainsAllValues(values) | Determines whether the Map contains all of the provided values. |
| Map:ContainsAny(items) | Determines whether the Map contains any of the provided items. |
| Map:ContainsAnyKeys(keys) | Determines whether the Map contains any of the provided keys. |
| Map:ContainsAnyValues(values) | Determines whether the Map contains any of the provided values. |
| Map:ContainsKey(key) | Determines whether the Map contains a key. |
| Map:ContainsValue(value) | Determines whether the Map contains a value. |
| Map:Count() | Gets the number of items in the Map. |
| Map:Empty() | Determines whether the Map contains no elements. |
| Map:Enumerator() | Creates an enumerator for the Map. |
| Map:Get(key) | Gets the value of the specified key. |
| Map:Keys() | Creates a Collection of this Map's keys. |
| Map:Pairs() | Creates a Collection of this Map's key value pairs. |
| Map:Remove(item) | Removes the specified item from the Map. |
| Map:RemoveAll(items) | Removes all provided items from the Map. |
| Map:RetainAll(items) | Removes all items except those provided from the Map. |
| Map:Set(key, value) | Sets the value of the specified key. |
| Map:ToArray() | Creates a new array-indexed table of this Map. |
| Map:ToTable() | Creates a new table of this Map. |
| Map:Values() | Creates a Collection of this Map's values. |
Functions
Methods- Map.fromArray(array)
-
Creates a new Map from a map-formatted array.
This constructor creates a new Map copy of an array of key value pairs. A
typical map-formatted array consists of key value pairs in the indices of
array. Each key value pair should be a table with index 1 as the key of the
pair and index 2 as the value of the pair.
Parameters:
- array the map-formatted array to copy from
Returns:
-
the new Map
- Map.fromPairs(collection)
-
Creates a new Map from a map-formatted Collection.
This constructor creates a new Map copy of a Collection of key value pairs.
A typical map-formatted Collection consists of keys value pairs. Each key
value pair should be a table with index 1 as the key of the pair and index 2
as the value of the pair.
Parameters:
- collection the map-formatted Collection to copy from
Returns:
-
the new Map
- Map.fromTable(table)
-
Creates a new Map from a map-formatted table.
This constructor creates a new Map copy of the table using its keys. A
typical map-formatted table consists of keys that have a non-nil value.
Parameters:
- table the map-formatted table to copy from
Returns:
-
the new Map
- Map.new()
-
Creates a new Map interface instance.
This should only be used when implementing a new Map.
Access:
-
private
Returns:
-
the new Map interface
Methods
- Map:Add(item)
-
Adds an item to the Map.
This method is optional. All Map 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 Map.
Inherited from:
Parameters:
- item the item to add
Returns:
-
true if the Map changed as a result, false otherwise
- Map:AddAll(items)
-
Adds all provided items to the Map.
This method is optional. All Map 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 Map.
Inherited from:
Parameters:
- items the Collection of items to add to this Map
Returns:
-
true if the Map changed as a result, false otherwise
- Map:Clear()
-
Removes everything from the Map.
This method is optional. All Map 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 Map.
Inherited from:
- Map:Contains(item)
-
Determines whether the Map contains an item.
Inherited from:
Parameters:
- item the item to locate in the Map
Returns:
-
true if the item is in the Map, false otherwise
- Map:ContainsAll(items)
-
Determines whether the Map 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 Map
Returns:
-
true if all items are in the Map, false otherwise
- Map:ContainsAllKeys(keys)
-
Determines whether the Map contains all of the provided keys.
Checks for keys provided in another Collection in an arbitrary,
deterministic order. The order is the same as the order of enumeration.
Parameters:
- keys the Collection of keys to locate in this Map
Returns:
-
true if all keys are in the Map, false otherwise
- Map:ContainsAllValues(values)
-
Determines whether the Map contains all of the provided values.
Checks for values provided in another Collection in an arbitrary,
deterministic order. The order is the same as the order of enumeration.
Parameters:
- values the Collection of values to locate in this Map
Returns:
-
true if all values are in the Map, false otherwise
- Map:ContainsAny(items)
-
Determines whether the Map 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 Map
Returns:
-
true if any items are in the Map, false otherwise
- Map:ContainsAnyKeys(keys)
-
Determines whether the Map contains any of the provided keys.
Checks for keys provided in another Collection in an arbitrary,
deterministic order. The order is the same as the order of enumeration.
Parameters:
- keys the Collection of keys to locate in this Map
Returns:
-
true if any keys are in the Map, false otherwise
- Map:ContainsAnyValues(values)
-
Determines whether the Map contains any of the provided values.
Checks for values provided in another Collection in an arbitrary,
deterministic order. The order is the same as the order of enumeration.
Parameters:
- values the Collection of values to locate in this Map
Returns:
-
true if any values are in the Map, false otherwise
- Map:ContainsKey(key)
-
Determines whether the Map contains a key.
Parameters:
- key the key to locate in the Map
Returns:
-
true if the key is in the Map, false otherwise
- Map:ContainsValue(value)
-
Determines whether the Map contains a value.
Parameters:
- value the value to locate in the Map
Returns:
-
true if the value is in the Map, false otherwise
- Map:Count()
-
Gets the number of items in the Map.
Inherited from:
Returns:
-
the number of items
- Map:Empty()
-
Determines whether the Map contains no elements.
Inherited from:
Returns:
-
true if the Map empty, false otherwise
- Map:Enumerator()
-
Creates an enumerator for the Map.
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
- Map:Get(key)
-
Gets the value of the specified key.
Parameters:
- key the key to get
Returns:
-
the value associated with the key
- Map:Keys()
-
Creates a Collection of this Map's keys.
Returns:
-
the Collection of keys
- Map:Pairs()
-
Creates a Collection of this Map's key value pairs.
Index 1 of each pair is the key and index 2 of each pair is the value.
Returns:
-
the Collection of key value pairs
- Map:Remove(item)
-
Removes the specified item from the Map.
This method is optional. All Map 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 Map.
Inherited from:
Parameters:
- item the item to remove from the Map
Returns:
-
true if the Map changed as a result, false otherwise
- Map:RemoveAll(items)
-
Removes all provided items from the Map.
Removes each instance of a provided item.
This method is optional. All Map 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 Map.
Inherited from:
Parameters:
- items the Collection of items to remove from this Map
Returns:
-
true if the Map changed as a result, false otherwise
- Map:RetainAll(items)
-
Removes all items except those provided from the Map.
Retains only the items contained in the specified Collection. If there are
duplicates they are all kept.
This method is optional. All Map 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 Map.
Inherited from:
Parameters:
- items the Collection of items to retain in this Map
Returns:
-
true if the Map changed as a result, false otherwise
- Map:Set(key, value)
-
Sets the value of the specified key.
Parameters:
- key the key to set
- value the value to set
Returns:
-
true if the value of the key changed, false otherwise
- Map:ToArray()
-
Creates a new array-indexed table of this Map.
Creates an array of key value pairs. Index 1 of each pair is the key and
index 2 of each pair is the value.
Inherited from:
Returns:
-
the array-indexed table
- Map:ToTable()
-
Creates a new table of this Map.
The indices of the table are the keys of the Map. The only values of the
table are the associated values of each key.
Inherited from:
Returns:
-
the table
- Map:Values()
-
Creates a Collection of this Map's values.
Returns:
-
the Collection of values