Map

map map( [array keys , array values] )

keys array An array of keys to be paired with the values
values array An array of values to be paired with the keys
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.

bool map_add( map map_obj , string key , mixed value )

map_obj map The map object being accessed.
key string The key that will be linked with the value.
value mixed The value that is linked to the key.
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.

bool map_clear( map map_obj )

map_obj map The map object being accessed.
Removes all keys and values from the map.

int map_compare( map map_obj , string lhs , string rhs )

map_obj map The map object being accessed.
lhs string The left-hand side map key to compare.
rhs string The right-hand side map key to compare.
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.

bool map_contains( map map_obj , string key )

map_obj map The map object being accessed.
key string The key to be checked.
Return true if the specified key is contained in the map.

int map_count( map map_obj )

map_obj map The map object being accessed.
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.

mixed map_get( map map_obj , string key )

map_obj map The map object being accessed.
key string The key that links to a value in the map.
Returns the value contained in the map associated with the specified key.

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

bool map_is_empty( map map_obj )

map_obj map The map object being accessed.
Returns true if the map is empty, ie: contains no keys/values, else false.

array map_keys( map map_obj )

map_obj map The map object being accessed.
Returns an array that can be used to iterate through all keys in a map.

int map_remove( map map_obj , string key )

map_obj map The map object being accessed.
key string The key that will be removed from the map.
Removes the key from the map.

bool map_set( map map_obj , string key , mixed value )

map_obj map The map object being accessed.
key string The key that will be linked with the value.
value mixed The value that is linked to the key.
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).

bool map_update( map map_obj , string key , mixed value )

map_obj map The map object being accessed.
key string The key that will be linked with the value.
value mixed The value that is linked to the key.
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.

array map_values( map map_obj )

map_obj map The map object being accessed.
Returns an array that can be used to iterate through all values in the map.