Formats numbers using the Unicode formatting standard, LDML.

Downloads in past


1.1.07 years ago7 years agoMinified + gzip package size for ldml-number in KB


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


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.


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.


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 syntaxspec for the interpretation of the characters.


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 CLDRcldr 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"


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.