Packageorg.as3collections
Interfacepublic interface IMap extends IIterable, org.as3coreaddendum.system.ICloneable, org.as3coreaddendum.system.IEquatable
Implementors AbstractHashMap, TypedMap

An object that maps keys to values. A map cannot contain duplicate keys, each key can map to at most one value.

This interface provides three collection views, which allow a map's contents to be viewed as a list of keys, a list of values, or a list of key-value mappings (IMapEntry). Some map implementations, like the ArrayListMap class, make specific guarantees as to their order; others, like the HashMap class, do not.

These views, plus IMap.iterator(), enable various forms of iteration over the keys and values of the map. To iterate over the keys/values the user can use IMap.iterator() or IMap.entryList().iterator(). To iterate over the keys the user can use IMap.getKeys().iterator(). To iterate over the values the user can use IMap.getValues().iterator().

Some map implementations have restrictions on the keys and values they may contain. For example, some implementations prohibit null keys and values, and some have restrictions on the types of their keys or values.

The methods that modify the map are specified to throw org.as3coreaddendum.errors.UnsupportedOperationError if the map does not support the operation. These methods are documented as "optional operation".

This documentation is partially based in the Java Collections Framework JavaDoc documentation. For further information see Java Collections Framework

See also

AbstractHashMap
AbstractListMap
IMapEntry
IListMap


Public Properties
 PropertyDefined By
  allKeysEquatable : Boolean
[read-only] Indicates whether all keys in this map implements org.as3coreaddendum.system.IEquatable interface.
IMap
  allValuesEquatable : Boolean
[read-only] Indicates whether all values in this map implements org.as3coreaddendum.system.IEquatable interface.
IMap
Public Methods
 MethodDefined By
  
clear():void
Removes all of the mappings from this map (optional operation).
IMap
  
containsKey(key:*):Boolean
Returns true if this map contains a mapping for the specified key.
IMap
  
containsValue(value:*):Boolean
Returns true if this map maps one or more keys to the specified value.
IMap
  
Returns an ICollection object that is a view of the mappings contained in this map.
IMap
  
Returns an ICollection object that is a view of the keys contained in this map.
IMap
  
getValue(key:*):*
Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
IMap
  
Returns an ICollection object that is a view of the values contained in this map.
IMap
  
isEmpty():Boolean
Returns true if this map contains no key-value mappings.
IMap
 Inherited
Returns an iterator over a set of elements.
IIterable
  
put(key:*, value:*):*
Associates the specified value with the specified key in this map (optional operation).
IMap
  
putAll(map:IMap):void
Copies all of the mappings from the specified map to this map (optional operation).
IMap
  
putAllByObject(o:Object):void
Retrieves each property of the specified object, calling put on this map once for each property (optional operation).
IMap
  
Associates the specified entry.value with the specified entry.key in this map (optional operation).
IMap
  
remove(key:*):*
Removes the mapping for a key from this map if it is present (optional operation).
IMap
  
removeAll(keys:ICollection):Boolean
Removes the mapping for a key from this map (if it is present) for each element in the specified collection (optional operation).
IMap
  
retainAll(keys:ICollection):Boolean
Retains only the mappings in this map that the keys are contained (as elements) in the specified collection (optional operation).
IMap
  
size():int
Returns the number of key-value mappings in this map.
IMap
Property Detail
allKeysEquatableproperty
allKeysEquatable:Boolean  [read-only]

Indicates whether all keys in this map implements org.as3coreaddendum.system.IEquatable interface.


Implementation
    public function get allKeysEquatable():Boolean
allValuesEquatableproperty 
allValuesEquatable:Boolean  [read-only]

Indicates whether all values in this map implements org.as3coreaddendum.system.IEquatable interface.


Implementation
    public function get allValuesEquatable():Boolean
Method Detail
clear()method
public function clear():void

Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.


Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the clear operation is not supported by this map.
containsKey()method 
public function containsKey(key:*):Boolean

Returns true if this map contains a mapping for the specified key.

Parameters

key:* — key whose presence in this map is to be tested.

Returns
Booleantrue if this map contains a mapping for the specified key.

Throws
org.as3coreaddendum.errors:ClassCastError — if the type of the specified key is incompatible with this map (optional).
 
ArgumentError — if the specified key is null and this map does not permit null keys (optional).
containsValue()method 
public function containsValue(value:*):Boolean

Returns true if this map maps one or more keys to the specified value.

Parameters

value:* — value whose presence in this map is to be tested.

Returns
Booleantrue if this map maps one or more keys to the specified value.

Throws
org.as3coreaddendum.errors:ClassCastError — if the type of the specified value is incompatible with this map (optional).
 
ArgumentError — if the specified value is null and this map does not permit null values (optional).
entryCollection()method 
public function entryCollection():ICollection

Returns an ICollection object that is a view of the mappings contained in this map. The type of the objects within the map is IMapEntry

Modifications in the ICollection object does not affect this map.

Returns
ICollection — an ICollection object that is a view of the mappings contained in this map.

See also

getKeys()method 
public function getKeys():ICollection

Returns an ICollection object that is a view of the keys contained in this map.

Modifications in the ICollection object doesn't affect this map.

Returns
ICollection — an ICollection object that is a view of the keys contained in this map.
getValue()method 
public function getValue(key:*):*

Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

If this map permits null values, then a return value of null does not necessarily indicate that the map contains no mapping for the key. It's possible that the map explicitly maps the key to null. The containsKey method may be used to distinguish these two cases.

Parameters

key:* — the key whose associated value is to be returned.

Returns
* — the value to which the specified key is mapped, or null if this map contains no mapping for the key.

Throws
org.as3coreaddendum.errors:ClassCastError — if the type of the specified key is incompatible with this map (optional).
 
ArgumentError — if the specified key is null and this map does not permit null keys (optional).
getValues()method 
public function getValues():ICollection

Returns an ICollection object that is a view of the values contained in this map.

Modifications in the ICollection object does not affect this map.

Returns
ICollection — an ICollection object that is a view of the values contained in this map.
isEmpty()method 
public function isEmpty():Boolean

Returns true if this map contains no key-value mappings.

Returns
Booleantrue if this map contains no key-value mappings.
put()method 
public function put(key:*, value:*):*

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if m.containsKey(k) would return true.)

Parameters

key:* — key with which the specified value is to be associated.
 
value:* — value to be associated with the specified key.

Returns
* — the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key, if the implementation supports null values.)

Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the put operation is not supported by this map.
 
org.as3coreaddendum.errors:ClassCastError — if the type of the specified key or value is incompatible with this map.
 
ArgumentError — if the specified key or value is null and this map does not permit null keys or values.
putAll()method 
public function putAll(map:IMap):void

Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map.

Parameters

map:IMap — mappings to be stored in this map.


Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the putAll operation is not supported by this map.
 
org.as3coreaddendum.errors:ClassCastError — if the type of a key or value in the specified map is incompatible with this map.
 
ArgumentError — if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values.
putAllByObject()method 
public function putAllByObject(o:Object):void

Retrieves each property of the specified object, calling put on this map once for each property (optional operation).

Parameters

o:Object — the object to retrieve the properties.


Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the putAllByObject operation is not supported by this map.
 
org.as3coreaddendum.errors:ClassCastError — if the type of a key or value in the specified object is incompatible with this map.
 
ArgumentError — if the specified object is null, or if this map does not permit null keys or values, and the specified object contains null keys or values.
putEntry()method 
public function putEntry(entry:IMapEntry):*

Associates the specified entry.value with the specified entry.key in this map (optional operation). If the map previously contained a mapping for the entry.key, the old value is replaced by the specified entry.value. (A map m is said to contain a mapping for a key k if and only if m.containsKey(k) would return true.)

The effect of this call is equivalent to that of calling put(entry.key, entry.value) on this map.

Parameters

entry:IMapEntry — entry to put in this map.

Returns
* — the previous value associated with entry.key, or null if there was no mapping for entry.key. (A null return can also indicate that the map previously associated null with entry.key, if the implementation supports null values.)

Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the putEntry operation is not supported by this map.
 
org.as3coreaddendum.errors:ClassCastError — if the type of the specified entry.key or entry.value is incompatible with this map.
 
ArgumentError — if the specified entry is null, or if the specified entry.key or entry.value is null and this map does not permit null keys or values.
remove()method 
public function remove(key:*):*

Removes the mapping for a key from this map if it is present (optional operation).

Returns the value to which this map previously associated the key, or null if the map contained no mapping for the key. If this map permits null values, then a return value of null does not necessarily indicate that the map contained no mapping for the key. It's possible that the map explicitly mapped the key to null.

The map will not contain a mapping for the specified key once the call returns.

Parameters

key:* — the key whose mapping is to be removed from the map.

Returns
* — the previous value associated with key, or null if there was no mapping for key.

Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the remove operation is not supported by this map.
 
org.as3coreaddendum.errors:ClassCastError — if the type of the specified key is incompatible with this map (optional).
 
ArgumentError — if the specified key is null and this map does not permit null keys (optional).
removeAll()method 
public function removeAll(keys:ICollection):Boolean

Removes the mapping for a key from this map (if it is present) for each element in the specified collection (optional operation). The elements in the specified collection are interpreted as keys.

The effect of this call is equivalent to that of calling remove on this map once for each element in the speficied collection.

The map will not contain mappings for the elements in the specified collection once the call returns.

Parameters

keys:ICollection — the collection whose elements are interpreted as keys to be removed from the map.

Returns
Booleantrue if this map changed as a result of the call.

Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the removeAll operation is not supported by this map.
 
org.as3coreaddendum.errors:ClassCastError — if the type of an element in the specified collection is incompatible with this map (optional).
 
ArgumentError — if the specified collection is null, or if this map does not permit null keys, and the specified collections contains null elements (optional).
retainAll()method 
public function retainAll(keys:ICollection):Boolean

Retains only the mappings in this map that the keys are contained (as elements) in the specified collection (optional operation). In other words, removes from this map all of its mappings whose keys are not contained (as elements) in the specified collection. The elements in the specified collection are interpreted as keys.

Parameters

keys:ICollection — the collection whose elements are interpreted as keys to be retained in the map.

Returns
Booleantrue if this map changed as a result of the call.

Throws
org.as3coreaddendum.errors:UnsupportedOperationError — if the retainAll operation is not supported by this map.
 
org.as3coreaddendum.errors:ClassCastError — if the types of one or more keys in this map are incompatible with the specified collection (optional).
 
ArgumentError — if the specified collection contains a null element and this collection does not permit null keys (optional), or if the specified collection is null.
size()method 
public function size():int

Returns the number of key-value mappings in this map.

Returns
int — the number of key-value mappings in this map.