Class Map

An unordered iterable collection of key/value pairs that cannot contain two instances of the same key. It optionally enforces the type of the key and the type of the associated value.

To create a Map: 

  var map = new go.Map("string", "number");
  map.add("one", 1);
  map.add("two", 2);
  map.add("three", 3);
  // now map.count === 3
  // and map.getValue("two") === 2
  // and map.contains("zero") === false

You can iterate over the key/value pairs in a Map: 

  var it = aMap.iterator;
  while (it.next()) {
    window.console.log(it.key + ": " + it.value);
  }
Or: 
  aMap.each(function(kvp) {
    window.console.log(kvp.key + ": " + kvp.value);
  });
But note that there is no guaranteed ordering amongst the key/value pairs.

Call toKeySet to get a read-only Set that holds all of the keys of a Map. Iterating over that Set will produce values that are the keys in the Map.

Although not precisely implementing the features and semantics of the EcmaScript 6 Map class, this GoJS Map class has synonyms for the following methods and property:

Constructor Summary Details

Name Description
Map(keytype, valtype)

The two optional arguments to the constructor describe the types of keys and the types of values that this Map may hold.More... If the argument is null, it does not check the type. If the argument is a string, it must be one of: 'number' or 'string' for the key type, or 'number', 'string', 'boolean', or 'function' for the value type. Otherwise the argument must be a class function/constructor, such as GraphObject.

For example, the expression: 

  new go.Map("string", go.Point)
produces a Map that has keys that must be strings and whose associated values must be Points.
Parameters:
{Function|string|null=} keytype
Optional class type (constructor) or a string, for the key describing the primitive key type.
{Function|string|null=} valtype
Optional class type (constructor) or a string, for the value describing the primitive value type.

Properties Summary Details

Name, Value Type Description
count
{number}

This read-only property is the number of associations in the Map.

iterator
{MapIterator.}

Gets an object that you can use for iterating over the key-value pairs of a Map.More... Typical usage: 

  var it = aMap.iterator;
  while (it.next()) {
    window.console.log("the key: " + it.key + " has value: " + it.value);
  }
iteratorKeys
{Iterator.} 1.4

Gets an object that you can use for iterating over the keys of a Map.More... Typical usage: 

  var it = aMap.iteratorKeys;
  while (it.next()) {
    window.console.log("key: " + it.value);
  }
iteratorValues
{Iterator.} 1.4

Gets an object that you can use for iterating over the values of a Map.More... Typical usage: 

  var it = aMap.iteratorValues;
  while (it.next()) {
    window.console.log("value: " + it.value);
  }

Method Summary Details

Name, Return Type Description
add(key, val)
{boolean}

Adds a key-value association to the Map, or replaces the value associated with the key if the key was already present in the map.More...

Be careful not to call this method while iterating over the collection.

Parameters:
{K} key
The key or index for storing the value in the Map.
{V} val
The value to add to the Map, associated with the key.
Returns:
{boolean} true if the key was not already present in the Map; false if it was.
addAll(coll)
{Map.}

Adds all of the key-value pairs of another Map to this Map.More... If a key is already present in this Map, its value is replaced with the corresponding value from the given map.

Be careful not to call this method while iterating over the collection.

Parameters:
{Iterable.>|Array.<*>} coll
the collection of keys/values to add, or an Array of { key: ..., value: ... } objects.
Returns:
{Map.} this map.
all(pred)
{boolean} 1.4

This is true if all invocations of the given predicate on items in the collection are true.More...

Call the given predicate on each key/value pair in the collection. As soon as a call returns false, this returns false. Otherwise this returns true. For an empty collection this returns true.

Parameters:
{function(KeyValuePair.):boolean} pred
The argument to the predicate will be an object with both "key" and "value" properties. This function must not have any side-effects.
Returns:
{boolean} True if all predicate calls are true; false otherwise.
any(pred)
{boolean} 1.4

This is true if any invocation of the given predicate on items in the collection is true.More...

Call the given predicate on each key/value pair in the collection. As soon as a call returns true, this returns true. Otherwise this returns false. For an empty collection this returns false.

Parameters:
{function(KeyValuePair.):boolean} pred
The argument to the predicate will be an object with both "key" and "value" properties. This function must not have any side-effects.
Returns:
{boolean} True if any predicate call is true; false otherwise.
clear()

Clears the Map, removing all key-value associations.More... This sets the count to zero.

Be careful not to call this method while iterating over the collection.
contains(key)
{boolean}

Returns whether the given key is in this Map.More...

Parameters:
{K} key
The key to look up in the Map.
Returns:
{boolean} Whether or not the key is contained within the Map.
copy()
{Map.}

Makes a shallow copy of this Map.More... The keys and their values are not copied, so if they are objects they may continue to be shared with the original Map.

Returns:
{Map.} The new Map.
delete(key)
{boolean}

Removes a key (if found) from the Map.More...

Be careful not to call this method while iterating over the collection.

Parameters:
{K} key
The key to insert.
Returns:
{boolean} true if the key was found and removed, false otherwise.
each(func)
{Map.} 1.4

Call the given function on each key/value pair in the collection.More...

Parameters:
{function(KeyValuePair.)} func
The argument to the function will be an object with both "key" and "value" properties. This function must not modify the collection.
Returns:
{Map.} this map itself
first()
{KeyValuePair.} 1.4

Returns the first key/value pair in the collection, or null if there is none.

Returns:
{KeyValuePair.} This returns null if there are no items in the collection.
get(key)
{V|null}

Returns the value associated with a key.More...

Parameters:
{K} key
The key to look up in the Map.
Returns:
{V|null} The value associated with the given key, or null if not present in the Map.
getValue(key)
{V|null}

Returns the value associated with a key.More...

Parameters:
{K} key
The key to look up in the Map.
Returns:
{V|null} The value associated with the given key, or null if not present in the Map.
has(key)
{boolean}

Returns whether the given key is in this Map.More...

Parameters:
{K} key
The key to look up in the Map.
Returns:
{boolean} Whether or not the key is contained within the Map.
remove(key)
{boolean}

Removes a key (if found) from the Map.More...

Be careful not to call this method while iterating over the collection.

Parameters:
{K} key
The key to insert.
Returns:
{boolean} true if the key was found and removed, false otherwise.
set(key, val)
{boolean}

Adds a key-value association to the Map, or replaces the value associated with the key if the key was already present in the map.More...

Be careful not to call this method while iterating over the collection.

Parameters:
{K} key
The key or index for storing the value in the Map.
{V} val
The value to add to the Map, associated with the key.
Returns:
{boolean} true if the key was not already present in the Map; false if it was.
toArray()
{Array.>}

Produces a JavaScript Array of key/value pair objects from the contents of this Map.

Returns:
{Array.>} A copy of the Map in Array form, each element being an Object with 'key' and 'value' properties.
toKeySet()
{MapKeySet.}

Produces a Set that provides a read-only view onto the keys of this Map.More... The collection of keys is not copied.

Returns:
{MapKeySet.}