class sap.ui.core.format.NumberFormat

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/core/format/NumberFormat
Application Component: CA-UI5-COR

The NumberFormat is a static class for formatting and parsing numeric values according to a set of format options.


Constructor


Methods Overview

Method Description
sap.ui.core.format.NumberFormat.extend

Creates a new subclass of class sap.ui.core.format.NumberFormat with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.base.Object.extend.

format

Format a number according to the given format options.

sap.ui.core.format.NumberFormat.getCurrencyInstance

Get a currency instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

The currency instance supports locally defined custom currency exclusive to the created instance. The following example shows how to use custom currencies (e.g. for Bitcoins):

var oFormat = NumberFormat.getCurrencyInstance({
    "currencyCode": false,
    "customCurrencies": {
        "BTC": {
            "symbol": "\u0243",
            "decimals": 3
        }
    }
});

oFormat.format(123.4567, "BTC"); // "Ƀ 123.457"

As an alternative to using a fixed symbol for your custom currencies, you can also provide an ISO-Code. The provided ISO-Code will be used to look up the currency symbol in the global configuration, either defined in the CLDR or custom defined on the Format Settings (see sap.ui.core.Configuration.FormatSettings#setCustomCurrencies, sap.ui.core.Configuration.FormatSettings#addCustomCurrencies).

If no symbol is given at all, the custom currency key is used for formatting.

var oFormat = NumberFormat.getCurrencyInstance({
    "currencyCode": false,
    "customCurrencies": {
        "MyDollar": {
            "isoCode": "USD",
            "decimals": 3
        },
        "Bitcoin": {
            "decimals": 2
        }
    }
});

// symbol looked up from global configuration
oFormat.format(123.4567, "MyDollar"); // "$123.457"

// no symbol available, custom currency key is rendered
oFormat.format(777.888, "Bitcoin"); // "Bitcoin 777.89"

sap.ui.core.format.NumberFormat.getDefaultUnitPattern

Returns a default unit format/parse pattern for the given unit short name. The returned pattern can then be used for custom units, for example as a unitPattern-count-other pattern. The unitPattern-count-other pattern is then used by NumberFormat instances as a fallback in case no other patterns are defined, see the below example:

var oFormat = NumberFormat.getUnitInstance({
    "customUnits": {
        "myUnit": {
            "unitPattern-count-other": NumberFormat.getDefaultUnitPattern("Bottles"); // returns "{0} Bottles"
        }
    }
});
oFormat.format(1234, "myUnit"); // returns "1.234,00 Bottles"

sap.ui.core.format.NumberFormat.getFloatInstance

Get a float instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

sap.ui.core.format.NumberFormat.getIntegerInstance

Get an integer instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has TOWARDS_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

sap.ui.core.format.NumberFormat.getMetadata

Returns a metadata object for class sap.ui.core.format.NumberFormat.

sap.ui.core.format.NumberFormat.getPercentInstance

Get a percent instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

sap.ui.core.format.NumberFormat.getUnitInstance

Get a unit instance of the NumberFormat, which can be used for formatting units.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

parse

Parse a string which is formatted according to the given format options.

sap.ui.core.format.NumberFormat.extend

Creates a new subclass of class sap.ui.core.format.NumberFormat with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.base.Object.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

format

Format a number according to the given format options.

Param Type DefaultValue Description
vValue number array

the number to format or an array which contains the number to format and the sMeasure parameter

sMeasure string

an optional unit which has an impact on formatting currencies and units

sap.ui.core.format.NumberFormat.getCurrencyInstance

Get a currency instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

The currency instance supports locally defined custom currency exclusive to the created instance. The following example shows how to use custom currencies (e.g. for Bitcoins):

var oFormat = NumberFormat.getCurrencyInstance({
    "currencyCode": false,
    "customCurrencies": {
        "BTC": {
            "symbol": "\u0243",
            "decimals": 3
        }
    }
});

oFormat.format(123.4567, "BTC"); // "Ƀ 123.457"

As an alternative to using a fixed symbol for your custom currencies, you can also provide an ISO-Code. The provided ISO-Code will be used to look up the currency symbol in the global configuration, either defined in the CLDR or custom defined on the Format Settings (see sap.ui.core.Configuration.FormatSettings#setCustomCurrencies, sap.ui.core.Configuration.FormatSettings#addCustomCurrencies).

If no symbol is given at all, the custom currency key is used for formatting.

var oFormat = NumberFormat.getCurrencyInstance({
    "currencyCode": false,
    "customCurrencies": {
        "MyDollar": {
            "isoCode": "USD",
            "decimals": 3
        },
        "Bitcoin": {
            "decimals": 2
        }
    }
});

// symbol looked up from global configuration
oFormat.format(123.4567, "MyDollar"); // "$123.457"

// no symbol available, custom currency key is rendered
oFormat.format(777.888, "Bitcoin"); // "Bitcoin 777.89"

Param Type DefaultValue Description
oFormatOptions object

The option object which support the following parameters. If no options is given, default values according to the type and locale settings are used.

minIntegerDigits int 1

defines minimal number of non-decimal digits

maxIntegerDigits int 99

defines maximum number of non-decimal digits. If the number exceeds this maximum, e.g. 1e+120, "?" characters are shown instead of digits.

minFractionDigits int

defines minimal number of decimal digits

maxFractionDigits int

defines maximum number of decimal digits

decimals int

defines the number of decimal digits

shortDecimals int

defines the number of decimal in the shortened format string. If this isn't specified, the 'decimals' options is used

shortLimit int

only use short number formatting for values above this limit

shortRefNumber int

@since 1.40 specifies a number from which the scale factor for 'short' or 'long' style format is generated. The generated scale factor is used for all numbers which are formatted with this format instance. This option has effect only when the option 'style' is set to 'short' or 'long'. This option is by default set with undefined which means the scale factor is selected automatically for each number being formatted.

showScale boolean true

@since 1.40 specifies whether the scale factor is shown in the formatted number. This option takes effect only when the 'style' options is set to either 'short' or 'long'.

pattern string

CLDR number pattern which is used to format the number

groupingEnabled boolean true

defines whether grouping is enabled (show the grouping separators)

groupingSeparator string

defines the character used as grouping separator. Note: groupingSeparator must always be different from decimalSeparator.

groupingSize int 3

defines the grouping size in digits, the default is three

groupingBaseSize int 3

defines the grouping base size in digits, in case it is different from the grouping size (e.g. indian grouping)

decimalSeparator string

defines the character used as decimal separator. Note: decimalSeparator must always be different from groupingSeparator.

plusSign string

defines the used plus symbol

minusSign string

defines the used minus symbol

parseAsString boolean false

@since 1.28.2 defines whether to output string from parse function in order to keep the precision for big numbers. Numbers in scientific notation are parsed back to the standard notation. For example "5e-3" is parsed to "0.005".

preserveDecimals boolean false

Whether #format preserves decimal digits except trailing zeros in case there are more decimals than the maxFractionDigits format option allows. If decimals are not preserved, the formatted number is rounded to maxFractionDigits.

style string standard

defines the style of format. Valid values are 'short, 'long' or 'standard' (based on CLDR decimalFormat). Numbers are formatted into compact forms when it's set to 'short' or 'long'. When this option is set, the default value of option 'precision' is set to 2. This can be changed by setting either min/maxFractionDigits, decimals, shortDecimals or precision option.

roundingMode sap.ui.core.format.NumberFormat.RoundingMode HALF_AWAY_FROM_ZERO

specifies a rounding behavior for discarding the digits after the maximum fraction digits defined by maxFractionDigits. Rounding will only be applied, if the passed value if of type number. This can be assigned by value in RoundingMode or a function which will be used for rounding the number. The function is called with two parameters: the number and how many decimal digits should be reserved.

trailingCurrencyCode boolean

Overrides the global configuration value sap.ui.core.Configuration.FormatSettings#getTrailingCurrencyCode whose default value is true. This is ignored if oFormatOptions.currencyCode is set to false or if oFormatOptions.pattern is supplied

showMeasure boolean true

defines whether the currency code/symbol is shown in the formatted string, e.g. true: "1.00 EUR", false: "1.00" for locale "en" If both showMeasure and showNumber are false, an empty string is returned

showNumber boolean true

defines whether the number is shown as part of the result string, e.g. 1 EUR for locale "en" NumberFormat.getCurrencyInstance({showNumber:true}).format(1, "EUR"); // "1.00 EUR" NumberFormat.getCurrencyInstance({showNumber:false}).format(1, "EUR"); // "EUR" If both showMeasure and showNumber are false, an empty string is returned

currencyCode boolean true

defines whether the currency is shown as code in currency format. The currency symbol is displayed when this is set to false and there is a symbol defined for the given currency code.

currencyContext string standard

It can be set either with 'standard' (the default value) or with 'accounting' for an accounting specific currency display

emptyString number

@since 1.30.0 defines what empty string is parsed as and what is formatted as empty string. The allowed values are "" (empty string), NaN, null or 0. The 'format' and 'parse' are done in a symmetric way. For example when this parameter is set to NaN, empty string is parsed as [NaN, undefined] and NaN is formatted as empty string.

customCurrencies Object<string,object>

defines a set of custom currencies exclusive to this NumberFormat instance. If custom currencies are defined on the instance, no other currencies can be formatted and parsed by this instance. Globally available custom currencies can be added via the global configuration. See the above examples. See also sap.ui.core.Configuration.FormatSettings#setCustomCurrencies and sap.ui.core.Configuration.FormatSettings#addCustomCurrencies.

oLocale sap.ui.core.Locale

Locale to get the formatter for

sap.ui.core.format.NumberFormat.getDefaultUnitPattern

Returns a default unit format/parse pattern for the given unit short name. The returned pattern can then be used for custom units, for example as a unitPattern-count-other pattern. The unitPattern-count-other pattern is then used by NumberFormat instances as a fallback in case no other patterns are defined, see the below example:

var oFormat = NumberFormat.getUnitInstance({
    "customUnits": {
        "myUnit": {
            "unitPattern-count-other": NumberFormat.getDefaultUnitPattern("Bottles"); // returns "{0} Bottles"
        }
    }
});
oFormat.format(1234, "myUnit"); // returns "1.234,00 Bottles"

Param Type DefaultValue Description
sShortName string

the short name of the unit used in the created pattern

sap.ui.core.format.NumberFormat.getFloatInstance

Get a float instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

Param Type DefaultValue Description
oFormatOptions object

The option object which support the following parameters. If no options is given, default values according to the type and locale settings are used.

minIntegerDigits int 1

defines minimal number of non-decimal digits

maxIntegerDigits int 99

defines maximum number of non-decimal digits. If the number exceeds this maximum, e.g. 1e+120, "?" characters are shown instead of digits.

minFractionDigits int 0

defines minimal number of decimal digits

maxFractionDigits int 99

defines maximum number of decimal digits

decimals int

defines the number of decimal digits

shortDecimals int

defines the number of decimal in the shortened format string. If this isn't specified, the 'decimals' options is used

shortLimit int

only use short number formatting for values above this limit

shortRefNumber int

@since 1.40 specifies a number from which the scale factor for 'short' or 'long' style format is generated. The generated scale factor is used for all numbers which are formatted with this format instance. This option has effect only when the option 'style' is set to 'short' or 'long'. This option is by default set with undefined which means the scale factor is selected automatically for each number being formatted.

showScale boolean true

@since 1.40 specifies whether the scale factor is shown in the formatted number. This option takes effect only when the 'style' options is set to either 'short' or 'long'.

precision int

defines the number precision, number of decimals is calculated dependent on the integer digits

pattern string

CLDR number pattern which is used to format the number

groupingEnabled boolean true

defines whether grouping is enabled (show the grouping separators)

groupingSeparator string

defines the character used as grouping separator. Note: groupingSeparator must always be different from decimalSeparator.

groupingSize int 3

defines the grouping size in digits, the default is three

groupingBaseSize int 3

defines the grouping base size in digits, in case it is different from the grouping size (e.g. indian grouping)

decimalSeparator string

defines the character used as decimal separator. Note: decimalSeparator must always be different from groupingSeparator.

plusSign string

defines the used plus symbol

minusSign string

defines the used minus symbol

parseAsString boolean false

@since 1.28.2 defines whether to output string from parse function in order to keep the precision for big numbers. Numbers in scientific notation are parsed back to the standard notation. For example "5e-3" is parsed to "0.005".

preserveDecimals boolean false

Whether #format preserves decimal digits except trailing zeros in case there are more decimals than the maxFractionDigits format option allows. If decimals are not preserved, the formatted number is rounded to maxFractionDigits.

style string standard

defines the style of format. Valid values are 'short, 'long' or 'standard' (based on CLDR decimalFormat). Numbers are formatted into compact forms when it's set to 'short' or 'long'. When this option is set, the default value of option 'precision' is set to 2. This can be changed by setting either min/maxFractionDigits, decimals, shortDecimals or precision option.

roundingMode sap.ui.core.format.NumberFormat.RoundingMode HALF_AWAY_FROM_ZERO

specifies a rounding behavior for discarding the digits after the maximum fraction digits defined by maxFractionDigits. Rounding will only be applied, if the passed value if of type number. This can be assigned by value in RoundingMode or a function which will be used for rounding the number. The function is called with two parameters: the number and how many decimal digits should be reserved.

emptyString number

@since 1.30.0 defines what empty string is parsed as and what is formatted as empty string. The allowed values are "" (empty string), NaN, null or 0. The 'format' and 'parse' are done in a symmetric way. For example when this parameter is set to NaN, empty string is parsed as NaN and NaN is formatted as empty string.

oLocale sap.ui.core.Locale

Locale to get the formatter for

sap.ui.core.format.NumberFormat.getIntegerInstance

Get an integer instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has TOWARDS_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

Param Type DefaultValue Description
oFormatOptions object

The option object which support the following parameters. If no options is given, default values according to the type and locale settings are used.

minIntegerDigits int 1

defines minimal number of non-decimal digits

maxIntegerDigits int 99

defines maximum number of non-decimal digits. If the number exceeds this maximum, e.g. 1e+120, "?" characters are shown instead of digits.

minFractionDigits int 0

defines minimal number of decimal digits

maxFractionDigits int 0

defines maximum number of decimal digits

decimals int

defines the number of decimal digits

shortDecimals int

defines the number of decimal in the shortened format string. If this isn't specified, the 'decimals' options is used

shortLimit int

only use short number formatting for values above this limit

shortRefNumber int

@since 1.40 specifies a number from which the scale factor for 'short' or 'long' style format is generated. The generated scale factor is used for all numbers which are formatted with this format instance. This option has effect only when the option 'style' is set to 'short' or 'long'. This option is by default set with undefined which means the scale factor is selected automatically for each number being formatted.

showScale boolean true

@since 1.40 specifies whether the scale factor is shown in the formatted number. This option takes effect only when the 'style' options is set to either 'short' or 'long'.

precision int

defines the number precision, number of decimals is calculated dependent on the integer digits

pattern string

CLDR number pattern which is used to format the number

groupingEnabled boolean false

defines whether grouping is enabled (show the grouping separators)

groupingSeparator string

defines the character used as grouping separator. Note: groupingSeparator must always be different from decimalSeparator.

groupingSize int 3

defines the grouping size in digits, the default is three

groupingBaseSize int 3

defines the grouping base size in digits, in case it is different from the grouping size (e.g. indian grouping)

decimalSeparator string

defines the character used as decimal separator. Note: decimalSeparator must always be different from groupingSeparator.

plusSign string

defines the used plus symbol

minusSign string

defines the used minus symbol

parseAsString boolean false

@since 1.28.2 defines whether to output string from parse function in order to keep the precision for big numbers. Numbers in scientific notation are parsed back to the standard notation. For example "5e+3" is parsed to "5000".

preserveDecimals boolean false

Whether #format preserves decimal digits except trailing zeros in case there are more decimals than the maxFractionDigits format option allows. If decimals are not preserved, the formatted number is rounded to maxFractionDigits.

style string standard

defines the style of format. Valid values are 'short, 'long' or 'standard' (based on CLDR decimalFormat). Numbers are formatted into compact forms when it's set to 'short' or 'long'. When this option is set, the default value of option 'precision' is set to 2. This can be changed by setting either min/maxFractionDigits, decimals, shortDecimals or precision option.

roundingMode sap.ui.core.format.NumberFormat.RoundingMode TOWARDS_ZERO

specifies a rounding behavior for discarding the digits after the maximum fraction digits defined by maxFractionDigits. Rounding will only be applied, if the passed value if of type number. This can be assigned by value in RoundingMode or a function which will be used for rounding the number. The function is called with two parameters: the number and how many decimal digits should be reserved.

emptyString number

@since 1.30.0 defines what empty string is parsed as and what is formatted as empty string. The allowed values are only NaN, null or 0. The 'format' and 'parse' are done in a symmetric way. For example when this parameter is set to NaN, empty string is parsed as NaN and NaN is formatted as empty string.

oLocale sap.ui.core.Locale

Locale to get the formatter for

sap.ui.core.format.NumberFormat.getMetadata

Returns a metadata object for class sap.ui.core.format.NumberFormat.

sap.ui.core.format.NumberFormat.getPercentInstance

Get a percent instance of the NumberFormat, which can be used for formatting.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

Param Type DefaultValue Description
oFormatOptions object

The option object which support the following parameters. If no options is given, default values according to the type and locale settings are used.

minIntegerDigits int 1

defines minimal number of non-decimal digits

maxIntegerDigits int 99

defines maximum number of non-decimal digits. If the number exceeds this maximum, e.g. 1e+120, "?" characters are shown instead of digits.

minFractionDigits int 0

defines minimal number of decimal digits

maxFractionDigits int 99

defines maximum number of decimal digits

decimals int

defines the number of decimal digits

shortDecimals int

defines the number of decimal in the shortened format string. If this isn't specified, the 'decimals' options is used

shortLimit int

only use short number formatting for values above this limit

shortRefNumber int

@since 1.40 specifies a number from which the scale factor for 'short' or 'long' style format is generated. The generated scale factor is used for all numbers which are formatted with this format instance. This option has effect only when the option 'style' is set to 'short' or 'long'. This option is by default set with undefined which means the scale factor is selected automatically for each number being formatted.

showScale boolean true

@since 1.40 specifies whether the scale factor is shown in the formatted number. This option takes effect only when the 'style' options is set to either 'short' or 'long'.

precision int

defines the number precision, number of decimals is calculated dependent on the integer digits

pattern string

CLDR number pattern which is used to format the number

groupingEnabled boolean true

defines whether grouping is enabled (show the grouping separators)

groupingSeparator string

defines the character used as grouping separator. Note: groupingSeparator must always be different from decimalSeparator.

groupingSize int 3

defines the grouping size in digits, the default is three

groupingBaseSize int 3

defines the grouping base size in digits, in case it is different from the grouping size (e.g. indian grouping)

decimalSeparator string

defines the character used as decimal separator. Note: decimalSeparator must always be different from groupingSeparator.

plusSign string

defines the used plus symbol

minusSign string

defines the used minus symbol

percentSign string

defines the used percent symbol

parseAsString boolean false

@since 1.28.2 defines whether to output string from parse function in order to keep the precision for big numbers. Numbers in scientific notation are parsed back to the standard notation. For example "5e-3" is parsed to "0.005".

preserveDecimals boolean false

Whether #format preserves decimal digits except trailing zeros in case there are more decimals than the maxFractionDigits format option allows. If decimals are not preserved, the formatted number is rounded to maxFractionDigits.

style string standard

defines the style of format. Valid values are 'short, 'long' or 'standard' (based on CLDR decimalFormat). Numbers are formatted into compact forms when it's set to 'short' or 'long'. When this option is set, the default value of option 'precision' is set to 2. This can be changed by setting either min/maxFractionDigits, decimals, shortDecimals or precision option.

roundingMode sap.ui.core.format.NumberFormat.RoundingMode HALF_AWAY_FROM_ZERO

specifies a rounding behavior for discarding the digits after the maximum fraction digits defined by maxFractionDigits. Rounding will only be applied, if the passed value if of type number. This can be assigned by value in RoundingMode or a function which will be used for rounding the number. The function is called with two parameters: the number and how many decimal digits should be reserved.

emptyString number

@since 1.30.0 defines what empty string is parsed as and what is formatted as empty string. The allowed values are "" (empty string), NaN, null or 0. The 'format' and 'parse' are done in a symmetric way. For example when this parameter is set to NaN, empty string is parsed as NaN and NaN is formatted as empty string.

oLocale sap.ui.core.Locale

Locale to get the formatter for

sap.ui.core.format.NumberFormat.getUnitInstance

Get a unit instance of the NumberFormat, which can be used for formatting units.

If no locale is given, the currently configured formatLocale will be used.

This instance has HALF_AWAY_FROM_ZERO set as default rounding mode. Please set the roundingMode property in oFormatOptions to change the default value.

Param Type DefaultValue Description
oFormatOptions object

The option object which support the following parameters. If no options is given, default values according to the type and locale settings are used.

minIntegerDigits int 1

defines minimal number of non-decimal digits

maxIntegerDigits int 99

defines maximum number of non-decimal digits. If the number exceeds this maximum, e.g. 1e+120, "?" characters are shown instead of digits.

minFractionDigits int

defines minimal number of decimal digits

maxFractionDigits int

defines maximum number of decimal digits

decimals int

defines the number of decimal digits

shortDecimals int

defines the number of decimal in the shortened format string. If this isn't specified, the 'decimals' options is used

shortLimit int

only use short number formatting for values above this limit

shortRefNumber int

@since 1.40 specifies a number from which the scale factor for 'short' or 'long' style format is generated. The generated scale factor is used for all numbers which are formatted with this format instance. This option has effect only when the option 'style' is set to 'short' or 'long'. This option is by default set with undefined which means the scale factor is selected automatically for each number being formatted.

showScale boolean true

@since 1.40 specifies whether the scale factor is shown in the formatted number. This option takes effect only when the 'style' options is set to either 'short' or 'long'.

precision int

defines the number precision, number of decimals is calculated dependent on the integer digits

pattern string

CLDR number pattern which is used to format the number

groupingEnabled boolean true

defines whether grouping is enabled (show the grouping separators)

groupingSeparator string

defines the character used as grouping separator. Note: groupingSeparator must always be different from decimalSeparator.

groupingSize int 3

defines the grouping size in digits, the default is three

groupingBaseSize int 3

defines the grouping base size in digits, in case it is different from the grouping size (e.g. indian grouping)

decimalSeparator string

defines the character used as decimal separator. Note: decimalSeparator must always be different from groupingSeparator.

customUnits Object<string,object>

defines a set of custom units, e.g. {"electric-inductance": { "displayName": "henry", "unitPattern-count-one": "{0} H", "unitPattern-count-other": "{0} H", "perUnitPattern": "{0}/H", "decimals": 2, "precision": 4 }}

allowedUnits array

defines the allowed units for formatting and parsing, e.g. ["size-meter", "volume-liter", ...]

plusSign string

defines the used plus symbol

minusSign string

defines the used minus symbol

parseAsString boolean

@since 1.28.2 defines whether to output string from parse function in order to keep the precision for big numbers. Numbers in scientific notation are parsed back to the standard notation. For example "5e-3" is parsed to "0.005".

preserveDecimals boolean false

Whether #format preserves decimal digits except trailing zeros in case there are more decimals than the maxFractionDigits format option allows. If decimals are not preserved, the formatted number is rounded to maxFractionDigits.

style string standard

defines the style of format. Valid values are 'short, 'long' or 'standard' (based on CLDR decimalFormat). Numbers are formatted into compact forms when it's set to 'short' or 'long'. When this option is set, the default value of option 'precision' is set to 2. This can be changed by setting either min/maxFractionDigits, decimals, shortDecimals or precision option.

roundingMode sap.ui.core.format.NumberFormat.RoundingMode HALF_AWAY_FROM_ZERO

specifies a rounding behavior for discarding the digits after the maximum fraction digits defined by maxFractionDigits. Rounding will only be applied, if the passed value if of type number. This can be assigned by value in RoundingMode or a function which will be used for rounding the number. The function is called with two parameters: the number and how many decimal digits should be reserved.

showMeasure boolean true

defines whether the unit of measure is shown in the formatted string, e.g. for input 1 and "duration-day" true: "1 day", false: "1". If both showMeasure and showNumber are false, an empty string is returned

showNumber boolean true

defines whether the number is shown as part of the result string, e.g. 1 day for locale "en" NumberFormat.getUnitInstance({showNumber:true}).format(1, "duration-day"); // "1 day" NumberFormat.getUnitInstance({showNumber:false}).format(1, "duration-day"); // "day" e.g. 2 days for locale "en" NumberFormat.getUnitInstance({showNumber:true}).format(2, "duration-day"); // "2 days" NumberFormat.getUnitInstance({showNumber:false}).format(2, "duration-day"); // "days" If both showMeasure and showNumber are false, an empty string is returned

emptyString number

@since 1.30.0 defines what empty string is parsed as and what is formatted as empty string. The allowed values are "" (empty string), NaN, null or 0. The 'format' and 'parse' are done in a symmetric way. For example when this parameter is set to NaN, empty string is parsed as [NaN, undefined] and NaN is formatted as empty string.

oLocale sap.ui.core.Locale

Locale to get the formatter for

parse

Parse a string which is formatted according to the given format options.

Param Type DefaultValue Description
sValue string

the string containing a formatted numeric value