Final Class: IntlNumberConverter

Oracle® JavaScript Extension Toolkit (JET)
15.1.0
F83698-01

Since:
  • 0.6.0
Module:
  • ojconverter-number

QuickNav

Methods

Type Definitions

Other Topics

Description

Constructs an immutable instance and initializes it with the options provided. When initialized with no options, the default options for the current locale are assumed. The converters by default use the current page locale (set with the html lang attribute and what is returned by oj.Config.getLocale()). There are several ways to initialize the converter.

  • Using options defined by the ECMA 402 Specification, these would be the properties style, currency, currencyDisplay, minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, useGrouping. NOTE: minimumSignificantDigits and maximumSignificantDigits are not supported.
  • Using the decimalFormat option to define a locale-based pattern, e.g., a compact pattern, such as "1M" and "1 million".
  • Using the currencyFormat option to define a locale-based pattern, e.g., a compact pattern, such as "$1M" and "$1 million".
  • Using the roundingMode and roundDuringParse options to round the number UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN or HALF_EVEN.
  • Using a custom decimal, currency or percent format pattern. specified using the 'pattern' property. (deprecated)

The converter provides leniency when parsing user input value to a number in the following ways:

  • Prefix and suffix that do not match the pattern, are removed. E.g., when the options are {style: "percent"} (suffix is the % character), a value of "abc-123.45xyz", will be leniently parsed as if the value was -123.45 to -123%
  • When a value includes a symbol but the pattern doesn't require it. E.g., the options are {pattern: "###", currency: 'USD'}, then values ($123), (123) and -123 will be leniently parsed as -123.

Lenient parse can be disabled by setting the property lenientParse to "none". In which case the user input must be an exact match of the expected pattern and all the leniency described above will be disabled.

Migration

Please be aware that newer converters are available and IntlNumberConverter will be deprecated in the future. See the docs for BigDecimalStringConverter and NumberConverter for more details.


Usage

Signature:

final class IntlNumberConverter extends NumberConverter

Typescript Import Format
//To import this class, use the format below.
import {IntlNumberConverter} from "ojs/ojconverter-number";

For additional information visit:


Final classes in JET

Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.


Constructor

new IntlNumberConverter(options)

Parameters:
Name Type Argument Description
options oj.IntlNumberConverter.ConverterOptions <optional>
 an object literal used to provide optional information to initialize the converter.

Methods

format(value) : {string}

Formats a Number and returns the formatted string, using the options this converter was initialized with.
Parameters:
Name Type Description
value number to be formatted for display
Throws:
a ConverterError both when formatting fails, or if the options provided during initialization cannot be resolved correctly.
Type
Error
Returns:

the localized and formatted value suitable for display. When the value is formatted as a percent it's multiplied by 100.

Type
string

getHint : {null}

In general, returns hint for the converter. For a IntlNumberConverter returned value is always null.
Returns:

a hint describing the format the value is expected to be in.

Type
null

getOptions : {oj.IntlNumberConverter.ConverterOptions}

Returns the options called with converter initialization.
Deprecated:
Since Description
11.0.0 Use resolvedOptions.
Returns:

an object of options.

Type
oj.IntlNumberConverter.ConverterOptions

parse(value) : {number|null}

Parses a string value to return a Number, using the options this converter was initialized with.
Parameters:
Name Type Description
value string to parse
Throws:
a ConverterError both when parsing fails, or if the options provided during initialization cannot be resolved correctly.
Type
Error
Returns:

the parsed number or null if the value was null or an empty string. When the value is parsed as a percent its 1/100th part is returned.

Type
number | null

resolvedOptions : {oj.IntlNumberConverter.ConverterOptions}

Returns an object literal with properties reflecting the number formatting options computed based on the options parameter. If options (or pattern) is not provided, the properties will be derived from the locale defaults.
Throws:
a ConverterError when the options that the converter was initialized with are invalid.
Returns:

An object literal containing the resolved values for the following options. Some of these properties may not be present, indicating that the corresponding components will not be represented in the formatted output.

  • locale: a String value with the language tag of the locale whose localization is used for formatting.
  • style: a String value. One of the allowed values - "decimal", "currency" or "percent".
  • currency: a String value. an ISO 4217 alphabetic currency code. May be present only when style is currency.
  • currencyDisplay: a String value. One of the allowed values - "code", "symbol", or "name".
  • numberingSystem: a String value of the numbering system used. E.g. latn
  • minimumIntegerDigits: a non-negative integer Number value indicating the minimum integer digits to be used.
  • minimumFractionDigits: a non-negative integer Number value indicating the minimum fraction digits to be used.
  • maximumFractionDigits: a non-negative integer Number value indicating the maximum fraction digits to be used.
  • useGrouping: a Boolean value indicating whether a grouping separator is used.
  • lenientParse: specifies if lenient parse is enabled or disabled. Allowed values: "full", "none". default is "full" which means lenient parse is enabled.
  • separators: - An object with 2 fields: 'decimal' and 'group'.

Type
oj.IntlNumberConverter.ConverterOptions

Type Definitions

ConverterOptions

Properties:
Name Type Argument Description
currency string <optional>
 specifies the currency that will be used when formatting the number. The value should be a ISO 4217 alphabetic currency code. If the style is set to currency, it's required that the currency property also be specified. This is because there is no default currency associated with the current locale. The user must always specify the currency code to be shown, otherwise an error will be thrown. The current page locale (returned by oj.Config.getLocale()) determines the formatting elements of the number like grouping separator and decimal separator. The currency code tells us which currency to display in current page locale. JET has translations for currency names.

As an example if we want to format 1000.35 EURO and the page locale is "en-US", we pass {style:'currency', currency:'EUR', currencyDisplay:'symbol'} and we will get "€1,000.35" If the page locale is "fr-FR", with the same options, we will get: "1 000,35 €"

currencyDisplay 'code' | 'symbol' | 'name' <optional>
 if the number is using currency formatting, specifies if the currency will be displayed using its "code" (as an ISO 4217 alphabetic currency code), "symbol" (a localized currency symbol (e.g. $ for US dollars, £ for Great British pounds, and so on), or "name" (a localized currency name. Allowed values are "code", "symbol" and "name". The default is "symbol".
currencyFormat 'standard' | 'short' | 'long' <optional>
 specifies the currency format length to use when style is set to "currency". Allowed values are : "standard"(default), "short" and "long". 'standard' is equivalent to not specifying the 'currencyFormat' attribute, in that case the locale's default currency pattern is used for formatting. Similar to decimalFormat, currencyFormat can only be used for formatting. It can not be used for parsing.

The user can also specify 'minimumFractionDigits' and 'maximumFractionDigits' to display. When not present we use the locale's default max and min fraction digits.

There is no need to specify the scale; we automatically detect greatest scale that is less or equal than the input number. For example 1000000 is formatted as "$1M" or "1 million dollar" and 1000 is formatted as "$1K" or " 1 thousand dollar" for short and long formats respectively. The pattern for the short and long number is locale dependent and uses plural rules for the particular locale.

decimalFormat 'standard' | 'short' | 'long' <optional>
 specifies the decimal format length to use when style is set to "decimal". Allowed values are : "standard"(default), "short" and "long". 'standard' is equivalent to not specifying the 'decimalFormat' attribute, in that case the locale’s default decimal pattern is used for formatting.

The user can also specify 'minimumFractionDigits' and 'maximumFractionDigits' to display. When not present we use the locale's default max and min fraction digits.

There is no need to specify the scale; we automatically detect greatest scale that is less or equal than the input number. For example 1000000 is formatted as "1M" or "1 million" and 1234 is formatted, with zero fractional digits, as "1K" or " 1 thousand" for short and long formats respectively. The pattern for the short and long number is locale dependent and uses plural rules for the particular locale.

NOTE: Currently this option formats a value (e.g., 2000 -> 2K), but it does not parse a value (e.g., 2K -> 2000), so it can only be used in a readOnly EditableValue because readOnly EditableValue components do not call the converter's parse function.

lenientParse 'full' | 'none' <optional>
 The lenientParse property can be used to enable or disable leninet parsing. Allowed values: "full" (default), "none".

By default the lenient parse is enabled and the leniency rules descibed above will be used. When lenientParse is set to "none" the lenient parse is disabled and the user input must match the expected input otherwise an exception will be thrown.
maximumFractionDigits number <optional>
 follows the same rules as 'minimumFractionDigits', but sets the maximum number of fractional digits that are allowed. The value will be rounded if there are more digits than the maximum specified.
minimumFractionDigits number <optional>
 similar to 'minimumIntegerDigits', except it deals with the digits after the decimal place (fractional digits). It must be an integer between 0 and 20. The fractional digits will be padded with trailing zeros if they are less than the minimum.
minimumIntegerDigits number <optional>
 sets the minimum number of digits before the decimal place (known as integer digits). The number is padded with leading zeros if it would not otherwise have enough digits. The value must be an integer between 1 and 21.
pattern string <optional>
 an optional localized pattern, where the characters used in pattern are as defined in the Unicode CLDR for numbers, percent or currency formats. When present this will override the other "options".

  - When the pattern represents a currency style the 'currency' property is required to be set, as not setting this will throw an error. The 'currencyDisplay' is optional.
Example: {pattern: '¤#,##0', currency: 'USD'}.

  - It's not mandatory for the pattern to have the special character '¤' (currency sign) be present. When not present, values are treated as a currency value, but are not formatted to show the currency symbol.
Example: {pattern: '#,##0', currency: 'USD'}

  - When the pattern represents a percent style, the percent special character ('%') needs to be explicitly specified in the pattern, e.g., {pattern: "#,##0%"}. If the pattern does not contain the percent character it's treated as a decimal pattern, unless the style is set to percent, in which case the value is treated as a percent value, but not formatted to show the percent symbol.
Example: {style: 'percent', pattern: "#,##0"}.

  - A decimal pattern or exponent pattern is specified in the pattern using the CLDR conventions.
Example: {pattern: "#,##0.00"} or {pattern: "0.##E0"}.

NOTE: 'pattern' is provided for backwards compatibility with existing apps that may want the convenience of specifying an explicit format mask. Setting a pattern will override the default locale specific format.

Deprecated:
Since Description
11.0.0 Use other options instead like style

roundDuringParse boolean <optional>
 Specifies whether or not to round during parse. Defaults to false; the number converter rounds during format but not during parse.
roundingMode 'HALF_UP' | 'HALF_DOWN' | 'HALF_EVEN' | 'UP' | 'DOWN' | 'CEILING' | 'FLOOR' <optional>
 specifies the rounding behavior. This follows the Java.Math.RoundingMode behavior. https://docs.oracle.com/javase/7/docs/api/java/math/RoundingMode.html
separators oj.IntlNumberConverter.Separators <optional>
 An object with 2 fields: 'decimal' and 'group'. It allows the user to provide custom decimal and grouping separators. It is accepted for both format and parse methods.
style 'decimal' | 'currency' | 'percent' | 'unit' <optional>
 sets the style of number formatting. Allowed values are "decimal" (the default), "currency", "percent" or "unit". When a number is formatted as a decimal, the decimal character is replaced with the most appropriate symbol for the locale. In English this is a decimal point ("."), while in many locales it is a decimal comma (","). If grouping is enabled the locale dependent grouping separator is also used. These symbols are also used for numbers formatted as currency or a percentage, where appropriate.
unit 'byte' | 'bit' <optional>
 Mandatory when style is "unit". Allowed values: "byte" or "bit". It is used for formatting only. It can not be used for parsing.

It is used to format digital units like 10Mb for bit unit or 10MB for byte unit. There is no need to specify the scale of the unit. We automatically detect it. For example 1024 is formatted as 1KB and ?1048576? as 1MB. The user can also specify 'minimumFractionDigits' and 'maximumFractionDigits' to be displayed, otherwise we use the locale's default max and min fraction digits.

useGrouping boolean <optional>
 when the value is truthy, the locale dependent grouping separator is used when formatting the number. This is often known as the thousands separator, although it is up to the locale where it is placed. The ‘useGrouping’ is set to true by default.

Separators

Properties:
Name Type Argument Description
decimal string <optional>
 Allows the user to provide custom decimal separators.
Example: { style:'decimal', separators: {decimal: ',', group: '.'}};
group string <optional>
 Allows the user to provide custom group separators.
Example: { style:'decimal', separators: {decimal: ',', group: '.'}};