Usage
Signature:
final class NumberConverter
Typescript Import Format
//To import this class, use the format below.
import {NumberConverter} from "ojs/ojconverter-nativenumber";
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 NumberConverter(options)
Parameters:
Name | Type | Argument | Description |
---|---|---|---|
options |
NumberConverter.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:
an error when 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}
-
For a NumberConverter returned value is always null.
Returns:
a hint describing the format the value is expected to be in.
- Type
- null
-
parse(input) : {number}
-
Parses a string value to return a number, using the options this converter was initialized with.
Parameters:
Name Type Description input
string to parse Throws:
an error when parsing fails, or when the options provided during initialization cannot be resolved correctly.- Type
- Error
Returns:
the parsed number
- Type
- number
-
resolvedOptions : {NumberConverter.ConverterOptions}
-
Returns an object literal with properties reflecting the number formatting options computed based on the options parameter. If an option is not provided, the properties will be derived from the locale defaults.
Throws:
an error when the options that the converter was initialized with are invalid.- Type
- Error
Returns:
An object literal containing the resolved options.
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 locale 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' <optional>
specifies the currency format length to use when style is set to "currency". Allowed values are : "standard"(default) and "short". '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" and 1000 is formatted as "$1K" using short format. The pattern for short format is locale dependent and uses plural rules for the particular locale.
currencySign
'standard' | 'accounting' <optional>
if the number is using currency formatting, specifies the currency sign. In many locales, accounting format means to wrap the negative number with parentheses instead of prepending a minus sign. Allowed values are "standard" and "accounting". The default is "standard". customCurrencyCode
string <optional>
If the currencyDisplay property is set to 'code', the customCurrencyCode property will replace the currency code with the custom currency code. If the customCurrencyCode is '', it will remove the currency code, and trim any extra whitespace. customCurrencySymbol
string <optional>
If the currencyDisplay property is set to 'symbol', the customCurrencySymbol property will replace the currency symbol with the custom currency symbol. If the customCurrencySymbol is '', it will remove the currency symbol, and trim any extra whitespace. 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 lenient parsing. Allowed values: "full" (default), "none". By default the lenient parse is enabled and the leniency rules described 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.
locale
string <optional>
specifies a locale to be used by this converter instance. If this option is not provided, the converter will be calling Config.getLocale() to determine the current JET page locale. 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. 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 The default value for this property is 'HALF_UP'. separators
NumberConverter.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. If the user wants the number to be formatted like a specific locale that is different than the JET page's default locale, then you can set the NumberConverter's locale option instead of using the separators option.
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 in accordance with the the ISO-80000 standard. For example 1000 is formatted as 1KB and 1000000 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 true, 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. If the ‘useGrouping’ is not specified, grouping separators will be displayed based on the locale preference, which may also be dependent on the currency. -
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: '.'}};