Last call for comments. Minor changes since previous drafts (and some
comments at the beginning to address changes that are known to come).
--lars
Title: The class "Map"
The class Map
NAME: "The class 'Map'"
FILE: spec/library/Map.html
CATEGORY: Pre-defined classes (E262-3 Chapter 15)
SOURCES:REFERENCES [1], [2], [3]
SPEC AUTHOR:Lars
DRAFT STATUS: LAST CALL - 2008-03-20
REVIEWED AGAINST ES3: N/A
REVIEWED AGAINST ERRATA:N/A
REVIEWED AGAINST BASE DOC: N/A
REVIEWED AGAINST PROPOSALS: YES
REVIEWED AGAINST CODE: YES
REVIEWED AGAINST TICKETS: YES
IMPLEMENTATION STATUS: ES4 RI
TEST CASE STATUS: Unknown
LAST CALL NOTES
* (Tickets #247, #289, and e-mail discussion.) The meta::invoke
method will change when we change the meaning of statics in
parameterized classes. Concrete types 'K' and 'V' will have to be
used in the invocation, and the returned 'Map' instance will be
from 'K' to 'V' instead of from 'EnumerableId' to '*', like this:
Map.string,int( { x: 10, y: 20 } )
* Should the WG adopt some proposal for default type parameters for
ES4 (not very likely) then the default values for 'K' and 'V' will
be 'EnumerableId' and '*'.
* The WG has agreed that for a parameterized type Cls and type T,
Cls.T is a subtype of Cls.*. That has yet to be
fully formalized, but it is used here.
CHANGES SINCE DRAFT 3 (2008-03-11)
* The type previously known as 'function' is now known as 'Callable'
* Cleaned out FIXME comments in the text.
CHANGES SINCE DRAFT 2 (2008-03-03)
* The prototype 'get' and 'put' methods also accept a 'notfound'
parameter.
* Presentation:
- section headers for intrinsic methods now use the syntax
'intrinsic::foo()' instead of just 'foo'.
- compatibility note ("new in 4th edition")
- added an explicit "extends Object" clause.
- the informative method 'allElements' was renamed as 'allItems'.
- corrected a typo
- common fields in the status block above
CHANGES SINCE DRAFT 1 (2008-02-29)
* The value returned by 'hashcode' is constrained to be a number and
is always explicitly converted to uint
* Map(x) returns x if x is a Map
* 'get' and 'put' have (V|undefined) return types
* 'get' and 'put' accept an optional value (defaulting to undefined)
which is returned if the association was not found in the map
* There is a new method 'clear' to clear the map
* The object returned from helper::iterate has been annotated with
an explicit type, fixing the next field.
REFERENCES
[1] http:wiki.ecmascript.org/doku.php?id=proposals:dictionary
[2] http:bugs.ecmascript.org/ticket/146
[3] http:bugs.ecmascript.org/ticket/203
The class Map is a parameterized, dynamic, non-final, direct
subclass of Object that provides a reliable, efficient, mutable,
and iterable map from keys to values. Keys and values may be of
arbitrary types.
COMPATIBILITY NOTE The class Map is new in the 4th Edition of this Standard.
A Map is realized as a hash table. When the Map is
constructed the caller may provide specialized functions that compare
keys and compute hash values for keys.
Synopsis
The class Map provides the following interface:
__ES4__ dynamic class Map.K,V> extends Object
{
public function Map(equals: Callable = (function(a,b) a === b),
hashcode: Callable = intrinsic::hashcode)
static meta function invoke(object: Object=null): Map.EnumerableId,*>
static public const length = 2;
intrinsic function size() : uint
intrinsic function get(key: K, notfound: (V|undefined)=undefined) : (V|undefined)
intrinsic function put(key: K, value: V, notfound: (V|undefined)=undefined) : (V|undefined)
intrinsic function has(key:K) : boolean
intrinsic function remove(key:K) : boolean
intrinsic function clear() : void
iterator function get(deep: boolean = false) : iterator::IteratorType.K>
iterator function getKeys(deep: boolean = false) : iterator::IteratorType.K>
iterator function getValues(deep: boolean = false) : iterator::IteratorType.V>
iterator function getItems(deep: boolean = false) : iterator::IteratorType.[K,V]>
private const equals : Callable =
private const hashcode : Callable =
private var population : uint =
}
The Map prototype object provides these direct properties:
size: function ()
get:function (key, notfound)
put:function (key, value, notfound)
has:function (key)
remove: function (key)
clear: function ()
Methods on the Map class object
newMap.K,V(equals=,hashcode=)
Description The Map constructor creates a new map for key type K
and value type V.
The optional equals argument is a function that compares two
keys and returns true if they are equal and false if they are
not.
