Class Map<K,V>

A map is a container style object that provides a mechanism for associating key objects with value objects. More...

Declarations

Extended By
`FloatMap` , `IntMap` , `StringMap`

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

Methods
`Add : Bool ( key:K, value:V )`	Adds a key/value pair to the map.
`Clear : Int ()`	Removes all keys and values from the map.
`Compare : Int ( lhs:K, rhs:K )`	The compare method must return a negative value if lhs < rhs, a positive value if lhs > rhs, or 0 if lhs = rhs.
`Contains : Bool ( key:K )`	Return true if the specified key is contained in the map.
`Count : Int ()`	Returns the number of key/value pairs in the map.
`FirstNode : Node<K,V> ()`	Returns the first node in the map.
`Get : V ( key:K )`	Returns the value contained in the map associated with the specified key.
`IsEmpty : Bool ()`	Returns True if the map is empty, ie: contains no keys/values, else False.
`Keys : Object ()`	Returns an object that can be used to iterate through all keys in a map with a For Eachin loop.
`LastNode : Node<K,V> ()`	Returns the last node in the map.
`ObjectEnumerator : Object ()`	Returns an object that can be used to enumerate all nodes in the map with a For EachIn loop.
`Remove : Int ( key:K )`	Removes the key from the map.
`Set : Bool ( key:K, value:V )`	Set the value in a map associated with the given key.
`Update : Bool ( key:K, value:V )`	Updates an existing key/value pair.
`Values : Object ()`	Returns an object that can be used to enumerate all values in the map with a For Eachin loop.

Detailed Discussion

A map is a container style object that provides a mechanism for associating key objects with value objects. This is done using special node objects that contains a reference to both a key and a value, along with information about the node's location within the map.

Each key in a map occurs exactly once - a map cannot contain multiple equivalent keys.

Maps are very efficient, and can handle inserting, removing and finding keys in 'O(log2)' time. That is, the time needed to insert, remove or find a key is proportional to log2 of the number of items in the map.

Classes that extend map must implement the Compare method. This method is used by the map to compare keys, and must return -1 if the first key is less than the second, +1 if the first key is greater than the second, or 0 if the keys are equal.

Methods Documentation

Method Add : Bool ( key:K, value:V )

Adds a key/value pair to the map.

The map is only modified if it does not already contain the given key, in which case a new key/value association is created and true is returned.

If the map already contains key, it is not modified and false is returned.

Parameters

key, value - key/value pair to add to map.

See also

Set, Get

Method Clear : Int ()

Removes all keys and values from the map.

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

The compare method must return a negative value if lhs < rhs, a positive value if lhs > rhs, or 0 if lhs = rhs.

The compare method is abstract so must be implemented by all subclasses of Map.

Method Contains : Bool ( key:K )

Return true if the specified key is contained in the map.

Parameters

key - value to check

Method Count : Int ()

Returns the number of key/value pairs in the map.

Note that this method takes O(N) time, ie: it must visit each element of the map.

Method FirstNode : Node<K,V> ()

Returns the first node in the map. This is the node with the minimum key value.

Method Get : V ( key:K )

Returns the value contained in the map associated with the specified key.

If the key is not contained in the map, null is returned.

Parameters

key - key to find value for.

See also

Add, Set

Method IsEmpty : Bool ()

Returns True if the map is empty, ie: contains no keys/values, else False.

Method Keys : Object ()

Returns an object that can be used to iterate through all keys in a map with a For Eachin loop.

Method LastNode : Node<K,V> ()

Returns the last node in the map. This is the node with the maximum key value.

Method ObjectEnumerator : Object ()

Returns an object that can be used to enumerate all nodes in the map with a For EachIn loop.

See also

Node

Method Remove : Int ( key:K )

Removes the key from the map.

Parameters

key - key to remove

Method Set : Bool ( key:K, value:V )

Set the value in a map associated with the given key.

Returns true if key was added to the map, or false if map already contained the given key.

The map is always updated - the return value only indicates whether an existing key/value association was updated (false) or a new one created (true).

Parameters

key, value - key/value pair to set.

See also

Add, Get

Method Update : Bool ( key:K, value:V )

Updates an existing key/value pair.

If the map does not contain key, the map is not modified and false is returned.

Otherwise, the map is updated and true is returned.

Method Values : Object ()

Returns an object that can be used to enumerate all values in the map with a For Eachin loop.