CURRENCY

The function CURRENCY creates a value of the type Currency, which represents an amount, a currency type, and a precision.

This function creates a value of type Currency, it takes as arguments an amount, an optional currency code that specifies which world currency to create, and a precision indicating the size of the denomination.

For example, arguments of 1, "USD", and 0 would return a Currency that represents one U.S. dollar, while arguments of 100, "USD", and 2 would represent one-hundred U.S. pennies. While both Currencies represent the same monetary value, the latter will help avoid rounding errors.

See Working with Numbers and Currency in Airscript for more details. The List of Currency Codes table at the end of this article lists all valid currency codes, along with a recommended minimum precision.

Declaration

CURRENCY(amount, currency_code, precision) -> currency

Parameters

amount (required, type: number)
An integer representing the amount of the chosen currency_code multiplied by the precision.

currency_code (optional, type: string, default: "USD")
A code specifying which world currency to create. The default is "USD" for U.S. Dollars, "JPY" would represent Japanese Yen. See List of Currency Codes for a complete list of valid codes.

precision (optional, type: number, default: 2)
The precision to be used for the currency, ie. if the precision 3 and amount is 10454, the represented currency would be $10.454

Return Values

currency (type: currency)
The currency with provided, amount, code, and precision.

Examples

While currency is measured using a number, it also requires a unit. One U.S. dollar ("USD") is different from one Canadian dollar ("CAD")

CURRENCY(1, "USD", 0) -> {  
  amount: 1,  
  code: "USD",  
  precision: 0  
}  
CURRENCY(1, "CAD", 0) -> {  
  amount: 1,  
  code: "CAD",  
  precision: 0  
}

In addition to the currency code, providing a precision specifies the smallest denomination the Currency should take into account. For example, one U.S. dollar and one-hundred U.S. pennies represent the same monetary value, however, the latter is a better choice as it will help avoid rounding errors when working with the Currency.

CURRENCY(1, "USD", 0) -> {  
  amount: 1,  
  code: "USD",  
  precision: 0  
}  
CURRENCY(100, "USD", 2) -> {  
  amount: 100,  
  code: "USD",  
  precision: 2  
}

If the currency code and precision are omitted, the default will be to create the currency in U.S. pennies

CURRENCY(100) -> {  
  amount: 100,  
  code: "USD",  
  precision: 2  
}

Discussion

It is important to use the Currency type rather than a Number because there are rounding errors when working with decimal Numbers. For example the result of 0.1 + 0.2 is not 0.3 but rather 0.30000000000000004. Performing the same calculation with a precision of 2, will yield the correct result as there will be no decimal places.

10 + 20 -> 30

The table below lists the minimum recommended precision for each currency code in the second column. This number corresponds to the number of decimal places that are typically displayed for that currency. Note that some use cases may require a higher precision if more decimal places are needed.

List of Currency Codes