Packageorg.as3collections
Classpublic class AbstractHashMap
InheritanceAbstractHashMap Inheritance Object
Implements IMap
Subclasses HashMap, ReadOnlyHashMap

This class provides a skeletal hash table based implementation of the IMap interface, to minimize the effort required to implement this interface.

This is an abstract class and shouldn't be instantiated directly.

This class maintains a native flash.utils.Dictionary object as its source.

This class makes no guarantees as to the order of the map. In particular, it does not guarantee that the order will remain constant over time.

The documentation for each non-abstract method in this class describes its implementation in detail. Each of these methods may be overridden if the map being implemented admits a more efficient implementation.

IMPORTANT:

This class implements equality through org.as3coreaddendum.system.IEquatable interface in the equals method and in all methods that compares the elements inside this collection (i.e. containsKey, containsValue, put, remove, removeAll and retainAll).

In order to this map uses the equals method of its keys and/or values in comparisons (rather than default '==' operator), all keys and/or values in this map must implement the org.as3coreaddendum.system.IEquatable interface and also the supplied key and/or value.

For example:

myMap.containsKey(myKey);

All keys (but in this case only keys) inside myMap, and myKey, must implement the org.as3coreaddendum.system.IEquatable interface so that equals method of each key can be used in the comparison. Otherwise '==' operator is used. The same is true for values. The use of equality for keys and values are independent. It's possible to use only keys that implement IEquatable, only values, both, or none. This usage varies according to application needs.

All subclasses of this class must conform with this behavior.

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

See also

IMap
HashMap
AbstractListMap
org.as3coreaddendum.system.IEquatable


Public Properties
 PropertyDefined By
  allKeysEquatable : Boolean
[read-only] Indicates whether all keys in this map implements org.as3coreaddendum.system.IEquatable interface.
AbstractHashMap
  allValuesEquatable : Boolean
[read-only] Indicates whether all values in this map implements org.as3coreaddendum.system.IEquatable interface.
AbstractHashMap
Public Methods
 MethodDefined By
  
AbstractHashMap(source:IMap = null, weakKeys:Boolean = false)
Constructor, creates a new AbstractHashMap object.
AbstractHashMap
  
clear():void
Removes all of the mappings from this map (optional operation).
AbstractHashMap
  
clone():*
Creates and return a shallow copy of this collection.
AbstractHashMap
  
containsKey(key:*):Boolean
Returns true if this map contains a mapping for the specified key.
AbstractHashMap
  
containsValue(value:*):Boolean
Returns true if this map maps one or more keys to the specified value.
AbstractHashMap
  
Returns an ArrayList object that is a view of the mappings contained in this map.
AbstractHashMap
  
equals(other:*):Boolean
This method uses MapUtil.equalNotConsideringOrder method to perform equality, sending this map and other argument.
AbstractHashMap
  
Returns an ArrayList object that is a view of the keys contained in this map.
AbstractHashMap
  
getValue(key:*):*
Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
AbstractHashMap
  
Returns an ArrayList object that is a view of the values contained in this map.
AbstractHashMap
  
isEmpty():Boolean
Returns true if this map contains no key-value mappings.
AbstractHashMap
  
Returns an iterator over a set of mappings.
AbstractHashMap
  
put(key:*, value:*):*
Associates the specified value with the specified key in this map (optional operation).
AbstractHashMap
  
putAll(map:IMap):void
Copies all of the mappings from the specified map to this map (optional operation).
AbstractHashMap
  
putAllByObject(o:Object):void
This implementation performs a for..in in the specified object, calling put on this map once for each iteration (optional operation).
AbstractHashMap
  
Associates the specified entry.value with the specified entry.key in this map (optional operation).
AbstractHashMap
  
remove(key:*):*
Removes the mapping for a key from this map if it is present (optional operation).
AbstractHashMap
  
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).
AbstractHashMap
  
retainAll(keys:ICollection):Boolean
Retains only the mappings in this map that the keys are contained (as elements) in the specified collection (optional operation).
AbstractHashMap
  
size():int
Returns the number of key-value mappings in this map.
AbstractHashMap
  
toString():String
Returns the string representation of this instance.
AbstractHashMap
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
Constructor Detail
AbstractHashMap()Constructor
public function AbstractHashMap(source:IMap = null, weakKeys:Boolean = false)

Constructor, creates a new AbstractHashMap object.

Parameters
source:IMap (default = null) — a map with wich fill this map.
 
weakKeys:Boolean (default = false) — instructs the backed Dictionary object to use "weak" references on object keys. If the only reference to an object is in the specified Dictionary object, the key is eligible for garbage collection and is removed from the table when the object is collected.

Throws
IllegalOperationError — If this class is instantiated directly, in other words, if there is not another class extending this class.
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.

This implementation always throws an UnsupportedOperationError.


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

Creates and return a shallow copy of this collection.

This implementation always throws a CloneNotSupportedError.

Returns
* — A new object that is a shallow copy of this instance.

Throws
org.as3coreaddendum.errors:CloneNotSupportedError — if this map doesn't support clone.
containsKey()method 
public function containsKey(key:*):Boolean

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

If all keys in this map and key argument implement org.as3coreaddendum.system.IEquatable, this implementation will iterate over this map using equals method of the keys. Otherwise this implementation uses Dictionary[key] !== undefined.

Parameters

key:*

Returns
Boolean

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.

If all values in this map and value argument implement org.as3coreaddendum.system.IEquatable, this implementation will iterate over this map using equals method of the values. Otherwise this implementation uses Dictionary[value] !== undefined.

Parameters

value:*

Returns
Boolean

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 ArrayList object that is a view of the mappings contained in this map. The type of the objects within the list is IMapEntry

There's no guarantee that the order will remain constant over time.

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

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

See also

equals()method 
public function equals(other:*):Boolean

This method uses MapUtil.equalNotConsideringOrder method to perform equality, sending this map and other argument.

Parameters

other:* — the object to be compared for equality.

Returns
Booleantrue if the arbitrary evaluation considers the objects equal.

See also

getKeys()method 
public function getKeys():ICollection

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

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

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

See also

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.

If all keys in this map and key argument implement org.as3coreaddendum.system.IEquatable, this implementation will iterate over this map using equals method of the keys. Otherwise this implementation returns Dictionary[key].

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 ArrayList object that is a view of the values contained in this map.

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

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

See also

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.
iterator()method 
public function iterator():IIterator

Returns an iterator over a set of mappings.

This implementation always throws an UnsupportedOperationError.

Returns
IIterator — an iterator over a set of values.

Throws
org.as3coreaddendum.errors:UnsupportedOperationError — this method must be overridden in subclass.
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.)

This implementation always throws an UnsupportedOperationError.

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.

This implementation iterates over the specified map, and calls this map's put operation once for each entry returned by the iteration.

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

This implementation performs a for..in in the specified object, calling put on this map once for each iteration (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.)

This implementation calls put(entry.key, entry.value).

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.

This implementation always throws an UnsupportedOperationError.

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.

This implementation iterates over this map, checking each key returned by the iterator in turn to see if it's contained in the specified keys collection (using contains method of the keys argument). If it's so contained, it's removed from this map with the iterator's remove method.

Note that this implementation will throw an UnsupportedOperationError if the iterator returned by the iterator method does not implement the remove method and this map contains one or more keys in common with the specified 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 keys collection (using contains method of the keys argument). The elements in the specified collection are interpreted as keys.

This implementation iterates over this map and calls IIterator.remove once for each key that are not contained in the specified collection.

Note that this implementation will throw an UnsupportedOperationError if the iterator returned by the iterator method does not implement the remove method and this map contains one or more keys not present in the specified collection.

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.
toString()method 
public function toString():String

Returns the string representation of this instance.

This method uses MapUtil.toString method.

Returns
String — the string representation of this instance.

See also