Number formatting

The special characters for number formatting are:

The special characters used for separators in the pattern do not indicate which characters are displayed as separators in the output text; they merely define where the separators are in the pattern. The characters used for separators in the output text are determined by the locale.

The default locale is en_US (English, United States). This locale applies the convention of using a period (full stop) for the decimal separator and a comma for thousand separators. To apply a different convention, change the default locale in Settings > Number and Currency.

This table shows the affect of changing the locale or pattern:

Notice how the locale determines which characters are printed as separators. For example, the locale en_US (English, United States) uses a period for the the decimal separator and a comma for thousand separators, whereas the locale de_DE (German, Germany) uses a comma for the decimal separator and a period for thousand separators. The number format pattern determines where the separators appear.

Each project has a default currency format pattern, which you set in the Settings view (Settings > Number and Currency). The pattern is a default value (third parameter) for the currencyFormat function.

Currency format patterns are also defined using JavaDecimalFormat syntax. They differ from number format patterns in one respect: they use the special character ¤ (also known as a currency sign) to define the position and formatting of the currency unit.

You can format a currency unit as its currency symbol (e.g. $) or its ISO code (e.g. USD). A single currency sign in your format pattern displays the currency symbol; a double currency sign displays the code. This is demonstrated below:

Your number format pattern can contain both a positive and negative subpattern. This allows you to define specific prefix and suffix characters for displaying negative numbers. The special character ; separates positive and negative subpatterns.

For example, the pattern #,##0.##;(#,##0.##) contains two subpatterns:

The format pattern above ensures that a negative number is displayed in parentheses.

Including a negative subpattern is optional. If omitted, negative numbers are automatically prefixed by a minus sign, and all other formatting is taken from the positive pattern. The effects of including a negative subpattern are shown below.

You can override your project's default number format pattern by using a formatting function:

Click on the links to learn more. Each function topic includes detailed parameter descriptions and examples.

You can nest formatting functions — that is, you can make the output from one formatting function the input to another formatting function. If there are conflicts in the formatting of nested functions, the formatting applied by the 'outer' function is applied.

To demonstrate this, and to keep the ATL simple, all examples in this section use the following user-defined variable:

As shown, myVar has an actual value of 1234.5678 and a display value of 1,234.57.

These examples show what happens when you use myVar as the input to another formatting function:

When you use a formatted number in calculations, the calculation uses the number's actual value, not its display value. For example, the ATL [[precision(123.4567,2)]] would be displayed as 123.46 in your output text, but the number's actual value (123.4567) would be used if you included the same ATL in a calculation. This applies to all ATL arithmetic operators:

The examples in this section make use of the following user-defined variables:

The Displayed As column above shows how the results are displayed in a project with the default locale set to en_US (English, United States) and the default number format pattern set to #,##0.##.

The examples below assume the same project default settings.

You can also perform calculations using in-built mathematical functions. This section shows how these work with numbers/variables to which formatting is already applied.

These examples make use of the following user-defined variables:

The Displayed As column above shows how the results are displayed in a project with the default locale set to en_US (English, United States) and the default number format pattern set to #,##0.00.

The examples below assume the same project default settings.

Functions with optional DECIMAL PLACES and STRIP TRAILING ZEROS parameters

Some mathematical functions have optional DECIMAL PLACES and STRIP TRAILING ZEROS parameters. When these optional parameters are used, they supersede the values from any previous or default formatting. For example:

The DECIMAL PLACES parameter is set to 1 and the STRIP TRAILING ZEROS parameter is set to false. These parameter values take precedence over all other number formatting, so the result is displayed to one decimal place with the trailing zero retained.