Banana.SDecimal

The Banana.SDecimal is a static only class, with static method for high precision decimal calculation.

Static functions only

Banana.SDecimal is a class that provides static methods only. 

• Instances of of Banana.SDecimal are not allowed
  • The class has not a constructor for Banana.SDecimal.
  • Using "new Banana.SDecimal(0)" is an error.
  • Calling the method using a variable for example "value.add("123") is an error.
• Static functions take as arguments strings Numeric String (example "1234.56").
• Most functions return a Numeric String (example "1234.56").

Numeric String (Numeric Javascript String)

A Numeric String, a normal Javascript String that contains only numeric data. 

• Use Numeric String with the Banana.SDecimal methods to avoid the use of Javascript floating point arithmetic that is not suitable for accounting calculations due to the rounding differences. It is used instead of a Javascript Number.
• The Banana.SDecimal method uses Numeric String as arguments and return values.
• Numeric String are also referred as Internal Numeric Format (for example toInternalNumberFormat).

Characteristics of a Numeric String

• Numeric Strings use only numeric characters, for example '10.00' or '-10'.
• The point '.' is used as a decimal separator.
• Thousand separator are not allowed
• Negative numbers have a minus "-" sign preceding the number ("-1234.56").
• An empty string is considered equal to zero. The following value are the same
• Provide up to 34 digits of numeric precision.

Numeric String initialization examples 

If you need to instantiate a Numeric String Prior to using a variable simply assign an empty string.

var balance = ""; // empty Numeric String same as "0"
var balance = "0"; // same as ""
var balance = "1234";
var balance = "1234.00"; //same as "1234"
var balance = "1234.56"; // number with 2 decimals places
var balance = "1234.56789"; // number with 4 decimals places
var balance = "-1234"; //negative number
var balance = "-1234.00"; //negative number same as "-1234"
var balance = "1234.56789"; // negative number with 4 decimals places
// convert a string containing a numeric value in international format to a Numeric String format
var textAmount1 = Banana.Converter.toInternalNumberFormat("1'234,56", ","); 

Basic calculations

Use Banana.SDecimal methods for adding, dividing and subtracting Numeric Strings.

// sum '6.50+3.50' and use the default 2 decimal digits
var r = Banana.SDecimal.add('6.50', '3.50');   // return '10.00'

// divide '10/2' and use the default 2 decimal digits
var r = Banana.SDecimal.divide('10', '2');     // return '5.00'

// divide '10/2' and use 5 decimal digits
var r = Banana.SDecimal.divide('10', '2', {'decimals':5});     // return '5.00000'

Sum of two amounts 

Examples of Banana.SDecimal methods for adding two Numeric Strings.

// Example input text amounts
var textAmount1 = "1234.56";  // A valid number in string format
var textAmount2 = "-789.12";  // Another valid number in string format

// Perform the addition using Banana.SDecimal.add
var sum = Banana.SDecimal.add(textAmount1, textAmount2);

Convert two amounts from local number format and add

Prior to adding the amounts must be converted to a Numeric String.
Then you can use the Banana.SDecimal.add method.

// Example input text amounts
var textAmount1 = Banana.Converter.toInternalNumberFormat("1'234,56", ",");  // A valid number in local format
var textAmount2 = Banana.Converter.toInternalNumberFormat("-789,12", ",");   // Another valid number in local format

// Perform the addition using Banana.SDecimal.add
var sum = Banana.SDecimal.add(textAmount1, textAmount2);

Check if an amount is negative

if (Banana.SDecimal.sign('-789.12') < 0) {
  // amount is negative
}

Amounts values from Banana.document.table

Within the table, the value amounts and numeric columns are already in Numeric String format. 

• You can pass the retrieved values "row.value("Opening");" to the Banana.SDecimal methods.

The example that calculates the total of debits and credits, and the balance of the account in the row "0" of the table.

function calculateBalanceTotal() {
    let accountsTable = Banana.document.table("Accounts"); // Reads from table Accounts
    let row = accountsTable.row(0); // take the first row (index 0) or the table
    let opening = row.value("Opening");  // row.value("column_name_xml") already returns the text in Banana.SDecimal format
    let debit = row.value("Debit");  // row.value("column_name_xml") already returns the text in Banana.SDecimal format
    let credit = row.value("Credit");  // row.value("column_name_xml") already returns the text in Banana.SDecimal format
    let total = Banana.SDecimal.subtract(debit, credit);
    let balance = Banana.SDecimal.add(total, opening);
    return balance;
}

Sum the balance column

Within the table, the value of the columns number and amounts are already returned in Numeric String format.
You can pass the value directly to the Banana.SDecimal methods.

The example sums all balances of normal accounts.

function calculateBalanceTotal() {

    // Get the "Accounts" table
    let accountsTable = Banana.document.table("Accounts");
    let totalBalance = ""; // instatiate a numeric string

    for (let i = 0; i < accountsTable.rowCount; i++) {
        let row = accountsTable.row(i);
        let account = row.value("Account");
        
        // Only rows with normal accounts (not cost centers or segments)
        if (account && !account.startsWith(".") && !account.startsWith(",") && !account.startsWith(";") && !account.startsWith(":")) {
           let balance = row.value("Balance"); // get the balance value already in SDecimal format
           totalBalance = Banana.SDecimal.add(totalBalance, balance); // Add the balance amounts
        }
    }
    return totalBalance;
}

Rounding context

Functions can be passed a rounding context that specify the rounding properties:

• decimals is the number of decimal digits (default value is 2)
  • null returns the value unrounded.
  • '0' returns with no decimals.
  • '1' to '33' returns the value with the indicated number of decimals.
• mode is the rounding mode (default value is HALF_UP)
  • Banana.SDecimal.HALF_UP the amount is rounded to the nearest. The 0.5 are rounded up.
  • Banana.SDecimal.HALF_EVEN the amount is rounded to the nearest. The 0.5 are rounded up or down based on the preceding digit.

If the rounding context is omitted no rounding is done.

Rounding context of the accounting file

All Banana document files have a rounding context that can be retrieved with the property Banana.document.rounding (see Banana.document).

Examples:

// no context
var r = Banana.SDecimal.divide('10', '3'); // return '3.3333333333333333333333333'

// with context
var context = {'decimals' : 4, 'mode' : Banana.SDecimal.HALF_UP};
var r = Banana.SDecimal.divide('10', '3', context);        // return '3.3333'
var r = Banana.SDecimal.divide('10', '3', {'decimals':0}); // return '3'

// use the rounding property (accounting file 2 decimals)
var r = Banana.SDecimal.divide('10', '3', Banana.document.rounding); // return '3.33'

Methods

Here are the list of all available methods of the SDecimal class. 

abs(value1, [, roundingContext])

Static method.
Returns the absolute value of value1 removing its sign. The result is optionally rounded based on the specified roundingContext.

Parameters:

• value1 (string): The Numeric String whose absolute value is to be calculated.
• roundingContext (optional): A rounding specification (e.g., number of decimal places). If provided, the result will be rounded accordingly.

Returns:

• A Numeric String representing the absolute value of value1, optionally rounded.

var r = Banana.SDecimal.abs('-10') // return '10.00'

 add(value1, value2 [, roundingContext])

Static method.
Returns the sum of value1 and value2.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.add('6.50', '3.50'); // return '10.00'

compare(value1, value2)

Static method.
Parameters:

• value1 and value2 are Numeric String.
• return value is a Numeric String.

Returns an integer value:

• 1 if value1 > value2
• 0 if value1 = value2
• -1 if value1 < value2

Banana.SDecimal.compare('3.50', '2'); // return '1'
Banana.SDecimal.compare('3.00', '3'); // return '0'

divide(value1, value2 [, roundingContext])

Static method.
Returns value1 divided by value2.

Parameters:

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.divide('6', '3'); // return '2.00'

isZero(value)

Static method.
Returns a boolean

• true if value is zero
• false if value is not zero

var r = Banana.SDecimal.isZero('3.00'); // return 'false'

max(value1, value2 [, roundingContext])

Static method.
Returns the max between value1 and value2.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.max('6', '3'); // return '6.00'

min(value1, value2 [, roundingContext])

Static method.
Returns the min between value1 and value2.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.min('6', '3'); // return '3.00'

multiply(value1, value2 [, roundingContext])

Static method.
Returns value1 multiplied by value2.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.multiply('6', '3'); // return '18.00'

remainder(value1, value2 [, roundingContext])

Static method.
Divide value1 by value2 and returns the reminder.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.reminder('10', '3'); // return '1.00'

round(value1, [, roundingContext])

Static method.
Returns value1 round to the spcified rounding context.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.round('6.123456'); // no context no rounding 
r = Banana.SDecimal.round('6.123456', {'decimals':2}); // return '6.12'

roundNearest(value1, nearest, [, roundingContext])

Static method.
Returns value1 round to the specified minimal amount.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.roundNearest('6.17', '0.1'); // return '6.1'
r = Banana.SDecimal.roundNearest('6.17', '0.05', {'decimals':2}); // return '6.15'

invert(value, [, roundingContext])

Static method.
The invert function reverses the sign of a numeric value. If the input is positive, it returns the corresponding negative value. If the input is negative, it returns the corresponding positive value. The result is optionally rounded based on the provided roundingContext.

Parameters:

• value (string): The Numeric string whose sign is to be inverted.
• roundingContext (optional): A rounding specification (e.g., number of decimal places). If provided, the result will be rounded accordingly.

Returns:

• A Numric String representing the value with its sign inverted, optionally rounded.

var a = Banana.SDecimal.invert('5'); //return '-5'
var b = Banana.SDecimal.invert('-2.50'); //return '2.50'

sign(value)

Static method.
Returns an integer value

• 1 if value > 0
• 0 if  value = 0
• -1 if value < 0

var r = Banana.SDecimal.sign('-5'); // return '-1'

 subtract(value1, value2 [, roundingContext])

Static method.
Subtract value2 from value1 and returns the result.

• value1 and value2 are Numeric String.
• return value is a Numeric String.

var r = Banana.SDecimal.subtract('10', '3'); // return '7.00'

Locale conversion

To convert to and from the locale format use the Banana.Converter functions

• Banana.Converter.toInternalNumberFormat(value [, decimals, convZero])
• Banana.Converter.toLocaleNumberFormat(value [, decimalSeparator])

var sum = Banana.SDecimal.add('10000', '2000'); // return '12000.00'
var printValue = Banana.Converter.toLocaleNumberFormat(sum); // return "12'000.00"