Intro
With a recent change in UI5 version 1.130, we corrected the formatting of decimal places for currencies.
If no decimals are provided in the oFormatOptions of the sap.ui.core.format.NumberFormat.getCurrencyInstance API (either via the direct format option decimals or via currency customizing as specified by the format option customCurrencies), the given value is formatted with the decimals value defined by the CLDR standard.
What's different?
Prior to this change, applications may have defined currency formats, which relied on the maxFractionDigits format option to specify the number of decimal places. This is incorrect usage, as the maxFractionDigits parameter is meant to define the maximum but not the actual number of decimals.
Example - Prior to the change:
- Values to be formatted: ["123.456", "USD"]
- Format options: {maxFractionDigits: 3}
- Formatted result: "123.456 USD"
With our change established, this behavior has changed. Now the semantics of the maxFractionDigits/minFractionDigits format options is correctly interpreted for currency formats, namely as the maximum and minimum number of permitted decimals.
Example - After the change:
- Values to be formatted: ["123.456", "USD"]
- Format options: {maxFractionDigits: 3}
- Formatted result: "123.46 USD" (rounding is applied)
For the en locale, the formatted result has 2 decimal places:
- The maxFractionDigits define a maximum of 3 decimal places
- The CLDR data defines the USD currency in the en locale with 2 decimal places
As 2 < 3, this is the correct result. The output does not exceed the maximum number of decimal places in this format, and the currency is formatted according to the locale-specific standard.
This change also affects the formatting of currencies with fewer decimal places than expected by their CLDR configurations.
Example - Prior to the change:
- Values to be formatted: ["123.4", "USD"]
- Format options: {minFractionDigits: 0}
- Formatted result: "123.4 USD"
In the prior behavior, the number of decimal places remained the same if the number given contained more decimal places than defined by the minFractionDigits option.
Example - After the change:
- Values to be formatted: ["123.4", "USD"]
- Format options: {minFractionDigits: 0}
- Formatted result: "123.40 USD"
With the new change in place, this is not the case anymore as the CLDR defines the number of decimal places for the USD currency in the given locale as 2. Therefore, a zero is padded at the end.
What does that mean for tests and applications?
The new behavior of tests and applications depends on the application setup. If the currency formats either use currency customizing where decimals are defined for all currencies or define a decimals format option for their binding, the behavior stays the same.
If, on the other hand, an application relies on the maxFractionDigits option to always determine the number of decimal places on its currency formats, this cannot be assured anymore. Only if maxFractionDigits < decimals may the maxFractionDigits option still be used to format the output.
Thus, it is up to the application developer to decide, between one of the following alternatives:
For more information regarding the format options available for our NumberFormat.getCurrencyInstance API, see: sap.ui.core.format.NumberFormat.getCurrencyInstance
