Convert

Convert

Utility class that provides methods to convert and extract data from Arrays and Maps.

Members

(static, constant) FORCE_ARRAY :bool

Source:

Forces the result of an arrayToMap call so every matching key always points to an array.

Type:
  • bool

Methods

(static) arrayToMap(arr, prop, forceArrayopt) → {Object}

Source:

Given an array of objects and the name of a property, returns a map whose keys are the values of the given property or properties. Each key points to the matching object element, unless the property value matches more than one element. In this case its key will map to an array of all the matching elements.

If forceArray is true then the key will always point to an array, even if only one element matches.

The original array remains unchanged.

Examples
const test = [
   {"foo": 100, "bar": "One", "baz": null},
   {"foo": 200, "bar": "Two", "baz": "baz2"},
   {"foo": 300, "bar": "Three", "baz": null},
   {"foo": 400, "bar": "Four", "baz": "baz4"},
   {"foo": 500, "bar": "Five", "baz": "baz5"}
];
const m1 = Convert.arrayToMap(test, "bar");
// m1 is:
// {
//    Five: {foo: 500, bar: "Five", baz: "baz5"},
//    Four: {foo: 400, bar: "Four", baz: "baz4"},
//    One: {foo: 100, bar: "One", baz: null},
//    Three: {foo: 300, bar: "Three", baz: null},
//    Two: {foo: 200, bar: "Two", baz: "baz2"}
// }
const m2 = Convert.arrayToMap(test, "baz");
// m2 is:
// {
//    baz2: {foo: 200, bar: "Two", baz: "baz2"},
//    baz4: {foo: 400, bar: "Four", baz: "baz4"},
//    baz5: {foo: 500, bar: "Five", baz: "baz5"},
//    null: [
//       {foo: 100, bar: "One", baz: null}
//       {foo: 300, bar: "Three", baz: null}
//    ]
// }
const m3 = Convert.arrayToMap(test, "baz", Convert.FORCE_ARRAY);
// m3 is:
// {
//    baz2: [{foo: 200, bar: "Two", baz: "baz2"}],
//    baz4: [{foo: 400, bar: "Four", baz: "baz4"}],
//    baz5: [{foo: 500, bar: "Five", baz: "baz5"}],
//    null: [
//       {foo: 100, bar: "One", baz: null},
//       {foo: 300, bar: "Three", baz: null}
//    ]
// }
Parameters:
Name Type Attributes Default Description
arr array

Array to inspect
prop string

Property to extract.
forceArray bool <optional>
 false

When true the map values are always returned as arrays.
Returns:
Type
Object

(static) ArrayUnique() → {boolean}

Source:

ArrayUnique is a predicate function that can be used in the extractFromArray or extractFromArrayAsProportion methods to return only unique values.

Examples
const test = [
   {"foo": 100, "bar": "One"},
   {"foo": 200, "bar": "Two"},
   {"foo": 300, "bar": "One"},
   {"foo": 400, "bar": "Four"},
   {"foo": 500, "bar": "Two"}
];
const val1 = Convert.extractFromArray(test, "bar", Convert.ArrayUnique);
// val1 is:
// [ "One", "Two", "Four" ]
Returns:
Type
boolean

(static) extractFromArray(arr, props, predicateopt, transformopt, renameopt) → {Array}

Source:

Extracts one or more properties from an array of objects and returns them as an array. If only a single property is given the return value is an array of scalars, otherwise it's an array of objects containing the extracted properties.

Examples
const test = [
   {"foo": 100, "bar": "One", "baz": null},
   {"foo": 200, "bar": "Two", "baz": "baz2"},
   {"foo": 300, "bar": "Three", "baz": null},
   {"foo": 400, "bar": "Four", "baz": "baz4"},
   {"foo": 500, "bar": "Five", "baz": "baz5"}
];
const val1 = Convert.extractFromArray(test, "foo");
// val1 is:
// [ 100, 200, 300, 400, 500 ]
const val2 = Convert.extractFromArray(test, "foo", el => el.foo < 400);
// val2 is:
// [ 100, 200, 300 ]
const val3 = Convert.extractFromArray(test, "bar", el => el.foo < 400);
// val3 is:
// [ "One", "Two", "Three" ]
const val3 = Convert.extractFromArray(test, "bar", el => el.foo < 400, , val => `Value is ${val}`);
// val3 is:
// [ "Value is One", "Value is Two", "Value is Three" ]
const val4 = Convert.extractFromArray(test, ["foo", "bar"], el => el.foo < 400, , val => `Value is ${val}`);
// val4 is:
// [
//    {foo: "Value is 100", bar: "Value is One"},
//    {foo: "Value is 200", bar: "Value is Two"},
//    {foo: "Value is 300", bar: "Value is Three"}
// ]
Parameters:
Name Type Attributes Description
arr array

Array to process
props string | array

One or more properties to extract
predicate function <optional>

Filter method that is called with the following parameters: element (object), property_name (string) and results_so_far (array). It should return true if the property's value is to be included in the extract.
transform function <optional>

Method that will be applied to each returned property to transform the returned value. The method is called with the extracted value and its row. It should return the new property value.
rename function <optional>

Method that will be applied to each returned property to remap each property's name (for objects only). The method is called with the name of each property. It should return the new property name (or null to keep the existing name).
Returns:
Type
Array

(static) extractFromArrayAsProportion(arr, prop, predicateopt, transformopt) → {Array}

Source:

Extracts a single numeric property from an array of objects and converts them into an array of proportional values in the interval [0, 1]. If a predicate function is used the proportions are calculated based only on those values that pass the filter.

Examples
const test = [
   {"foo": 100, "bar": "One", "baz": null},
   {"foo": 200, "bar": "Two", "baz": "baz2"},
   {"foo": 300, "bar": "Three", "baz": null},
   {"foo": 400, "bar": "Four", "baz": "baz4"},
   {"foo": 500, "bar": "Five", "baz": "baz5"}
];
const val1 = Convert.extractFromArrayAsProportion(test, "foo");
// val1 is:
// [ 0.06666666666666667, 0.13333333333333333, 0.2, 0.26666666666666666, 0.3333333333333333 ]
// i.e. each value divided by the total (which is 1500)
// Convert a subset of the raw values to percentages
const val2 = Convert.extractFromArrayAsProportion(test, "foo", el => el.foo < 400, , val => val * 100);
// val2 is:
// [ 16.666666666666668, 33.333333333333336, 50 ]
// i.e. each value divided by the total (which is 600) multiplied by 100
Parameters:
Name Type Attributes Description
arr array

Array to process
prop string

Numeric property to extract
predicate function <optional>

Filter method that should true if the property is to be included in the extract
transform function <optional>

Method that will be applied to each proportion value
Returns:
Type
Array

(static) extractFromMap(map, props, predicateopt, transformopt) → {Array}

Source:

Extracts one or more properties from an map of objects and returns them as an object array.

Examples
const test = {
   obj1: { foo: 1, name: "Name 1"}",
   obj2: { foo: 2, name: "Name 2"}",
   obj3: { foo: 3, name: "Name 3"}",
   obj4: { foo: 4, name: "Name 4"}",
};
const r1 = Convert.extractFromMap(test, "name");
// r1 is ["Name 1", "Name 2", "Name 3", "Name 4"]
const r2 = Convert.extractFromMap(test, "name");
// r2 is ["obj1", "obj2", "obj3", "obj4"]
Parameters:
Name Type Attributes Description
map object

Map to process
props string | array

One or more properties to extract (the special value __key returns the map key)
predicate function <optional>

Filter method that returns true if the map entry is to be included
transform function <optional>

Method that will be applied to each returned property
Returns:

If props is a string then the returned array is an array of strings, else it's an array of objects.

Type
Array

(static) simpleArrayToMap(arr, val) → {Object}

Source:

Given an array of strings, returns a map whose keys are the values of the array, with each key pointing to the same given value. val can be a simple scaler, array, map etc.

Example
const test = ["foo", "bar", "baz"];
const m = Convert.simpleArrayToMap(test, {val: 1});
// m is:
// {
//  "foo": {val: 1},
//  "bar": {val: 1},
//  "baz": {val: 1}
// }
Parameters:
Name Type Description
arr array

Array to inspect
val *

Value to assign to every map element
Returns:
Type
Object

(static) toOrdinal(i) → {string}

Source:

Returns the ordinal suffix for the given numeric value.

Example
const ord1 = Convert.toOrdinal(1);
const ord2 = Convert.toOrdinal(2);
const ord3 = Convert.toOrdinal(12);
// ord1 is 1st
// ord2 is 2nd
// ord3 is 12th
Parameters:
Name Type Description
i number

Numer to be converted
Returns:

Ordinal

Type
string

(static) toProportion(arr, prop, newpropopt, transformopt)

Source:

Converts the given numeric property in an array of objects into an array of proportional values in the interval [0, 1]. The given array is modified in-place.

Examples
const test = [
   {"foo": 100, "bar": "One", "baz": null},
   {"foo": 200, "bar": "Two", "baz": "baz2"},
   {"foo": 300, "bar": "Three", "baz": null},
   {"foo": 400, "bar": "Four", "baz": "baz4"},
   {"foo": 500, "bar": "Five", "baz": "baz5"}
];
Convert.toProportion(test, "foo", "newfoo", v => v * 100);
// test is:
// [
//    {foo: 100, bar: "One", baz: null, newfoo: 6.666666666666667}
//    {foo: 200, bar: "Two", baz: "baz2", newfoo: 13.333333333333334}
//    {foo: 300, bar: "Three", baz: null, newfoo: 20}
//    {foo: 400, bar: "Four", baz: "baz4", newfoo: 26.666666666666668}
//    {foo: 500, bar: "Five", baz: "baz5", newfoo: 33.33333333333333}
// ]
// i.e. each value divided by the total (which is 1500) * 100
Parameters:
Name Type Attributes Default Description
arr array

Array to process
prop string

Original numeric property to extract
newprop string <optional>
 prop

Name of the new property to contain the proportional values. Defaults to the same as the original which means the original values will be overwritten by the proportions.
transform function <optional>

Method that will be applied to each proportion value