docs

Number Format

The sap.ui.core.format.NumberFormat class can be used to parse a string representing a number (float or integer) into a JavaScript number and vice versa (also known as format).

NumberFormat uses the parameters defined for the current locale. These parameters can be overwritten on each instance by setting the format options.

There are five types of formatters defined in NumberFormat:

Instantiation

The instantiation of sap.ui.core.format.NumberFormat is done by calling a getter defined on NumberFormat (and not by using the constructor).

// "NumberFormat" required from module "sap/ui/core/format/NumberFormat"
var oIntegerFormat = NumberFormat.getIntegerInstance();
var oFloatFormat = NumberFormat.getFloatInstance();
var oPercentFormat = NumberFormat.getPercentInstance();
var oCurrencyFormat = NumberFormat.getCurrencyInstance();

Parameters

All parameters have their default value defined in the current locale. Therefore, if no parameter is given when instantiating the formatter instance, it fetches the parameters from the current locale. The samples here assume that the current locale is en-US.

All parameters can be overwritten by giving a format option object in the getter of the formatter. There are a number of parameters defined for the four types of formatters. Most of them are shared among the types, and the rest are specifically defined for a certain kind of formatter.

Integer and Decimal Digits

var oFormatOptions = {
    minIntegerDigits: 3,
    maxIntegerDigits: 5,
    minFractionDigits: 2,
    maxFractionDigits: 4
};

// "NumberFormat" required from module "sap/ui/core/format/NumberFormat"
var oFloatFormat = NumberFormat.getFloatInstance(oFormatOptions);
oFloatFormat.format(1.1); // returns "001.10"
oFloatFormat.format(1234.567); // returns "1,234.567"
oFloatFormat.format(123456.56789); // returns "??,???.5679"

var oFormatOptions = {
    style: "short",
    decimals: 1,
    shortDecimals: 2
};

// "NumberFormat" required from module "sap/ui/core/format/NumberFormat"
var oFloatFormat = NumberFormat.getFloatInstance(oFormatOptions);
oFloatFormat.format(1234.56); // returns "1.23K" (shortified number takes the shortDecimals parameter)
oFloatFormat.format(123.456); // returns "123.5" (non-shortified number takes the decimals parameter)

Separator and Signs

Compact Format

You can use compact format to format a number using a given scale. For example, 1000000 may be formatted under en-US locale as 1 Million.

To format a number in compact format, set the style option to either "short" or "long". These styles control which version of scale name is used. For example, 1000000 is formatted as 1M with "short" and 1 Million with "long".

The scale can be selected automatically based on the given number, or you can set it explicitly by using shortRefNumber. You can set this option with a number which is then used for calculating the scaling factor for formatting all given numbers to this formatter.

To hide the scaling formatter from the formatted number and only be shown once on the screen, you can use option showScale. In order to get the scaling factor name of the number set to shortRefNumber under the current locale, getScale can be used.

To control the starting point of numbers which should be displayed in compact format, shortLimit can be used.

Example:

In the following chart, all numbers both on the chart and the axis should be formatted using the same scaling factor. The scaling factor should only appear in the chart title and be hidden from the formatted number. In order to achieve this, the option shortRefNumber is set to 1000000, and showScale is set to false. The corresponding scaling factor name is returned by calling the getScale method.

Miscellaneous

Parsing and Validation of User Input

You can parse a formatted number, which can contain locale-dependent grouping separators, a locale-dependent decimal separator or a percentage sign, into a number object using sap.ui.core.format.NumberFormat. Such a number string may not be correctly parsed by using parseInt or parseFloat in JavaScript.

// "NumberFormat" required from module "sap/ui/core/format/NumberFormat"
var oFloatFormat = NumberFormat.getFloatInstance();

oFloatFormat.parse("1,234.567"); // returns 1234.567
oFloatFormat.parse("12.34%"); // returns 0.1234

When users switch between multiple UIs, websites or editors, they may encounter different characters being used as decimal and grouping separators. This can lead to incorrect numerical input if the user assumes a locale different from the one actually used by the UI. For example, in English locales the grouping separator is a comma (”,”) and the decimal separator is a dot (”.”), whereas in German locales it is the other way around.

To prevent an accidental mix-up of decimal and grouping separator in the user input, we have introduced a stricter parsing logic of sap.ui.core.format.NumberFormat by using decimal separator validation with an optional strict grouping validation. Instead of ignoring the grouping separators when parsing user input, several checks are carried out on the grouping to identify potential input errors.

Decimal Separator Validation

If not otherwise mentioned, the examples below are based on the US locale standard settings (en-US):

// "NumberFormat" required from module "sap/ui/core/format/NumberFormat"
var oOptions = {
  decimalSeparator : ".",
  groupingSeparator : ",",
  groupingSize : 3
};
var oFloatFormat = NumberFormat.getFloatInstance(oOptions);

The following user input is considered to be potentially wrong and therefore invalid:

Note:

Regarding the return value, a number with invalid grouping is treated in the same way as user input that cannot be parsed:

oFloatFormat.parse("1,2"); // NaN
 
NumberFormat.getCurrencyInstance(oOptions).parse("1,2 EUR"); // null

The following user input is considered to be valid:

Strict Grouping Validation (optional)

For an even stricter parsing of number strings, you have the option of additionally enforcing strict grouping validation by setting the strictGroupingValidation format option to true.For more information, see the API Reference.

While grouping separators are then still treated as optional and can be wholly or partially absent from the input, all grouping separators that are present must be at a correct position according to the user’s locale. Numbers with wrongly placed grouping separators are refused in all cases. This brings UI5 validation closer to the UI behavior implemented in classic SAP GUI applications.

Example:

// "NumberFormat" required from module "sap/ui/core/format/NumberFormat"
var oOptions = {
  decimalSeparator : ".",
  groupingSeparator : ",",
  groupingSize : 3,
  strictGroupingValidation: true
};
var oFloatFormat = NumberFormat.getFloatInstance(oOptions);

oFloatFormat.parse("1,2,3"); // NaN (before: 123)

Related Information

API Reference: sap.ui.core.format.NumberFormat

Unit Formatting

[Currency Formatting](currency-formatting-e978728.md “”)

This site is open source. Improve this page.