Maestro API Reference

Namespace: Calc

Calc

Provides a generic calculation helper API, as either an Angular or Node module.

Methods

Calc.commaList(string)

Converts a comma-separated string into an array. This method uses the trim function to remove whitespace from the beginning and end of each item.
Parameters:
Name Type Description
string string A comma-separated string.
Returns:
Returns an array of the comma-separated values.
Type
Array
Examples
Calc.commaList("apple,banana,pears");
// => ["apple", "banana", "pears"]
Calc.commaList(" apple , banana , pears ");
// => ["apple", "banana", "pears"]

Calc.date(date [, preferNonUs])

Converts a string into a `Date` object.
Parameters:
Name Type Argument Default Description
date string | Date The string to convert into a date object.
preferNonUs boolean <optional>
 false If `true`, non-US date formats will be preferred.
Returns:
Returns a `Date` object. If the provided date is not valid, an empty string is returned.
Type
Date | string
Examples

Converting a US date.

Calc.date("01-12-2019");
// => Sat Jan 12 2019 00:00:00

Converting a non-US date.

Calc.date("01-12-2019", true);
// => Sun Dec 01 2019 00:00:00

Calc.daysBetween(startDate, endDate)

Calculates the number of days between two dates.
Parameters:
Name Type Description
startDate string | Date A string or date object for start of the range.
endDate string | Date A string or date object for end of the range.
Returns:
Returns the number of days between the start and end dates.
Type
integer
Examples

Passing through strings.

Calc.daysBetween("2019-01-01", "2020-01-01");
// => 365

Passing through date objects.

var startDate = new Date("2019-01-01");
var endDate = new Date("2020-01-01");
Calc.daysBetween(startDate, endDate);
// => 365

Calc.delimitedSelection(text)

Converts a comma-separated string into a format suitable for a data-driven dropdown. This method allows you to define the values separately from the labels.
Parameters:
Name Type Description
text string A comma-separated string.
Returns:
Returns an array of objects that is suitable for a data-driven dropdown.
Type
Array
Examples
Calc.delimitedSelection("Apples, Bananas, Pears");
// => [
//     {
//         value: "Apples",
//         label: "Apples"
//     },
//     {
//         value: "Bananas",
//         label: "Bananas"
//     },
//     {
//         value: "Pears",
//         label: "Pears"
//     }
// ]

Use pipes to define separate values and labels.

Calc.delimitedSelection("apples|Apples, bananas|Bananas, pears|Pears");
// => [
//     {
//         value: "apples",
//         label: "Apples"
//     },
//     {
//         value: "bananas",
//         label: "Bananas"
//     },
//     {
//         value: "pears",
//         label: "Pears"
//     }
// ]

Calc.num(data)

Converts a value (such as a string) into a number.
Parameters:
Name Type Description
data string | number The value.
Returns:
Returns a number. If the supplied value can't be converted into a number, `NaN` is returned.
Type
number
Examples

Passing through a number.

Calc.num(123456);
// => 123456

Passing through a string of numbers.

Calc.num("123456");
// => 123456

Passing through a value that can't be converted into a number.

Calc.num("abcdef");
// => NaN

Calc.pipedSelection(text)

Converts a pipe-separated string into a format suitable for a data-driven dropdown. This method does not allow you to define the values separately from the labels. The values and labels will always be the same.
Parameters:
Name Type Description
text string A pipe-separated string.
Returns:
Returns an array of objects that is suitable for a data-driven dropdown.
Type
Array
Example
Calc.pipedSelection("Apples|Bananas|Pears");
// => [
//     {
//         value: "Apples",
//         label: "Apples"
//     },
//     {
//         value: "Bananas",
//         label: "Bananas"
//     },
//     {
//         value: "Pears",
//         label: "Pears"
//     }
// ]

Calc.rangeSelection(from, to)

Converts a numeric range into a format suitable for use with a data-driven dropdown.
Parameters:
Name Type Description
from integer A number to start the range.
to integer A number to end the range.
Returns:
Returns an array of objects that is suitable for a data-driven dropdown.
Type
Array
Example
Calc.rangeSelection(1, 3);
// => [
//     {
//         value: 1,
//         label: 1
//     },
//     {
//         value: 2,
//         label: 2
//     },
//     {
//         value: 3,
//         label: 3
//     }
// ]

Calc.total(array, field [, filter])

Calculates the sum of a property within an array of objects.
Parameters:
Name Type Argument Description
array Array An array of objects.
field string The name of the property to sum.
filter function <optional>
 A handler to control which objects are included or ignored. When this function returns `true`, the associated object will be included in the sum.
Returns:
Returns the sum of the specified property.
Examples

Without a filter.

Calc.total([
   {
       type: "credit card",
       balance: 4000
   },
   {
       type: "savings",
       balance: 3000
   },
   {
       type: "credit card",
       balance: 6000
   }
], "balance");
// => 13000

With a filter.

Calc.total([
   {
       type: "credit card",
       balance: 4000
   },
   {
       type: "savings",
       balance: 3000
   },
   {
       type: "credit card",
       balance: 6000
   }
], "balance", (arrayItem) => {
  if (arrayItem.type === "savings") {
      return true;
  } else {
      return false;
  }
});
// => 3000