JsWorld

Numeric, Currency and
Date/Time Parsing

1. Localised parsing

Since its 2.0 version JsWorld provides a set of parsing classes. You can use them to parse localised number, currency and date/time input from your web application users, for example in HTML forms.

The parsers are configured in the same way as the formatting classes, using a jsworld.Locale object representing the properties of the chosen locale.

2. Numeric parsing

To parse localised number amounts you need to create a new jsworld.NumericParser object set up for the expected locale. Here is an example, where the number to parse is formatted according to the en_US locale settings. Notice that it is important to use a try-catch statement to be able to handle any exceptions raised during parsing!

<!-- Load the JsWorld classes -->
<script type="text/javascript" src="JsWorld.min.js"></script>

<!-- Load the en_US locale properties object "POSIX_LC.en_US" -->
<script type="text/javascript" src="locales/js/en_US.js"></script>

<script type="text/javascript">

	var formattedNumber = "  - 123,456.789 ";

	// Create number parser for en_US locale
	var lc = new jsworld.Locale(POSIX_LC.en_US);
	var parser = new jsworld.NumericParser(lc);

	try {
		var parsedNumber = parser.parse(formattedNumber);
		document.writeln("Parsed original number: " + parsedNumber);
	} catch (error) {
		alert(error);
	}

</script>

If the number is correctly formatted the script will print the following result:

Parsed original number: -123456.789

The numeric parser is relatively flexible in treating the input; it will accept non-essential variations in the input such as leading and trailing whitespace or amounts formatted without thousands separators.

These are all valid inputs to the above en_US parser:

"-123,456.789"    -> -123456.789
"   -123,456.789" -> -123456.789
"-123,456.789  "  -> -123456.789
"-123456.789"     -> -123456.789

You can check the jsworld.NumericParser API docs for additional information.

3. Monetary parsing

Parsing of formatted currency amounts is done with the jsworld.MonetaryParser class.

Here is an example how to initialise and apply the parser, for the de_DE locale (which has the Euro as its currency):

<!-- Load the JsWorld classes -->
<script type="text/javascript" src="JsWorld.min.js"></script>

<!-- Load the de_DE locale properties object "POSIX_LC.de_DE" -->
<script type="text/javascript" src="locales/js/de_DE.js"></script>

<script type="text/javascript">

	var formattedAmount = "-1.234.567,89 €";

	// Create monetary parser for de_DE locale
	var lc = new jsworld.Locale(POSIX_LC.de_DE);
	var parser = new jsworld.MonetaryParser(lc);

	try {
		var parsedAmount = parser.parse(formattedAmount);
		document.writeln("Parsed original amount: " + parsedAmount);
	} catch (error) {
		alert(error);
	}

</script>

The amount is correctly formatted for the specified locale, the parser will return the following result:

Parsed original amount: -1234567.89

The parser is designed to be flexible and allows input with leading and trailing whitespace, as well as amounts formatted without thousands separators. It also accepts input with both kinds of currency symbol -- the local (shorthand) symbol as well as amounts formatted with the international ISO 4217 code.

Parsing a British Pounds amount formatted in the en_GB locale, using an ISO 4217 code:

var formattedAmount = "GBP-1,234,567.89";

// Create monetary parser for en_GB locale
var lc = new jsworld.Locale(POSIX_LC.en_GB);
var parser = new jsworld.MonetaryParser(lc);

try {
	var parsedAmount = parser.parse(formattedAmount);
	document.writeln("Parsed original amount: " + parsedAmount);
} catch (error) {
	alert(error);
}

And the resulting parser output:

Parsed original amount: -1234567.89

Don't forget to use a try-catch clause to handle any possible exceptions that may be thrown if the input strings don't parse correctly.

You can also read the jsworld.MonetaryParser API docs for additional information.

4. Date/time parsing

Parsing of localised date, time and date/time strings is provided by the jsworld.DateTimeParser class. To instantiate the date/time parser you proceed as with the other parser classes, by loading the required JavaScript files and configuring a jsworld.Locale object to represent the chosen locale.

Here is an example showing parsing of date and time values in the Japanese locale (if you can't see the Japanese symbols your browser probably doesn't have the appropriate fonts):

<!-- Load the JsWorld classes -->
<script type="text/javascript" src="JsWorld.min.js"></script>

<!-- Load the ja_JP locale properties object "POSIX_LC.ja_JP" -->
<script type="text/javascript" src="locales/js/ja_JP.js"></script>

<script type="text/javascript">

	// Create Japanese locale object
	lc = new jsworld.Locale(POSIX_LC.ja_JP);

	// Create a date/time formatter and a parser
	formatter = new jsworld.DateTimeFormatter(lc);
	parser = new jsworld.DateTimeParser(lc);


	try {
		// Parse date
		date = formatter.formatDate("2010-04-17");
		result = parser.parseDate(date);
		document.writeln(date + " -> " + result);
		
		// Parse time
		time = formatter.formatTime("23:59:59");
		result = parser.parseTime(time);
		document.writeln(time + " -> " + result);
		
		// Parse date/time
		datetime = formatter.formatDateTime("2010-04-17 23:59:59");
		result = parser.parseDateTime(datetime);
		document.writeln(datetime + " -> " + result);
		
	} catch (error) {
		alert(error);
	}

</script>

Here is the script output. Notice that the parse methods return an ISO 8601 date/time value.

10/04/17               -> 2010-04-17
23:59:59               -> 23:59:59
2010年04月17日23:59:59  -> 2010-04-17 23:59:59

The jsworld.DateTimeParser class has three parsing methods:

The parser allows for case-insensitive matching of weekday and month names, both in full and abbreviated form, while taking account of world locales that don't have the notion of case. The parsed string must otherwise adhere to the expected locale d_fmt, t_fmt and d_t_fmt formats, otherwise an error will be thrown. Use a try-catch clause to check for such conditions.

5. ISO 8601 date/time parsing

The JsWorld also provides three utility functions to parse ISO 8601 date/time values:

If the parsing succeeds they will return a JavaScript Date object, else a parse error will be thrown. Use a try-catch clause to handle any parse exceptions. Note that time zone information isn't parsed at present.

6. Examples

All examples presented in this manual can be found here.