Skip to main content

numberToWords()

Converts a non-negative number into English words. The execution engine registers this function globally, so a command formula can call it without defining or importing a helper.

Syntax​

numberToWords(value)

Parameters​

ParameterTypeRequiredDescription
valuenumberYesA non-negative numeric value to convert. Any fractional part is discarded.

Returns​

A string containing the English representation of the integer portion of the input. Words use title case, compound tens use a hyphen, and hundreds use and.

Examples​

numberToWords(0);
// "Zero"

numberToWords(42);
// "Forty-Two"

numberToWords(125);
// "One Hundred and Twenty-Five"

numberToWords(2500000);
// "Two Million Five Hundred Thousand"

numberToWords(1999.95);
// "One Thousand Nine Hundred and Ninety-Nine"

Loan document example​

var approvedAmount = Number(context.approvedAmount);

if (!Number.isFinite(approvedAmount) || approvedAmount < 0) {
  throw new Error('approvedAmount must be a non-negative number');
}

return {
  approvedAmount: approvedAmount,
  approvedAmountInWords: numberToWords(approvedAmount) + ' Naira Only'
};

numberToWords() does not add a currency name or an Only suffix. Add those explicitly when the output is used in a loan offer, receipt, or other financial document.

Availability​

The helper is available to JavaScript evaluated by the BankLingo command execution engine, including command formulas and ExeFormula requests. It is registered when the Jint engine is created; it is not a browser JavaScript API.

Current behavior and limits​

  • 0 returns "Zero".
  • Decimal values are rounded down with Math.floor; decimal words are not produced.
  • Negative values and invalid numeric values are not supported. Validate inputs before calling the function.
  • The supported scale names are Thousand, Million, and Billion.
  • Use values from 0 through 999,999,999,999. Trillion and larger scale names are not implemented.
  • The helper returns words only; it does not format commas, currency codes, or decimal fractions.
function amountInWords(value) {
  var amount = Number(value);

  if (!Number.isFinite(amount) || amount < 0 || amount >= 1000000000000) {
    throw new Error('Amount must be between 0 and 999,999,999,999');
  }

  return numberToWords(amount);
}

See also​