Coverage Report

Coverage Report - org.as3collections.IMap

Classes in this File

0/1

 ﻿/*
  * Licensed under the MIT License
  * 
  * Copyright 2010 (c) Flávio Silva, http://flsilva.com
  *
  * Permission is hereby granted, free of charge, to any person
  * obtaining a copy of this software and associated documentation
  * files (the "Software"), to deal in the Software without
  * restriction, including without limitation the rights to use,
  * copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the
  * Software is furnished to do so, subject to the following
  * conditions:
  *
  * The above copyright notice and this permission notice shall be
  * included in all copies or substantial portions of the Software.
  *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  * OTHER DEALINGS IN THE SOFTWARE.
  * 
  * http://www.opensource.org/licenses/mit-license.php
  */
 
 package org.as3collections
 {
         import org.as3coreaddendum.system.ICloneable;
         import org.as3coreaddendum.system.IEquatable;
 
         /**
          * An object that maps keys to values.
          * A map cannot contain duplicate keys, each key can map to at most one value.
          * <p>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 (<code>IMapEntry</code>).
          * Some map implementations, like the <code>ArrayListMap</code> class, make specific guarantees as to their order; others, like the <code>HashMap</code> class, do not.</p>
          * <p>These views, plus <code>IMap.iterator()</code>, enable various forms of iteration over the keys and values of the map.
          * To iterate over the keys/values the user can use <code>IMap.iterator()</code> or <code>IMap.entryList().iterator()</code>.
          * To iterate over the keys the user can use <code>IMap.getKeys().iterator()</code>.
          * To iterate over the values the user can use <code>IMap.getValues().iterator()</code>.</p>
          * <p>Some map implementations have restrictions on the keys and values they may contain.
          * For example, some implementations prohibit <code>null</code> keys and values, and some have restrictions on the types of their keys or values.</p>
          * <p>The methods that modify the map are specified to throw <code>org.as3coreaddendum.errors.UnsupportedOperationError</code> if the map does not support the operation.
          * These methods are documented as "optional operation".</p>
          * <p>This documentation is partially based in the <em>Java Collections Framework</em> JavaDoc documentation.
          * For further information see <a href="http://download.oracle.com/javase/6/docs/technotes/guides/collections/index.html" target="_blank">Java Collections Framework</a></p>
          * 
          * @see org.as3collections.AbstractHashMap AbstractHashMap
          * @see org.as3collections.AbstractListMap AbstractListMap
          * @see org.as3collections.IMapEntry IMapEntry
          * @see org.as3collections.IListMap IListMap
          * @author Flávio Silva
          */
         public interface IMap extends IIterable, ICloneable, IEquatable
         {
                 /**
                  * Indicates whether all keys in this map implements <code>org.as3coreaddendum.system.IEquatable</code> interface.
                  */
                 function get allKeysEquatable(): Boolean;
 
                 /**
                  * Indicates whether all values in this map implements <code>org.as3coreaddendum.system.IEquatable</code> interface.
                  */
                 function get allValuesEquatable(): Boolean;
 
                 /**
                  * 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 <code>clear</code> operation is not supported by this map.
                  */
                 function clear(): void;
 
                 /**
                  * Returns <code>true</code> if this map contains a mapping for the specified key.
                  * 
                  * @param          key         key whose presence in this map is to be tested.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                  if the type of the specified key is incompatible with this map (optional).
                  * @throws         ArgumentError          if the specified key is <code>null</code> and this map does not permit <code>null</code> keys (optional).
                  * @return         <code>true</code> if this map contains a mapping for the specified key.
                  */
                 function containsKey(key:*): Boolean;
 
                 /**
                  * Returns <code>true</code> if this map maps one or more keys to the specified value.
                  * 
                  * @param          value         value whose presence in this map is to be tested.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                  if the type of the specified value is incompatible with this map (optional).
                  * @throws         ArgumentError          if the specified value is <code>null</code> and this map does not permit <code>null</code> values (optional).
                  * @return         <code>true</code> if this map maps one or more keys to the specified value.
                  */
                 function containsValue(value:*): Boolean;
 
                 /**
                  * Returns an <code>ICollection</code> object that is a view of the mappings contained in this map.
                  * The type of the objects within the map is <code>IMapEntry</code>
                  * <p>Modifications in the <code>ICollection</code> object does not affect this map.</p>
                  * 
                  * @return         an <code>ICollection</code> object that is a view of the mappings contained in this map.
                  * @see org.as3collections.IMapEntry IMapEntry
                  * @see org.as3collections.ICollection ICollection
                   */
                 function entryCollection(): ICollection;
 
                 /**
                  * Returns an <code>ICollection</code> object that is a view of the keys contained in this map.
                  * <p>Modifications in the <code>ICollection</code> object doesn't affect this map.</p>
                  * 
                  * @return         an <code>ICollection</code> object that is a view of the keys contained in this map.
                   */
                 function getKeys(): ICollection;
 
                 /**
                  * Returns the value to which the specified key is mapped, or <code>null</code> if this map contains no mapping for the key.
                  * <p>If this map permits <code>null</code> values, then a return value of <code>null</code> does not <em>necessarily</em> indicate that the map contains no mapping for the key.
                  * It's possible that the map explicitly maps the key to <code>null</code>.
                  * The <code>containsKey</code> method may be used to distinguish these two cases.</p>
                  * 
                  * @param          key         the key whose associated value is to be returned.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                  if the type of the specified key is incompatible with this map (optional).
                  * @throws         ArgumentError          if the specified key is <code>null</code> and this map does not permit <code>null</code> keys (optional).
                  * @return         the value to which the specified key is mapped, or <code>null</code> if this map contains no mapping for the key.
                  */
                 function getValue(key:*): *;
 
                 /**
                  * Returns an <code>ICollection</code> object that is a view of the values contained in this map.
                  * <p>Modifications in the <code>ICollection</code> object does not affect this map.</p>
                  * 
                  * @return         an <code>ICollection</code> object that is a view of the values contained in this map.
                   */
                 function getValues(): ICollection;
 
                 /**
                  * Returns <code>true</code> if this map contains no key-value mappings.
                  * 
                  * @return         <code>true</code> if this map contains no key-value mappings.
                   */
                 function isEmpty(): Boolean;
 
                 /**
                  * 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 <code>m</code> is said to contain a mapping for a key <code>k</code> if and only if <code>m.containsKey(k)</code> would return <code>true</code>.) 
                  * 
                  * @param          key         key with which the specified value is to be associated.
                  * @param          value         value to be associated with the specified key.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>put</code> operation is not supported by this map.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of the specified key or value is incompatible with this map.
                  * @throws         ArgumentError                          if the specified key or value is <code>null</code> and this map does not permit <code>null</code> keys or values.
                  * @return         the previous value associated with key, or <code>null</code> if there was no mapping for key. (A <code>null</code> return can also indicate that the map previously associated <code>null</code> with key, if the implementation supports <code>null</code> values.)
                  */
                 function put(key:*, value:*): *;
 
                 /**
                  * 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 <code>put(k, v)</code> on this map once for each mapping from key <code>k</code> to value <code>v</code> in the specified map.
                  * 
                  * @param          map         mappings to be stored in this map.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>putAll</code> operation is not supported by this map.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of a key or value in the specified map is incompatible with this map.
                  * @throws         ArgumentError                          if the specified map is <code>null</code>, or if this map does not permit <code>null</code> keys or values, and the specified map contains <code>null</code> keys or values.
                  */
                 function putAll(map:IMap): void;
 
                 /**
                  * Retrieves each property of the specified object, calling <code>put</code> on this map once for each property (optional operation).
                  * 
                  * @param          o the object to retrieve the properties.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>putAllByObject</code> operation is not supported by this map.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of a key or value in the specified object is incompatible with this map.
                  * @throws         ArgumentError                          if the specified object is <code>null</code>, or if this map does not permit <code>null</code> keys or values, and the specified object contains <code>null</code> keys or values.
                  */
                 function putAllByObject(o:Object): void;
 
                 /**
                  * Associates the specified <code>entry.value</code> with the specified <code>entry.key</code> in this map (optional operation).
                  * If the map previously contained a mapping for the <code>entry.key</code>, the old value is replaced by the specified <code>entry.value</code>. (A map <code>m</code> is said to contain a mapping for a key <code>k</code> if and only if <code>m.containsKey(k)</code> would return <code>true</code>.) 
                  * <p>The effect of this call is equivalent to that of calling <code>put(entry.key, entry.value)</code> on this map.</p>
                  * 
                  * @param          entry         entry to put in this map.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>putEntry</code> operation is not supported by this map.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of the specified <code>entry.key</code> or <code>entry.value</code> is incompatible with this map.
                  * @throws         ArgumentError                          if the specified entry is <code>null</code>, or if the specified <code>entry.key</code> or <code>entry.value</code> is <code>null</code> and this map does not permit <code>null</code> keys or values.
                  * @return         the previous value associated with <code>entry.key</code>, or <code>null</code> if there was no mapping for <code>entry.key</code>. (A <code>null</code> return can also indicate that the map previously associated <code>null</code> with <code>entry.key</code>, if the implementation supports <code>null</code> values.)
                  */
                 function putEntry(entry:IMapEntry): *;
 
                 /**
                  * Removes the mapping for a key from this map if it is present (optional operation).
                  * <p>Returns the value to which this map previously associated the key, or <code>null</code> if the map contained no mapping for the key.
                  * If this map permits <code>null</code> values, then a return value of <code>null</code> does not <em>necessarily</em> indicate that the map contained no mapping for the key. It's possible that the map explicitly mapped the key to <code>null</code>.</p>
                  * <p>The map will not contain a mapping for the specified key once the call returns.</p>
                  * 
                  * @param          key         the key whose mapping is to be removed from the map.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>remove</code> operation is not supported by this map.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of the specified key is incompatible with this map (optional).
                  * @throws         ArgumentError                          if the specified key is <code>null</code> and this map does not permit <code>null</code> keys (optional).
                  * @return         the previous value associated with key, or <code>null</code> if there was no mapping for <code>key</code>.
                  */
                 function remove(key:*): *;
 
                 /**
                  * 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.
                  * <p>The effect of this call is equivalent to that of calling <code>remove</code> on this map once for each element in the speficied collection.</p>
                  * <p>The map will not contain mappings for the elements in the specified collection once the call returns.</p>
                  * 
                  * @param          keys         the collection whose elements are interpreted as keys to be removed from the map.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>removeAll</code> operation is not supported by this map.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of an element in the specified collection is incompatible with this map (optional).
                  * @throws         ArgumentError                          if the specified collection is <code>null</code>, or if this map does not permit <code>null</code> keys, and the specified collections contains <code>null</code> elements (optional).
                  * @return         <code>true</code> if this map changed as a result of the call.
                  */
                 function removeAll(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.
                  * 
                  * @param          keys         the collection whose elements are interpreted as keys to be retained in the map.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>retainAll</code> operation is not supported by this map.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the types of one or more keys in this map are incompatible with the specified collection (optional).
                  * @throws         ArgumentError                           if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> keys (optional), or if the specified collection is <code>null</code>.
                  * @return         <code>true</code> if this map changed as a result of the call.
                  */
                 function retainAll(keys:ICollection): Boolean;
 
                 /**
                  * Returns the number of key-value mappings in this map. 
                  * 
                  * @return         the number of key-value mappings in this map.
                   */
                 function size(): int;
         }
 
 }

1		/*
2		* Licensed under the MIT License
3		*
4		* Copyright 2010 (c) Flávio Silva, http://flsilva.com
5		*
6		* Permission is hereby granted, free of charge, to any person
7		* obtaining a copy of this software and associated documentation
8		* files (the "Software"), to deal in the Software without
9		* restriction, including without limitation the rights to use,
10		* copy, modify, merge, publish, distribute, sublicense, and/or sell
11		* copies of the Software, and to permit persons to whom the
12		* Software is furnished to do so, subject to the following
13		* conditions:
14		*
15		* The above copyright notice and this permission notice shall be
16		* included in all copies or substantial portions of the Software.
17		*
18		* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19		* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
20		* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21		* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
22		* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23		* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24		* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25		* OTHER DEALINGS IN THE SOFTWARE.
26		*
27		* http://www.opensource.org/licenses/mit-license.php
28		*/
29
30	0	package org.as3collections
31		{
32		import org.as3coreaddendum.system.ICloneable;
33		import org.as3coreaddendum.system.IEquatable;
34
35		/**
36		* An object that maps keys to values.
37		* A map cannot contain duplicate keys, each key can map to at most one value.
38		* <p>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 (<code>IMapEntry</code>).
39		* Some map implementations, like the <code>ArrayListMap</code> class, make specific guarantees as to their order; others, like the <code>HashMap</code> class, do not.</p>
40		* <p>These views, plus <code>IMap.iterator()</code>, enable various forms of iteration over the keys and values of the map.
41		* To iterate over the keys/values the user can use <code>IMap.iterator()</code> or <code>IMap.entryList().iterator()</code>.
42		* To iterate over the keys the user can use <code>IMap.getKeys().iterator()</code>.
43		* To iterate over the values the user can use <code>IMap.getValues().iterator()</code>.</p>
44		* <p>Some map implementations have restrictions on the keys and values they may contain.
45		* For example, some implementations prohibit <code>null</code> keys and values, and some have restrictions on the types of their keys or values.</p>
46		* <p>The methods that modify the map are specified to throw <code>org.as3coreaddendum.errors.UnsupportedOperationError</code> if the map does not support the operation.
47		* These methods are documented as "optional operation".</p>
48		* <p>This documentation is partially based in the <em>Java Collections Framework</em> JavaDoc documentation.
49		* For further information see <a href="http://download.oracle.com/javase/6/docs/technotes/guides/collections/index.html" target="_blank">Java Collections Framework</a></p>
50		*
51		* @see org.as3collections.AbstractHashMap AbstractHashMap
52		* @see org.as3collections.AbstractListMap AbstractListMap
53		* @see org.as3collections.IMapEntry IMapEntry
54		* @see org.as3collections.IListMap IListMap
55		* @author Flávio Silva
56		*/
57		public interface IMap extends IIterable, ICloneable, IEquatable
58		{
59		/**
60		* Indicates whether all keys in this map implements <code>org.as3coreaddendum.system.IEquatable</code> interface.
61		*/
62		function get allKeysEquatable(): Boolean;
63
64		/**
65		* Indicates whether all values in this map implements <code>org.as3coreaddendum.system.IEquatable</code> interface.
66		*/
67		function get allValuesEquatable(): Boolean;
68
69		/**
70		* Removes all of the mappings from this map (optional operation).
71		* The map will be empty after this call returns.
72		*
73		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>clear</code> operation is not supported by this map.
74		*/
75		function clear(): void;
76
77		/**
78		* Returns <code>true</code> if this map contains a mapping for the specified key.
79		*
80		* @param key key whose presence in this map is to be tested.
81		* @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified key is incompatible with this map (optional).
82		* @throws ArgumentError if the specified key is <code>null</code> and this map does not permit <code>null</code> keys (optional).
83		* @return <code>true</code> if this map contains a mapping for the specified key.
84		*/
85		function containsKey(key:*): Boolean;
86
87		/**
88		* Returns <code>true</code> if this map maps one or more keys to the specified value.
89		*
90		* @param value value whose presence in this map is to be tested.
91		* @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified value is incompatible with this map (optional).
92		* @throws ArgumentError if the specified value is <code>null</code> and this map does not permit <code>null</code> values (optional).
93		* @return <code>true</code> if this map maps one or more keys to the specified value.
94		*/
95		function containsValue(value:*): Boolean;
96
97		/**
98		* Returns an <code>ICollection</code> object that is a view of the mappings contained in this map.
99		* The type of the objects within the map is <code>IMapEntry</code>
100		* <p>Modifications in the <code>ICollection</code> object does not affect this map.</p>
101		*
102		* @return an <code>ICollection</code> object that is a view of the mappings contained in this map.
103		* @see org.as3collections.IMapEntry IMapEntry
104		* @see org.as3collections.ICollection ICollection
105		*/
106		function entryCollection(): ICollection;
107
108		/**
109		* Returns an <code>ICollection</code> object that is a view of the keys contained in this map.
110		* <p>Modifications in the <code>ICollection</code> object doesn't affect this map.</p>
111		*
112		* @return an <code>ICollection</code> object that is a view of the keys contained in this map.
113		*/
114		function getKeys(): ICollection;
115
116		/**
117		* Returns the value to which the specified key is mapped, or <code>null</code> if this map contains no mapping for the key.
118		* <p>If this map permits <code>null</code> values, then a return value of <code>null</code> does not <em>necessarily</em> indicate that the map contains no mapping for the key.
119		* It's possible that the map explicitly maps the key to <code>null</code>.
120		* The <code>containsKey</code> method may be used to distinguish these two cases.</p>
121		*
122		* @param key the key whose associated value is to be returned.
123		* @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified key is incompatible with this map (optional).
124		* @throws ArgumentError if the specified key is <code>null</code> and this map does not permit <code>null</code> keys (optional).
125		* @return the value to which the specified key is mapped, or <code>null</code> if this map contains no mapping for the key.
126		*/
127		function getValue(key:): ;
128
129		/**
130		* Returns an <code>ICollection</code> object that is a view of the values contained in this map.
131		* <p>Modifications in the <code>ICollection</code> object does not affect this map.</p>
132		*
133		* @return an <code>ICollection</code> object that is a view of the values contained in this map.
134		*/
135		function getValues(): ICollection;
136
137		/**
138		* Returns <code>true</code> if this map contains no key-value mappings.
139		*
140		* @return <code>true</code> if this map contains no key-value mappings.
141		*/
142		function isEmpty(): Boolean;
143
144		/**
145		* Associates the specified value with the specified key in this map (optional operation).
146		* If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map <code>m</code> is said to contain a mapping for a key <code>k</code> if and only if <code>m.containsKey(k)</code> would return <code>true</code>.)
147		*
148		* @param key key with which the specified value is to be associated.
149		* @param value value to be associated with the specified key.
150		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>put</code> operation is not supported by this map.
151		* @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified key or value is incompatible with this map.
152		* @throws ArgumentError if the specified key or value is <code>null</code> and this map does not permit <code>null</code> keys or values.
153		* @return the previous value associated with key, or <code>null</code> if there was no mapping for key. (A <code>null</code> return can also indicate that the map previously associated <code>null</code> with key, if the implementation supports <code>null</code> values.)
154		*/
155		function put(key:, value:): *;
156
157		/**
158		* Copies all of the mappings from the specified map to this map (optional operation).
159		* The effect of this call is equivalent to that of calling <code>put(k, v)</code> on this map once for each mapping from key <code>k</code> to value <code>v</code> in the specified map.
160		*
161		* @param map mappings to be stored in this map.
162		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>putAll</code> operation is not supported by this map.
163		* @throws org.as3coreaddendum.errors.ClassCastError if the type of a key or value in the specified map is incompatible with this map.
164		* @throws ArgumentError if the specified map is <code>null</code>, or if this map does not permit <code>null</code> keys or values, and the specified map contains <code>null</code> keys or values.
165		*/
166		function putAll(map:IMap): void;
167
168		/**
169		* Retrieves each property of the specified object, calling <code>put</code> on this map once for each property (optional operation).
170		*
171		* @param o the object to retrieve the properties.
172		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>putAllByObject</code> operation is not supported by this map.
173		* @throws org.as3coreaddendum.errors.ClassCastError if the type of a key or value in the specified object is incompatible with this map.
174		* @throws ArgumentError if the specified object is <code>null</code>, or if this map does not permit <code>null</code> keys or values, and the specified object contains <code>null</code> keys or values.
175		*/
176		function putAllByObject(o:Object): void;
177
178		/**
179		* Associates the specified <code>entry.value</code> with the specified <code>entry.key</code> in this map (optional operation).
180		* If the map previously contained a mapping for the <code>entry.key</code>, the old value is replaced by the specified <code>entry.value</code>. (A map <code>m</code> is said to contain a mapping for a key <code>k</code> if and only if <code>m.containsKey(k)</code> would return <code>true</code>.)
181		* <p>The effect of this call is equivalent to that of calling <code>put(entry.key, entry.value)</code> on this map.</p>
182		*
183		* @param entry entry to put in this map.
184		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>putEntry</code> operation is not supported by this map.
185		* @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified <code>entry.key</code> or <code>entry.value</code> is incompatible with this map.
186		* @throws ArgumentError if the specified entry is <code>null</code>, or if the specified <code>entry.key</code> or <code>entry.value</code> is <code>null</code> and this map does not permit <code>null</code> keys or values.
187		* @return the previous value associated with <code>entry.key</code>, or <code>null</code> if there was no mapping for <code>entry.key</code>. (A <code>null</code> return can also indicate that the map previously associated <code>null</code> with <code>entry.key</code>, if the implementation supports <code>null</code> values.)
188		*/
189		function putEntry(entry:IMapEntry): *;
190
191		/**
192		* Removes the mapping for a key from this map if it is present (optional operation).
193		* <p>Returns the value to which this map previously associated the key, or <code>null</code> if the map contained no mapping for the key.
194		* If this map permits <code>null</code> values, then a return value of <code>null</code> does not <em>necessarily</em> indicate that the map contained no mapping for the key. It's possible that the map explicitly mapped the key to <code>null</code>.</p>
195		* <p>The map will not contain a mapping for the specified key once the call returns.</p>
196		*
197		* @param key the key whose mapping is to be removed from the map.
198		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>remove</code> operation is not supported by this map.
199		* @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified key is incompatible with this map (optional).
200		* @throws ArgumentError if the specified key is <code>null</code> and this map does not permit <code>null</code> keys (optional).
201		* @return the previous value associated with key, or <code>null</code> if there was no mapping for <code>key</code>.
202		*/
203		function remove(key:): ;
204
205		/**
206		* Removes the mapping for a key from this map (if it is present) for each element in the specified collection (optional operation).
207		* The elements in the specified collection are interpreted as keys.
208		* <p>The effect of this call is equivalent to that of calling <code>remove</code> on this map once for each element in the speficied collection.</p>
209		* <p>The map will not contain mappings for the elements in the specified collection once the call returns.</p>
210		*
211		* @param keys the collection whose elements are interpreted as keys to be removed from the map.
212		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>removeAll</code> operation is not supported by this map.
213		* @throws org.as3coreaddendum.errors.ClassCastError if the type of an element in the specified collection is incompatible with this map (optional).
214		* @throws ArgumentError if the specified collection is <code>null</code>, or if this map does not permit <code>null</code> keys, and the specified collections contains <code>null</code> elements (optional).
215		* @return <code>true</code> if this map changed as a result of the call.
216		*/
217		function removeAll(keys:ICollection): Boolean;
218
219		/**
220		* Retains only the mappings in this map that the keys are contained (as elements) in the specified collection (optional operation).
221		* In other words, removes from this map all of its mappings whose keys are not contained (as elements) in the specified collection.
222		* The elements in the specified collection are interpreted as keys.
223		*
224		* @param keys the collection whose elements are interpreted as keys to be retained in the map.
225		* @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>retainAll</code> operation is not supported by this map.
226		* @throws org.as3coreaddendum.errors.ClassCastError if the types of one or more keys in this map are incompatible with the specified collection (optional).
227		* @throws ArgumentError if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> keys (optional), or if the specified collection is <code>null</code>.
228		* @return <code>true</code> if this map changed as a result of the call.
229		*/
230		function retainAll(keys:ICollection): Boolean;
231
232		/**
233		* Returns the number of key-value mappings in this map.
234		*
235		* @return the number of key-value mappings in this map.
236		*/
237		function size(): int;
238		}
239
240		}