Number formatting

Charba provide a number format implementation which enables language-sensitive number formatting, leveraging on INTL platform.

// creates a number format
NumberFormat numberFormat = new NumberFormat();
// formats the number, shows "13.576.453,87"
Console.log(numberFormat.format(13576453.865));

Creating

A number format can be created and consumed as following:

// creates locale
CLocale german = CLocaleBuilder.create(Language.GERMAN).build();
// creates a number format
// with default locale and
// default options
NumberFormat numberFormat = new NumberFormat();
// creates a number format
// with a locale and
// default options
NumberFormat nfGerman = new NumberFormat(german);
// creates number format options
NumberFormatOptions options = new NumberFormatOptions();
// creates a number format
// with a locale and
// specific options
NumberFormat nfGermanOptions = new NumberFormat(german, options);

Options

A number format can be configured, when created, by the set of options which can change the number formatting, together with the locale.

// creates locale
CLocale german = CLocaleBuilder.create(Language.GERMAN).build();
// creates number format options
NumberFormatOptions options = new NumberFormatOptions();
// sets the currency options
options.setStyle(Style.CURRENCY);
options.setCurrency(Currency.EURO);
options.setCurrencyDisplay(CurrencyDisplay.SYMBOL);
// creates a number format
// with a locale and
// specific options
NumberFormat nfGermanOptions = new NumberFormat(german, options);
// formats the number, shows "13.576.453,87 €"
Console.log(nfGermanOptions.format(13576453.865)); 

The complete options are described by following table:

Name	Type	Default	Description
compactDisplay	CompactDisplay	CompactDisplay.SHORT	Set the compact display when notation is set to Notation.COMPACT.
currency	Currency	null	The currency to use in currency formatting.
currencyDisplay	CurrencyDisplay	CurrencyDisplay.SYMBOL	How to display the currency in currency formatting.
currencySign	CurrencySign	CurrencySign.STANDARD	In many locales, accounting format means to wrap the number with parentheses instead of appending a minus sign.
localeMatcher	LocaleMatcher	LocaleMatcher.BEST_FIT	The locale matching algorithm to use.
maximumFractionDigits	int	The default for plain number formatting is the larger of minimumFractionDigits and 3. The default for currency formatting is the larger of minimumFractionDigits and the number of minor unit digits provided by Currency. The default for percent formatting is the larger of minimumFractionDigits and 0.	The maximum number of fraction digits to use. Possible values are from 0 to 20.
maximumSignificantDigits	int	21	The maximum number of significant digits to use. Possible values are from 1 to 21.
minimumFractionDigits	int	The default for plain number and percent formatting is 0. The default for currency formatting is the number of minor unit digits provided by Currency.	The minimum number of fraction digits to use. Possible values are from 0 to 20.
minimumIntegerDigits	int	1	The minimum number of integer digits to use. Possible values are from 1 to 21.
minimumSignificantDigits	int	1	The minimum number of significant digits to use. Possible values are from 1 to 21.
notation	Notation	Notation.STANDARD	The formatting that should be displayed for the number.
numberingSystem	NumberingSystem	null	The numbering system to use for number formatting.
signDisplay	SignDisplay	SignDisplay.AUTO	When to display the sign for the number.
style	Style	Style.DECIMAL	The formatting style to use.
unitOfMeasureDisplay	MeasureUnitDisplay	MeasureUnitDisplay.SHORT	The unit formatting style to use in unit formatting.
unitsOfMeasure	MeasureUnit[]	[]	The unit to use in unit formatting.
useGrouping	boolean	true	Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators.

See INTL number format documentation for the details of each option.

Using

The number format provides a set of methods to enable the number formatting.

The most important one is format, to format a double as following:

// creates a number format
NumberFormat numberFormat = new NumberFormat();
// formats the number, shows "13.576.453,87"
Console.log(numberFormat.format(13576453.865D));

Resolving options

resolveOptions method provides a object with properties reflecting the locale and number formatting options computed during initialization.

// creates a number format
NumberFormat numberFormat = new NumberFormat(CLocale.US);
// gets the resolved options
IsDefaultNumberFormatOptions resolvedOptions = numberFormat.resolveOptions();
// gets currency resolved options
resolvedOptions.getStyle();
resolvedOptions.getCurrency();
resolvedOptions.getCurrencyDisplay();

Formatting to parts

formatToParts method is useful for custom formatting of number strings. It returns a list of format part objects containing the locale-specific tokens from which it possible to build custom strings while preserving the locale-specific parts.

// creates a number format
NumberFormat numberFormat = new NumberFormat(CLocale.US);
// gets the format parts
List<FormatPart> parts = numberFormat.formatToParts(13576453.865);
// scans the list , logging them
parts.forEach((element) -> Console.log(element.getType().name()+" : "+element.getValue()));
// result to console:
// INTEGER : 13
// GROUP : ,
// INTEGER : 576
// GROUP : ,
// INTEGER : 453
// DECIMAL : .
// FRACTION : 865