Class: OraNumberConverter

Oracle® JavaScript Extension Toolkit (JET)
3.2.0

E87541-01

QuickNav

OraNumberConverter

Version:
  • 3.2.0
OraNumberConverter object implements number parsing and formatting for decimal, currency, percent and perMill types. It supports ECMA-402 options and user defined pattern. The user defined pattern is parsed in order to derive the options that can be specified as ECMA options. There are several ways to use 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 a custom decimal, currency or percent format pattern. specified using the 'pattern' property
  • Using the decimalFormat option to define a compact pattern, such as "1M" and "1 million".
  • Using the roundingMode and roundDuringParse options to round the number HALF_UP, HALF_DOWN, or HALF_EVEN.

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 pattern is "#,##0.00%" (suffix is the % character), a value of "abc-123.45xyz", will be leniently parsed to -123.45
  • 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.

Constructor

new OraNumberConverter()

Properties:
Name Type Argument Description
options Object <optional>
an object literal used to provide optional information to initialize the converter.
Properties
Name Type Argument Description
style string <optional>
sets the style of number formatting. Allowed values are "decimal" (the default), "currency" or "percent". 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.
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 string <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".
decimalFormat string <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.

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.
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.
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.
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.
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.##E+0"}.

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.

roundingMode string <optional>
specifies the rounding behavior. This follows the Java.Math.RoundingMode behavior. Currently we support the options: HALF_UP, HALF_DOWN, and HALF_EVEN
roundDuringParse boolean <optional>
Specifies whether or not to round during parse. Defaults to false; the number converter rounds during format but not during parse.
separators Object <optional>
An object with 2 fields: 'decimal' and 'group'. It allows the user to override the locale's default decimal and grouping separators. It is accepted for both format and parse methods.
lenientParse string <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.

Source:
Examples

Create a number converter for currencies

var converter = OraNumberConveter.getInstance();
var options = {style: "currency", currency: "USD", minimumIntegerDigits: 2};
var localeElements;
var nb = 9;
converter.format(nb, localeElements, options); --> "$09.00" if page locale is 'en-US'
converter.format(nb, localeElements, options); --> "09,00 $US" if page locale is 'fr-FR'

Options for percent values using a custom (CLDR) pattern

var options = {pattern: '#,##0%'};
converter = converterFactory.createConverter(options);

To parse a value as percent but format it without displaying the percent character

var options = {style: 'percent', pattern: '#,##0'};

To parse a value as currency using a custom (CLDR) pattern

var options = {pattern: '¤#,##0', currency: 'USD'};

The following decimalFormat examples are in en locale. To format a value as short (default for fraction digits is based on the locale)

var options = {style:'decimal', decimalFormat:'short'};
var nb = 12345
converter.format(nb, localeElements, options);--> 12.354K

To format a value as long (default for fraction digits is based on the locale):

var options = {style:'decimal', decimalFormat:'long'};
var nb = 12345;
converter.format(nb, localeElements, options);--> 12.345 thousand

To format a value as short with minimum fraction digits:

options = { style:'decimal', decimalFormat:'short', minimumFractionDigits:4};
var nb = 1234;
converter.format(nb, localeElements, options);--> 1.2340K

To format a value as short with maximum fraction digits:

options = { style:'decimal', decimalFormat:'short', maximumFractionDigits:0};
 var nb = 1234;
converter.format(nb, localeElements, options);--> 12K

To format a value as long with minimum and maximum fraction digits:

options = { style:'decimal', decimalFormat:'long', 
minimumFractionDigits:2, maximumFractionDigits:4};
var nb = 12000;
converter.format(nb, localeElements, options);--> 12.00 thousand

To format a value as short with minimum and maximum fraction digits:

options = { style:'decimal', decimalFormat:'long', 
minimumFractionDigits:2, maximumFractionDigits:4};
var nb = 12345678;
converter.format(nb, localeElements, options);--> 12.345 million

decimal style default is standard:

options = { style:'decimal', decimalFormat:'standard'}; 
var nb = 12345;
converter.format(nb, localeElements, options);--> 12,345

decimal round HALF_DOWN:

options = { style:'decimal',  maximumFractionDigits:2, roundingMode:'HALF_DOWN'}; 
var nb = 0.225;
converter.format(nb, localeElements, options);--> 0.22
var str = "0.225";
converter.parse(str, localeElements, options);-->0.225 //doesn't round during parse by default

decimal round HALF_UP:

options = { style:'decimal',  maximumFractionDigits:2, roundingMode:'HALF_UP'}; 
var nb = 0.225;
converter.format(nb, localeElements, options);--> 0.23
var str = "0.225";
converter.parse(str, localeElements, options);--> 0.225 //doesn't round during parse by default

decimal round HALF_EVEN:

options = { style:'decimal',  maximumFractionDigits:2, roundingMode:'HALF_EVEN'}; 
converter.format(0.225, localeElements, options);--> 0.22
converter.format(0.235, localeElements, options);--> 0.24
converter.parse("0.225", localeElements, options);--> 0.225 //doesn't round during parse by default
converter.parse("0.235", localeElements, options);--> 0.235 //doesn't round during parse by default

decimal round HALF_DOWN and roundDuringParse:

options = { style:'decimal', maximumFractionDigits:2, 
            roundingMode:'HALF_DOWN', roundDuringParse: true};
var nb = 0.225; 
converter.format(nb, localeElements, options);--> 0.22
var str = "0.225";
converter.parse(str, localeElements, options);-->0.22

decimal round HALF_UP and roundDuringParse:

options = { style:'decimal',  maximumFractionDigits:2, 
            roundingMode:'HALF_UP', roundDuringParse: true}; 
var nb = 0.225;
converter.format(nb, localeElements, options);--> 0.23
var str = "0.225";
converter.parse(str, localeElements, options);--> 0.23

decimal round HALF_EVEN and roundDuringParse:

options = { style:'decimal',  maximumFractionDigits:2, 
            roundingMode:'HALF_EVEN', roundDuringParse: true}; 
converter.format(0.225, localeElements, options);--> 0.22
converter.format(0.235, localeElements, options);--> 0.24
converter.parse("0.225", localeElements, options);--> 0.22
converter.parse("0.235", localeElements, options);--> 0.24

Override locale's decimal and grouping separators:

in en-US locale, the decimal separator is '.' and grouping separator is ','. In this example we will swap them.
options = { style:'decimal', separators: {decimal: ',',  group: '.'}};
var nb = 1234567.89; 
converter.format(nb, localeElements, options);--> 1.234.567,89
converter.parse("1.234.567,89", localeElements, options);--> 1234567.89

Disable lenient parse:

options = { style:'decimal',  lenientParse: 'none'}; 
converter.parse("abc-123.45xyz", localeElements, options);--> Error: Unparsable number abc-123.45xyz The expected number pattern is #,##0.###

Methods

<static> format(value, localeElements, options, locale) → {string}

Format a number.
Parameters:
Name Type Argument Description
value number Number object to be formatted.
localeElements Object the instance of LocaleElements bundle
options Object <optional>
Containing the following properties:
- style. is one of the String values "decimal", "currency" or "percent". The default is "decimal".
- decimalFormat. is used in conjuction with "decimal" style. It can have one of the string values "short", "long". It is used for compact number formatting. For example 3000 is displayed as 3K for "short" and 3 thousand for "long". We take into consideration the locale's plural rules for the compact pattern.
- currency. An ISO 4217 alphabetic currency code. Mandatory when style is "currency".
- currencyDisplay. is one of the String values "code", "symbol", or "name", specifying whether to display the currency as an ISO 4217 alphabetic currency code, a localized currency symbol, or a localized currency name if formatting with the "currency" style. It is only present when style has the value "currency". The default is "symbol".
- minimumIntegerDigits. is a non-negative integer Number value indicating the minimum integer digits to be used. Numbers will be padded with leading zeroes if necessary.
- minimumFractionDigits. a non-negative integer Number value indicating the minimum fraction digits to be used. Numbers will be padded with trailing zeroes if necessary.
- maximumFractionDigits. a non-negative integer Number value indicating the maximum fraction digits to be used. Numbers will be rounded if necessary.
- roundingMode. specifies the rounding behavior. This follows the Java.Math.RoundingMode behavior. Currently we support the options : HALF_UP, HALF_DOWN, and HALF_EVEN
- useGrouping. is a Boolean value indicating whether a grouping separator should be used. The default is true.
- separators. - An object with 2 fields: 'decimal' and 'group'. It allows the user to override the locale's default decimal and grouping separators.
- pattern. custom pattern. Will override above options when present.
locale string <optional>
A BCP47 compliant language tag. it is only used to extract the unicode extension keys.
Source:
Throws:
  • If a property value of the options parameter is out of range.
    Type
    RangeError
  • If the style is currency and currency code is missing.
    Type
    TypeError
  • If an unexpected character is encountered in the pattern.
    Type
    SyntaxError
Returns:
formatted number.
Type
string

<static> getInstance() → {Object}

getInstance. Returns the singleton instance of OraNumberConverter class.
Source:
Returns:
The singleton OraNumberConverter instance.
Type
Object

<static> parse(str, localeElements, options, locale) → {number}

Parse a number.
Parameters:
Name Type Argument Description
str string | number string to be parsed.
localeElements Object the instance of LocaleElements bundle
options Object <optional>
Containing the following properties:
- style. is one of the String values "decimal", "currency" or "percent". The default is "decimal".
- currency. An ISO 4217 alphabetic currency code. Mandatory when style is "currency".
- currencyDisplay. is one of the String values "code", "symbol", or "name", specifying whether to display the currency as an ISO 4217 alphabetic currency code, a localized currency symbol, or a localized currency name if formatting with the "currency" style. It is only considered when style has the value "currency". The default is "symbol".
- pattern. custom pattern. Will override above options when present.
- roundingMode. specifies the rounding behavior. This follows the Java.Math.RoundingMode behavior. Currently we support the options : HALF_UP, HALF_DOWN, and HALF_EVEN
- roundDuringParse. Boolean value. Specifies whether or not to round during parse. by default the number converter rounds during format but not during parse.
- separators. - An object with 2 fields: 'decimal' and 'group'. It allows the user to override the locale's default decimal and grouping separators.
- lenientParse. specifies if lenient parse is enabled or disabled. Allowed values: "full", "none". default is "full" which means lenient parse is enabled.
locale string <optional>
A BCP47 compliant language tag. it is only used to extract the unicode extension keys.
Source:
Throws:
  • If a property value of the options parameter is out of range.
    Type
    RangeError
  • If the style is currency and currency code is missing.
    Type
    TypeError
  • If an unexpected character is encountered in the pattern.
    Type
    SyntaxError
  • If the str parameter does not match the number pattern.
    Type
    Error
Returns:
a number object parsed from the string. In case of error, returns null.
Type
number

<static> resolvedOptions(localeElements, options, locale) → {Object}

Resolve options. Returns a new object with properties reflecting the number formatting options computed based on the options parameter. If options is not provided, the properties will be derived from the locale defaults.
Parameters:
Name Type Argument Description
localeElements Object the instance of LocaleElements bundle
options Object <optional>
containing the following properties:
- style. "decimal", "currency" or "percent". The default is "decimal".
- decimalFormat. It can have one of the string values "short", "long". It is used for compact number formatting. For example 3000 is displayed as 3K for "short" and 3 thousand for "long". We take into consideration the locale's plural rules for the compact pattern.
- currency. An ISO 4217 alphabetic currency code. Mandatory when when style is "currency".
- currencyDisplay. is one of the String values "code", "symbol", or "name", specifying whether to display the currency as an ISO 4217 alphabetic currency code, a localized currency symbol, or a localized currency name if formatting with the "currency" style. It is only present when style has the value "currency". The default is "symbol".
- minimumIntegerDigits. is a non-negative integer Number value indicating the minimum integer digits to be used. Numbers will be padded with leading zeroes if necessary.
- minimumFractionDigits. a non-negative integer Number value indicating the minimum fraction digits to be used. Numbers will be padded with trailing zeroes if necessary.
- maximumFractionDigits. a non-negative integer Number value indicating the maximum fraction digits to be used. Numbers will be rounded if necessary.
- numberingSystem. The numbering system.
- useGrouping. is a Boolean value indicating whether a grouping separator should be used. The default is true.
- pattern. custom pattern. Will override above options when present.
- roundingMode. specifies the rounding behavior. This follows the Java.Math.RoundingMode behavior. Currently we support the options : HALF_UP, HALF_DOWN, and HALF_EVEN
- roundDuringParse. Boolean value. Specifies whether or not to round during parse. by default the number converter rounds during format but not during parse.
- separators. - An object with 2 fields: 'decimal' and 'group'. It allows the user to override the locale's default decimal and grouping separators.
- lenientParse. specifies if lenient parse is enabled or disabled. Allowed values: "full", "none". default is "full" which means lenient parse is enabled.
locale string <optional>
A BCP47 compliant language tag. it is only used to extract the unicode extension keys.
Source:
Throws:
  • If a property value of the options parameter is out of range.
    Type
    RangeError
  • If the style is currency and currency code is missing.
    Type
    TypeError
Returns:
Resolved options object.
Type
Object