► caplin.core.MapUtility()

This is a static class that never needs to be instantiated.

► <static> Object addArrayToMap(Object mMap, Array pArray)

Add the items within the given array to the map, using each item as a key pointing to the boolean value true. This will overwrite the value for a key that is already defined within the specified map.

As an example, the array ["foo", "bar"] would be converted to the map {foo:true, bar:true}.

This method is useful in that it allows a number of arrays to be condensed into a list of the unique values within this set of arrays. Once all the arrays have been added, then the #keysToArray method may be used to convert this list of unique entries back to an array.

Returns

{Object} the passed map.

See

#removeArrayFromMap

► <static> Object clone(Object mSource)

Creates a shallow clone of the supplied map. Map references are copied one level deep.

Returns

A shallow clone of the map.

► <static> Boolean hasAllKeys(Object mSource, Object mMap)

Returns true if the source map contains all the keys of the given map.

Returns

{Boolean}

► <static> boolean isEmpty(Object mMap)

Returns true if the given map is empty (has no enumerable properties), and false otherwise.

► <static> Object mergeMaps(Array pMapsToMerge, boolean bOverwriteDuplicates, Boolean bDuplicatesThrowsExceptions, Boolean bDeepCopy)

Merges all of the maps specified in the array into a new map.

The default behaviour of this method is to throw an exception if two maps contain the same key, however these duplicates can be ignored by setting the optional bOverwriteDuplicates argument to true. In this case the value of the key within the merged map will be that of the last map to contain the key. For example, merging [ { a: "1" }, { a: "2" } ] would result in the map { a: "2" }.

Throws

caplin.core.Error

if one or more of the contents of the maps to merge array is not a Map, or if any duplicate keys are found and the bOverwriteDuplicates argument is false.

Returns

A new map containing the merged key/value pairs from each of the specified maps.

► <static> Object removeArrayFromMap(Object mMap, Array pArray)

Remove all entries within the specified map, whose keys are contained within the given array. Keys included in the array that do not exist within the map will be ignored.

Returns

{Object} A map containing all name/value pairs that have been removed from the specified map.

See

#addArrayToMap

► <static> number size(Object mMap)

Returns the number of enumerable items within the given map.

If you find yourself using this method you should consider whether a map is the correct data structure.

Returns

{number} The number of items within the map.

► <static> String toString(Object mMap)

Returns a string representation of the map in the form:

map#1{ a: 1, b: 2, c: 3, ... }

The values contained within the map will be returned as per the value of their toString() method. Another map will be displayed as [object Object], as will any object that does not explicitly implement or inherit a toString() method.

This method can be invoked multiple times from within the same callstack, such that if an object contained within the map implements a toString() method that calls it, there can be no infinite recursion. For example, if the object contained a reference to another map, the output would be of the form:

map#1{ obj: myObject<map#2{ x: 24, y: 25, z: 26 }> }

Whilst if the object contains a circular reference back to the map, the output will be of the form:

map#1{ obj: myObject<map#1<see-earlier-definition>> }

Returns

{String} A string representation of the specified map.

► <static> Array valuesToArray(Object mMap)

Returns an array containing the values obtained by iterating the given map object.

Returns

{Array} an array of all the enumerable values in the map.