Dojo: The Definitive Guide

Dates, Numbers, and Currency

Additional Core facilities provide additional support for manipulating and supporting internationalization of dates, numbers, and currency via the dojo.date, dojo.number, and dojo.currency modules, respectively. In Part II, you'll learn that Dijit makes extensive use of these modules to provide advanced support for commonly used widgets. This section provides a quick inventory of these features.

Dates

Table 6-2 shows a quick overview of the dojo.date module. As you'll see, there are some real gems in here if you ever need to perform any routine processing of the built-in Date object.

Table 6-2. Summary of the date module

Name	Return type	Comment
dojo.date.getDaysInMonth (/*Date*/date)	Integer	Returns the number of days in date's month.
dojo.date.isLeapYear (/*Date*/date)	Boolean	Returns true if date is a leap year.
dojo.date.getTimezoneName (/*Date*/date)	String	Returns time zone information as defined by the browser. A Date object is needed because the time zone may vary according to issues such as daylight savings time.
dojo.date.compare(/*Date*/ date1, /*Date*/ date2, /*String?*/ portion)	Integer	Returns 0 if the two parameters are equal; returns a positive number if date1 > date 2 ; returns a negative number if date1 < date2. By default, both date and time are compared, although providing "date" or "time" for a portion produces a comparison strictly by date or time, respectively.
dojo.date.add(/*Date*/date, /*String*/ interval, /*Integer*/ amount)	Date	Provides a convenient way to add an incremental amount to a Date object by providing a numeric amount and the type of units. Units may be "year", "month", "day", "hour", "minute", "second", "millisecond", "quarter", "week", or "weekday".
dojo.date.difference (/*Date*/date1, /*Date*/ date2, /*String*/ interval)	Integer	Provides a convenient way to calculate the difference between two Date objects in terms of a specific type of unit, which may be "year", "month", "day", "hour", "minute", "second", "millisecond", "quarter", "week", or "weekday".

Warning

As of version 1.1 of the toolkit, getTimezoneName is not localized.

Numbers

The dojo.number module provides some handy functions, shown in Table 6-3 and Table 6-4, for parsing String values into numbers, formatting a Number in accordance with a specific pattern template, or rounding to a specific number of decimal places.

Table 6-3. Formatting options for the number module that are used in the dojo.number.format and dojo.number.parse functions provided in Table 6-4

dojo.number.format options	Type	Comment
pattern	String	Can be used to override the formatting pattern.
type	String	A format type based on the locale. Valid values include "decimal", "scientific", "percent", "currency", and "decimal". "decimal" is the default.
places	Number	Provides a fixed number of places to show, which overrides any information provided by pattern.
round	Number	Specifies rounding properties based on a multiple. For example, 5 would round to the nearest 0.5 and 0 would round to the nearest whole number.
currency	String	A currency code that meets the ISO4217 standard. For example, "USD" would signify U.S. Dollars.
symbol	String	A localized currency symbol.
locale	String	Allows a specific locale to be provided which drives formatting rules.

Table 6-4. Summary of the number module

Name	Return type	Comment
dojo.number.format (/*Number*/value, /*Object*/options)	String	Formats a Number as a String using locale-specific settings. Options may take on the values from Table 6-3.
dojo.number.round (/*Number*/value, /*Number*/places)	Number	Rounds a number to a given number of places after the decimal.
dojo.number.parse (/*String*/value, /*Object*/options)	Number	Converts a properly formatted String to a Number using locale-specific settings. Valid options include the following values from Table 6-3: pattern, type, locale, strict, and currency.

Currency

The dojo.currency module, described in Table 6-5 and Table 6-6, is similar to dojo.number in that it provides a means of formatting numeric values, only this time it is currency codes as defined in ISO427.^[15]

Table 6-5. Formatting options for the currency module as used by the dojo.currency.format and dojo.currency.parse functions

Name	Type	Comment
currency	String	A three-letter currency code as defined in ISO4217 such as "USD".
symbol	String	A value that may be used to override the default currency symbol.
pattern	String	Used to override the default currency pattern.
round	Number	Used to provide rudimentary rounding: -1 means don't round at all, 0 means round to the nearest whole number, and 5 means round to the nearest one-half.
locale	String	Override the default locale, which determines the formatting rules.
places	Number	The number of decimal places to accept (default is defined by currency.)

Table 6-6. Summary of the currency module

Name	Return type	Comment
dojo.currency.format (/*Number*/value, /*Object?*/options)	String	Formats a Number as a String, using locale-specific settings. Values for options are given in Table 6-5.
dojo.currency.parse (/*String*/ expression, /*Object?*/ options)	Number	Converts a properly formatted String to a Number. Values for options are given in Table 6-5.

Tip

Some of Dojo's build tools can be used to generate support for arbitrary locales and currencies since a lot of this work simply entails building lookup tables of information. See the file located at util/buildscripts/cldr/README for more details.

---

^[15] http://en.wikipedia.org/wiki/ISO_4217.