Recipe 14.4. Formatting the Date and Time

Problem

You want to display a formatted date and/or time value.

Solution

Use Date.toString( ), or use the custom DateFormat.format( ) method that returns the date and time as a string in the requested format.

Discussion

The Date.toString( ) method returns a user-friendly string version of the target Date object; for example:

// Displays (something like): Tue Jan 5 14:25:20 GMT-0800 2010 trace((new Date(  )).toString(  ));

Because ActionScript automatically invokes the toString( ) method on any object used in a string context, you can obtain the same result even if you omit toString( ), as in the following example:

// Also displays: Tue Jan 5 14:25:20 GMT-0800 2010 trace(new Date(  ));

The Date class doesn't have any other built-in functionality for formatting a date or time in a customized way. You can, of course, compose a string value, as in the following example:

var example:Date = new Date(2010, 0, 5, 10, 25); var formatted:String = (example.month + 1) + "/" + example.fullYear; trace(formatted);  // Displays: 1/2010

However, you may have to write a lot of custom code each time you want to display the date and/or time. Instead, you can use the format( ) method of an ascb.util.DateFormat instance. The DateFormat class is a custom class that is specifically designed to assist with formatting dates and times when given a mask. The mask can be composed of any characters, but some characters act like variables. Table 14-1 shows the characters you can use as variables when creating the mask.

Table 14-1. Date and time symbols

Symbol	Meaning	Example
a	Lowercase a.m. or p.m.	a.m.
A	Uppercase A.M. or P.M.	P.M.
d	Day of month (leading 0)	01
D	Abbreviated day of week	Sun
F	Month	January
g	12-hour	1
G	24-hour	1
h	12-hour (leading 0)	01
H	24-hour (leading 0)	01
i	Minutes (leading 0)	01
j	Day of month	1
l	Day of week	Sunday
m	Numeric month (leading 0)	01
M	Abbreviated month	Jan
n	Numeric month	1
s	Seconds (leading 0)	01
t	Days in month	31
w	Numeric day of week	0
y	2-digit year	06
Y	4-digit year	2006

When you create a DateFormat object, you should pass it a mask string as a parameter to the constructor. Most characters that aren't used as variables in the mask context are interpreted literally. For example, the following creates a DateFormat object that outputs the date in standard U.S. format with forward slashes between the month, date, and year:

var formatter:DateFormat = new DateFormat("m/d/Y");

Once you've created a DateFormat object, you can call the format( ) method to format any Date instance as a string using the mask you specified:

var example:Date = new Date(2010, 0, 5, 10, 25); var formatter:DateFormat = new DateFormat("m/d/Y"); trace(formatter.format(example));  // Displays: 01/05/2010

You can use the mask property to get and set the mask string. That means you can change the mask for an existing DateFormat object:

var example:Date = new Date(2010, 0, 5, 10, 25); var formatter:DateFormat = new DateFormat("m/d/Y"); trace(formatter.format(example));  // Displays: 01/05/2010 formatter.mask = "m/d/Y h:i a"; trace(formatter.format(example));  // Displays: 01/05/2010 10:25 am

You can also use single quotes around any portion of the mask that you want to have interpreted literally.

That's important if you want to display any of the characters that would otherwise be interpreted as variables within the mask:

var example:Date = new Date(2010, 0, 5, 10, 25); var formatter:DateFormat = new DateFormat("m/d/Y at h:i a"); trace(formatter.format(example));  // Displays: 01/05/2010 am31 10:25 am formatter.mask = "m/d/Y 'at' h:i a"; trace(formatter.format(example));  // Displays: 01/05/2010 at 10:25 am

See Also

Recipe 14.5; the variable characters used in the mask are the same as those used by PHP. You may find the information at http://www.php.net/manual/en/function.date.php useful for reference.