Money Primitive Type

Introduction

Money is a Primitive Data Type provided in FNZ Studio which should be used for handling currencies. The following short examples illustrate how this Data Type can prevent errors.

Copy 
Money $m1 := ToMoney(12,'USD'); //dollar!!
Money $m2 := ToMoney(3,'CHF');  //swiss francs!!

$m1.add($m2) 
---->invalid since it is not correct to simply add up two different currencies!

Similar to Dates, Money provides display formatting functions according to the different Regions (Locales) :

Copy 
Money $m := ToMoney(0,'USD');
MoneyFormat($m, '$ 0.000'); ---> USD 0.000
MoneyFormat($m, '0.000 $', 'en_US'); ---> 0.000 USD

The last aspect of the Money type is the possibility to convert from one currency to another by considering the conversion rate.

Copy 
$m := MoneyConvert($m1, 'USD');
// catalog "Currencies", column "rate" (optional: column "precision")
MoneyConvert(ToMoney(1, 'USD'), 'CHF');
// catalog "Currencies", column "rate" (optional: column "precision")
MoneyConvert(ToMoney(1, 'EUR'), 'USD', 3, 'DOWN');
// catalog "Currencies", column "rate"

Calculating with Money

Various Functions are provided to calculate with the Money Data Type.

Add, Subtract, Multiply, and Divide

Example multiplication function:

Copy 
Money $m1 := ToMoney(12.566874525);
Money $m2 := ToMoney(3);
//
Money $m := $m1.add($m2);
$m := $m1.subtract($m2);
$m := $m1.multiply(0.08);

Division

Example divide function:

Copy 
$m := $m1.divide(7, 2);
$m := $m1.divide(7, 0.05);

The Money "Division" function also provides some extra rounding functions.

Note: This document does not provide the full explanation of mathematics behind these functions.

CEILING

$m := $m1.divide(7, 2, 'CEILING'); It rounds off any decimal value towards positive infinity. For a positive decimal, it performs the same rounding as RoundingMode.UP. In case of a negative decimal, it performs the same rounding as as for RoundingMode.DOWN. It does not decrement the value.

FLOOR

$m := $m1.divide(7, 2, 'FLOOR'); It rounds off any decimal value towards negative infinity. For a positive decimal, it performs the same rounding as RoundingMode.DOWN. In case of a negative decimal, it performs the same rounding as as for RoundingMode.UP. It does not increment the value.

UP

$m := $m1.divide(7, 2, 'UP'); This rounds off any given decimal value away from zero. It basically increments the decimal value.

HALF UP

$m := $m1.divide(7, 2, 'HALF_UP'); This rounds off a decimal value towards the nearest neighboring value apart from the case when both neighboring values are equidistant, in which case it just rounds up the value. It performs the same rounding as RoundingMode.UP if the discarded fractional part is >= 0.5, else it performs the same rounding as RoundingMode.DOWN.

DOWN

$m := $m1.divide(7, 2, 'DOWN'); This rounds off any given decimal value towards zero. It does not increment the value.

HALF DOWN

$m := $m1.divide(7, 2, 'HALF_DOWN'); This rounds off a decimal value towards the nearest neighboring value apart from the case when both neighboring values are equidistant, in which case it just rounds down the value. It performs the same rounding as RoundingMode.DOWN if the discarded fractional part is > 0.5, else it performs the same rounding as RoundingMode.UP.

HALF EVEN

$m := $m1.divide(7, 2, 'HALF_EVEN'); This rounds off a decimal value towards the nearest neighboring value apart from the case when both neighboring values are equidistant, in which case it just rounds towards the nearest even number. It performs the same rounding as RoundingMode.HALF_UP if the digit to the left of the discarded fractional part is odd, and performs the same rounding as RoundingMode.HALF_DOWN if it’s even.

Round Up or Down

Copy 
$m := $m1.round(2);
$m := $m1.round(0.05);
$m := $m1.round(3, 'UP');

Extract Information

Copy 
$m.getCurrency();
$m.toInteger();
$m.toDouble();
$m.getJavaCurrency().getSymbol();
//depending of the currency this will return the symbol or the ISO code such as CHF or USD

Money Extension

The Primitive Money Type is a built-in Data Type and provides only very basic mathematical functions. In addition to this, the Money Extension provides:

  • additional Functions to convert between currencies according to rates
  • a Catalog containing the most relevant currencies
  • a Screen Component with a built-in currency chooser