Caplin Trader 5.1.0

Class: module:br-util/MapUtility

module:br-util/MapUtility()

Utility class providing common operations on maps.

In the context of this class, a Map is considered to be anything that is an instance of Object.

Constructor

new module:br-util/MapUtility()

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

Methods

(static) addArrayToMap(tgtMap, keys) → {Object}

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.

Parameters:
Name Type Description
tgtMap Object

The map to add the items to. May not be null or undefined
keys Array

The array that contains the map keys to add. May not be null or undefined.
See:
Returns:

the passed map.

Type
Object

(static) clone(srcMap) → {Object}

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

Parameters:
Name Type Description
srcMap Object

The map to clone.
Returns:

A shallow clone of the map.

Type
Object

(static) deepClone(src) → {Object}

Creates a deep clone of the supplied map/array. Copies the full depth of the data structure recursively.

Parameters:
Name Type Description
src Object

The object to clone.
Returns:

A deep clone of the object.

Type
Object

(static) hasAllKeys(tgtMap, srcMap) → {Boolean}

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

Parameters:
Name Type Description
tgtMap Object

The map you are checking
srcMap Object

The map you are using the check against
Returns:
Type
Boolean

(static) isEmpty(srcMap) → {boolean}

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

Parameters:
Name Type Description
srcMap Object

The map that may or may not be empty.
Returns:
Type
boolean

(static) mergeMaps(mergeMapArr, overwriteDuplicateKeys, throwOnDuplicateKey, isDeepCopy) → {Object}

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 overwriteDuplicateKeys 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' }.

Parameters:
Name Type Description
mergeMapArr Array

An array of all the maps to be merged.
overwriteDuplicateKeys boolean

(Optional) Flag that can be set to force this method to ignore duplicate keys and overwrite their values. If omitted this argument defaults to false.
throwOnDuplicateKey boolean

(Optional) Defaults to true. Indicates if an exception should be thrown if a duplicate value is found and the method is not to overwrite duplicates. This should be used if the original values should be preserved and not overwritten. If overwriteDuplicateKeys is set to true then this parameter is ignored.
isDeepCopy boolean

(Optional) Defaults to false, shallow copy. Identifies if map objects should have deep copy applied to them.
Throws:

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 overwriteDuplicateKeys argument is false.

Type
br/Errors
Returns:

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

Type
Object

(static) removeArrayFromMap(tgtMap, keys) → {Object}

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.

Parameters:
Name Type Description
tgtMap Object

The map to remove the items from.
keys Array

The array of keys to remove from the map.
See:
Returns:

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

Type
Object

(static) size(srcMap) → {number}

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.

Parameters:
Name Type Description
srcMap Object

The map the size is required for.
Returns:

The number of items within the map.

Type
number

(static) toString(srcMap) → {String}

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>> }

Warning: The output from this method will become unreliable if the toString() method of any of the values contained within the specified map throw an exception, however it is strongly advised that toString() methods should never throw exceptions.

Parameters:
Name Type Description
srcMap Object

The map to be converted to a String.
Returns:

A string representation of the specified map.

Type
String

(static) valuesToArray(srcMap) → {Array}

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

Parameters:
Name Type Description
srcMap Object

The map to iterate
Returns:

an array of all the enumerable values in the map.

Type
Array