Creatio development guide
PDF
This documentation is valid for Creatio version 7.10.0. We recommend using the newest version of Creatio documentation.

The DecimalUtils module

Glossary Item Box

Introduction

Certain errors cay occur when using JavaScript to perform floating point calculations. For example:

var a = 0.1 + 0.2; // a = 0.30000000000000004.
var b = 0.3 - 0.1; // b = 0.19999999999999998.

The DecimalUtils module was created to avoid these errors.

It is designed to perform highly accurate mathematical operations and generates pseudo-random numbers. The Terrasoft.DecimalUtils class is defined in this module. It contains all methods used for mathematical operations.

Сonstructor

The Terrasoft.DecimalUtils class instance is created using the Ext.create() method of the global Ext object.

Сonstructor format var decimalUtils = Ext.create("Terrasoft.DecimalUtils" [, config]);

The optional config parameter is the configuration object of the constructor. Properties of the config object are described in table 1.

Table 1. Properties of the DecimalUtils constructor configuration object

Name Type Description Default value
decimalPlaces (optional) Number The number of fractional part digits. Banker's rounding is applied to all calculations. 4
precision (optional) Number The number of significant figures for internal calculations. It includes both integer and fractional parts. For example, the number 123456789.123456789 contains 18 significant digits - 9 integer digits and 9 fractional digits. 24

Methods

The add() method

The add method calculates the sum of two numbers. Returning value type – Number.

Method format: decimalUtils.add(a, b);

Possible method parameters are listed in table 2.

Table 2. Add() method parameters

Name Type Description
a Number Addend
b Number Addend

Use case:

// Crearing an object.
var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
// The add() method returns 0.3.
decimalUtils.add(0.1, 0.2);        

The subtract() method

The subtract() method subtracts two numbers, i.e. calculates the difference. Returning value type – Number.

Method format: decimalUtils.subtract(a, b);

Possible method parameters are listed in table 3.

Table 3. Parameters of the subtract() method

Name Type Description
a Number Minuend
b Number Subtrahend

Use case:

// Crearing an object.
var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
// The subtract() method returns 0.2.
decimalUtils.subtract(0.3, 0.1);        

The multiply() method

The multiply() method calculates the multiplication of two numbers. Returning value type – Number.

Method format: decimalUtils.multiply(a, b);

Possible method parameters are listed in table 4.

Table 4. Parameters of the multiply() method

Name Type Description
a Number Multiplier
b Number Multiplier

Use case:

// Crearing an object.
var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
// The multiply() method returns 0.03.
decimalUtils.multiply(0.3, 0.1);        

The divide() method

The divide() method divides two numbers. Returning value type – Number.

Method format: decimalUtils.divide(a, b);

Possible method parameters are listed in table 5.

Table 5. Parameters of the divide() method

Name Type Description
a Number Dividend
b Number Divisor

Use case:

// Crearing an object.
var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
// The divide() method returns 3.
decimalUtils.divide(0.3, 0.1);        

The evaluate() method

The evaluate() method evaluates the result of the passed expression. Returning value type – Number.

Method format: decimalUtils.evaluate(expression);

Possible method parameters are listed in table 6.

Table 6. Parameters of the evaluate() method

Name Type Description
expression Object An object with mathematical operation properties (add, subtract, multiply, divide). Its values are arrays containing the Number value types or objects with subexpressions. It has a recursive structure.

Use case:

// Crearing an object.
var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
// A configuration object is passed as an argument.
decimalUtils.evaluate({
    // Calculating the sum. The summand values are passed in the array.
    add: [ // 1 + 7 = 8.
        // The first summand is a nested expression.
        {
            // Calculating the subtract. The values are passed in the array.
            subtract: [ // 4 - 3 = 1.
                // The minuend is a nested expression. It contains the multiplication operation.
               { multiply: [2, 2] }, // 2 * 2 = 4.
               3
            ]
        },
       // The second summand is a nested expression.
       {
           // Calculating the subtract. The values are passed in the array.
           subtract: [ // 5 - (-2) = 7.
                // The minuend is a nested expression. It contains the multiplication operation.
              { divide: [10, 2] }, // 10 ÷ 2 = 5.
              -2
           ]
       }
    ]
});// Returns 8.

Note

An array of operation arguments can contain an arbitrary number of elements. The operation is applied to the elements from left to right.

An example of using an addition operation with four arguments:

var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
decimalUtils.evaluate({
  add: [1, 2, 3, 4]
});

Calculation sequence:

1 + 2 = 3; 
3 + 3 = 6;
6 + 4 = 10;

An example of using an addition operation with four arguments:

var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
decimalUtils.evaluate({
  subtract: [10, 5, 3, 1]
});

Calculation sequence:

10 - 5 = 5; 
5 - 3 = 2;
2 - 1 = 1;

The toDecimalPlaces() method

The toDecimalPlaces() method rounds the number with the specified precision. This precision is specified by the decimalPlaces property of the configuration object passed to the constructor (see example below). Banker's rounding is applied to these calculations. Returning value type – Number.

Method format: decimalUtils.toDecimalPlaces(number);

Possible metric parameters are listed in table 7.

Table 7. Parameters of the toDecimalPlaces() method

Name Type Description
number Number The number to be rounded.

Use case:

var decimalUtils =  Ext.create("Terrasoft.DecimalUtils", {
    decimalPlaces: 1
});
decimalUtils.toDecimalPlaces(1.15);        // Returns 1.2

The roundValue() method

The roundValue() method rounds the number with the precision which is passed in the configuration object. If the precision has not been passed, the method rounds uses the precision of the decimalPlaces specified in the constructor configuration object. Banker's rounding is applied to these calculations. Returning value type – Number.

Method format: decimalUtils.roundValue(number [, config]);

Possible method parameters are listed in table 8.

Table 8. Parameters of the roundValue() method

Name Type Description
number Number The number to be rounded.
config (optional) Object An object with additional parameters.
config.decimalPlaces (optional) Number The number of fractional part digits.

Use case:

var decimalUtils =  Ext.create("Terrasoft.DecimalUtils", {
    decimalPlaces: 1
});
decimalUtils.roundValue(1.123456, {decimalPlaces: 4});// Returns 1.1235.
decimalUtils.roundValue(1.123456);// Returns 1.1.

The random() method

The random() method generates a pseudo-random number from 0 to 1 (not including 0 and 1) with the number of decimal places equal to decimalPlaces. Returning value type – Number.

Method format: var randomValue = decimalUtils.random();

Use case

var decimalUtils = Ext.create("Terrasoft.DecimalUtils");
// Returns a random number, e.g. 0.35.
var randomValue = decimalUtils.random();

© bpm'online 2002-2017.

Did you find this information useful?

How can we improve it?