currencyFormat
Formats a number as a currency expression.
Parameters
VALUE (number)
The number to format.
CURRENCY (string)
Optional. The ISO code for the currency unit (e.g. USD or JPY). All supported codes are available from the parameter dropdown in the Function Builder.
Default: USD
FORMAT (string)
Optional. The format pattern. You can enter your own pattern or select from the parameter dropdown in the Function Builder. See Syntax for number format patterns for guidance.
Default:
¤#,##0.00LOCALE (string)
Optional. Determines which characters to use for decimal and thousand separators in the output expression. All supported locales are included in the parameter dropdown in the Function Builder.
Default: en_US
NEGATIVE RED (Boolean)
Optional. Whether to display negative numbers in red (true) or the standard text color (false).
Default: false
Important
The default values above are the system defaults. You can change these defaults in your project's Settings view. See Settings > Number and Currency for guidance.
Examples
Assume the settings in Settings > Number and Currency are:
Setting | Value |
|---|---|
LOCALE |
|
CURRENCY FORMAT |
|
CURRENCY |
|
NEGATIVE RED |
|
DECIMAL PLACES FOR ABBREVIATION |
|
Tip
We explain how currency format patterns are made up in Syntax for number format patterns.
ATL in Script | Result | Notes |
|---|---|---|
| $50.00 | The optional parameters are unspecified, so a currency expression is created using the project settings. |
| -$50.00 | The optional parameters are unspecified, so a currency expression is created using the project settings. |
| £50.00 | The currency is set to GBP. The project settings for pattern (#,##0.00) and locale (en_US) apply by default. |
| £50.0 | The currency is set to GBP. The format pattern ensures that the currency symbol precedes a number displayed to one decimal place. The default locale (en_US) applies. |
| €50,00 | The currency is set to EUR. The format pattern ensures the currency symbol precedes a number displayed to two decimal places. The locale is set to de_DE (German, Germany), so a comma is used for the decimal separator. |
| 50,00 € | Identical to the example above except in one respect: the format pattern ensures the currency symbol appears after the number. The blank space in the format string is reproduced in the result. |
| 50,00 EUR | Identical to the example above except one important respect: the format pattern includes two currency signs, so the currency unit is displayed in code form. |
| £1235 | The format pattern ensures the number is displayed in an integer form. The pattern has no thousands separator so no separator appears in the result. The function applies half-up rounding. |
| £1,235 | The format pattern ensures the number is displayed in an integer form. The pattern contains a thousands separator so a separator appears in the result. As per the en_GB locale, the separator character is a comma. |
| €1.234,56 | The format pattern ensures the number is displayed to two decimal places. The locale is set to es_ES (Spanish, Spain), so a period is used for the thousands separator and a comma is used for the decimal separator. |
| €1 234,56 | The format pattern ensures the number is displayed to two decimal places. The locale is set to fr_FR (French, France), so a space is used for the thousands separator and a comma is used for the decimal separator. |
Positive and negative subpatterns
These examples use a currency format string that includes both a positive and negative subpattern:
ATL in Script | Result |
|---|---|
| ￥1,234.56 |
| (￥1,234.56) |
Tip
We explain the syntax for subpatterns in Positive and negative subpatterns.
Using the NEGATIVE RED parameter
These examples show how to use the optional NEGATIVE RED parameter:
ATL in Script | Result | Notes |
|---|---|---|
| -$50 | The fifth parameter is unspecified so the project setting (false) applies and no color formatting is applied to the negative input value. |
| -$50 | Same as above except the fifth parameter is set to true. This ensures that color formatting is applied to the negative input value. |
| ($50) | Same as above except a negative subpattern is included in the third parameter. This ensures that the negative value is displayed in brackets with color formatting. |
Tip
Remember you can control the defaults for the CURRENCY PATTERN and NEGATIVE RED parameters in Settings > Number and Currency. This will help you to avoid or minimize use of these optional parameters.
Abbreviating currency expressions
To abbreviate currency expressions, use the abbreviateNumber function.
ATL in Script | Result |
|---|---|
| $1,234.56 |
| $1.2K |
Localized currency symbols
The function returns a localized currency symbol when it's necessary to avoid ambiguity. For example:
ATL in Script | Result |
|---|---|
| CA$1,234.56 |
The currency unit is the Canadian dollar, which normally uses the $ symbol. However, the locale (en_AU) is for Australia, which also uses $ for its currency symbol. To remove the ambiguity, the function returns a localized currency symbol, CA$, instead.
Another way to avoid ambiguity is to change the format pattern (third parameter) to ensure the function returns a three-letter code rather than a symbol. For example, [[currencyFormat(1234.56,'CAD','¤¤ #,##0.00','en_AU')]] returns CAD 1,234.56.
The function uses the standard (non-localized) currency symbol when there's no conflict.
ATL in Script | Result |
|---|---|
| $1,234.56 |
Tip
Both examples above specify a locale in the function call. If unspecified, the locale is taken from your project settings. See the LOCALE setting in Settings > Number and Currency.
