Currency

The Currency Data Type is used to represent monetary values. It pairs a Number with a currency unit and a number to indicate precision, which determines how many decimal places to include.

It is important to use the Currency type rather than Numbers when working with currency 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.)

Structure

The Asset Data Type is an object with the following properties:

  • amount (number) - the number of currency units. To prevent rounding errors, this must be an integer.
  • code (string) - the currency unit, defined by the standard currency code.
  • precision (number) - the number digits to include after the decimal.
    • This property defines the intended placement of the decimal place to compensate for the amount property not allowing floating-point number values.

Examples

The following example shows how $40, forty US dollars, can represented as a Currency value. Note that the currency code is "USD" and the precision is 2, so the Currency value is represented in US cents:

{
  "amount": 4000,
  "code": "USD",
  "precision": 2
}

The following example shows another way that $40, forty US dollars, can be represented as a Currency value. Note that the currency code is "USD" and the precision is 1, so the Currency value is represented in tens of US cents:

{
  "amount": 400,
  "code": "USD",
  "precision": 1
}

Some Airscript functions accept input in the form of Currency. For instance, FORMAT_CURRENCY takes Currency values and converts them into a string, such as in the following example:

FORMAT_CURRENCY({
  "amount": 400,
  "code": "USD",
  "precision": 0
 }
) -> "$400.00"

The value of the amount property of a currency value must be an integer. Attempting to set a floating-point number as the amount value will result in errors downstream, such as in the following example:

FORMAT_CURRENCY({
  "amount": 400.50,
  "code": "USD",
  "precision": 0
 }
) -> ERROR