ldml-number

LDML number formatter

This is a number formatter that uses the Unicode LDML number syntax to specify the output.

Installing

It's available on npm:

npm i --save ldml-number

Alternatively there are web-compatible builds under lib/ which you can include in your page directly.

Using

The module is a constructor function which returns a reusable number formatting function.

const format = ldmlnum([pattern [, locale]]);

In praxis the usage will be something like this:

const ldmlnum = require('ldml-number');
const format = ldmlnum("#,##0.#");
format(1234.56) // "1,234.6"

The web-builds expose the module in the global namespace as ldmlnum.

Patterns

The pattern parameter defaults to "#,##0.###;-#,##0.###".

A pattern contains a positive subpattern and may contain a negative subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part, and a suffix. If there is no explicit negative subpattern, the implicit negative subpattern is the ASCII minus sign (-) prefixed to the positive subpattern.

Refer to the LDML number syntax for the interpretation of the characters.

Localization

You can prefer a locale as a BCP-47 tag when a formatter is created:

const format_en = ldmlnum('#,##0.0#');
const format_sv = ldmlnum('#,##0.0#', 'sv');

format_en(1234.56) // "1,234.56"
format_sv(1234.56) // "1.234,56"

This works with subtags if you need variants:

const format_en = ldmlnum('#,##0.0#', 'de');
const format_sv = ldmlnum('#,##0.0#', 'de-AT');

When the subtag isn't available but the base language is, the base language is used. So ldmlnum('#,##0.0#', 'sv-XX) would return a formatter with sv properties assuming sv-XX hasn't been set.

The tags are case-sensitive, but formatter is will try to resolve - and _. You can therefore assign to en_US but call it with a en-US tag.

The library supports the entire set of CLDR locales out of the box.

Note, however, that dialects that don't deviate from their language are not explicitly specified. Because es-AR has the same options as es the formatter will fallback to es when called with the dialect. This has the one implication that you cannot safely expect to be able to manually change a single setting by accessing ldmlnum.locale[some_language_tag].

Defining locales:

You might want to specify your locale beforehand.

The module object has a locale collection object attached that you must assign new locales to. You can do it manually:

ldmlnum.locale.en = {
  thousands_separator: ',',
  decimal_separator: '.',
  positive_sign: '+',
  negative_sign: '-',
  exponent_symbol: 'E',
  infinity_symbol: '∞',
  nan_symbol: '☹'
};

Partial assignments will default to English (here above) for the missing properties.

Alternatively, you can use a function:

ldmlnum.locale([ group, decimal, plus, minus, exp, inf, nan ])

All parameters are optional. The usual usage would be:

const ldmlnum = require('ldml-number');

# define locales
ldmlnum.locale.de = ldmlnum.locale('.', ',');
ldmlnum.locale.de_AT = ldmlnum.locale(' ', ',');

# format some numbers
const format = ldmlnum( '#,##0.0#', 'de' );
format( 1234.56 ) // "1.234,56"

const format_AT = ldmlnum( '#,##0.0#', 'de-AT' );
format_AT( 1234.56 ) // "1 234,56"

Rounding

The LDML specifies half even rounding. This function is available from the outside:

ldmlnum.round(number[, decimal_places ])

The formatter calls this very function so you may overwrite it in case you want something else.