The DecimalUtils module

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

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

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

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

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

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

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.

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

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

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();