JsWorld

Numeric Formatting

1. Basic number formatting

To format numeric amounts first you need to load JsWorld.min.js and a JavaScript object describing the properties of your chosen locale. The library package ships with ready locale definitions for over 450 world locales, put into files (one per locale) in the locales/js/ directory.

This is best shown with a concrete example, here for the en_US (American English/US) locale:

<script type="text/javascript" src="JsWorld.min.js"></script>
<script type="text/javascript" src="locales/js/en_US.js"></script>

The first script element loads the library logic, including the two classes required to format numbers -- jsworld.Locale and jsworld.NumericFormatter, the second script element loads an object called POSIX_LC.en_US containing the locale properties.

To create a numeric formatter for the en_US locale:

// Create an en_US locale object required 
// to configure the numeric formatter
var lc = new jsworld.Locale(POSIX_LC.en_US);

// Now create the formatter
var nf = new jsworld.NumericFormatter(lc);

Now you've got a numeric formatter configured for the en_US locale. Invoke its format method and pass a few numbers:

// print a few localised numbers
document.writeln(nf.format(2500000.001));
document.writeln(nf.format(-2500000.999));

// you can also pass a string value
document.writeln(nf.format("100000.00"));

The above should produce the following output, with the proper radix character and thousands separator for the en_US locale:

 2,500,000.001
-2,500,000.999

100,000

2. Modifying the formatted output

The jsworld.NumericFormatter.format() method can also accept a second optional string argument to modify the output format:

Here is an example demonstrating how the options work. You can mix several at a time to obtain the desired formatting effect.

var num = -777000;

document.writeln("default output   : " + nf.format(num));
document.writeln("no grouping      : " + nf.format(num, "^"));
document.writeln("no +/- signs     : " + nf.format(num, "~"));
document.writeln("3 decimal digits : " + nf.format(num, ".3"));
document.writeln("options mix      : " + nf.format(num, "^~.3"));

The resulting output:

default output   : -777,000
no grouping      :  -777000
no +/- signs     :  777,000
3 decimal digits : -777,000.000
options mix      :   777000.000

When specifying a lower decimal precision than the one of the input number the numeric formatter will perform implicit rounding:

// print three numbers forcing a precision of 6 decimal places
document.writeln(nf.format(10, ".6"));
document.writeln(nf.format(20.5, ".6"));
document.writeln(nf.format(30.0000009, ".6"));

Notice that the third output number was rounded:

10.000000
20.500000
30.000001

3. Exception handling

The jsworld.Locale and jsworld.NumericFormatter classes will raise an exception if something goes wrong. The two typical exception cases are:

You can guard against such error conditions by using a try-catch clause:

try {
	var lc = new jsworld.Locale(POSIX_LC.en_US);
	var nf = new jsworld.NumericFormatter(lc);
	nf.format("abc");
	
} catch (error) {
	document.writeln(error);
}

In the above example the format method is passed a string that doesn't parse to a number, so you'll get the following exception:

Error: Input string not a number

4. The locale properties defining numeric formatting

The JsWorld library uses the POSIX LC_NUMERIC standard to describe the formatting of numeric quantities in a particular locale. There are just three properties for that.

Property Description
decimal_point defines the decimal delimiter
thousands_sep defines the separator for groups of digits to the left of the decimal delimiter
grouping defines the size of each group of digits to the left of the decimal delimiter

The exact LC_NUMERIC specification is available in the corresponding POSIX document. The JsWorld API docs also have a description of them.

To create your own local number formatting you can either create your own locale properties object from scratch and pass it to the jsworld.Locale constructor, or modify an existing POSIX_LC.* definition.

5. Examples

All examples presented in this manual can be found here.

6. API documentation

Auto-generated documentation for the jsworld.NumericFormatter class is available here.