Recipe 10.3 Formatting the Date and Time

10.3.1 Problem

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

10.3.2 Solution

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

10.3.3 Discussion

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

// Displays: Mon May 26 11:32:46 GMT-0400 2003
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: Mon May 26 11:32:46 GMT-0400 2003
trace(new Date(  ));

You can rewrite the Date.toString( ) method to return a different date format:

Date.prototype.toString = function (  ) {
  return "Milliseconds since the Epoch: " + this.getTime(  );
};
// Both display: Milliseconds since the Epoch: 1053963542360
trace (new Date().toString(  ));
trace (new Date(  ));

However, a better approach is to implement a flexible, custom formatting method that accepts a parameter specifying the desired date format. Fortunately, there is a standard implementation for date formatting in languages such as Java, which you can imitate. Table 10-1 shows the symbols you should use in creating the formatting string that is passed to the custom format( ) method.

Table 10-1. Date and time symbols

Symbol	Meaning	Example
y	Year	2002
M	Month in year	December or 12 (depends on context: MM means 12 ; MMM means December)
d	Day in month	01
h	Hour in A.M./P.M. (1-12)	12
H	Hour in day (0-23)	21
m	Minute in hour	24
s	Second in minute	33
S	Millisecond in second	960
E	Day in week	Sunday or Sun (depends on context: E means Sunday; EEE means Sun)
a	A.M./P.M.	AM or PM

The custom format( ) method should accept a string parameter indicating the date/time format. It should use a switch statement to return the value in the designated format. The Date.days and Date.months arrays (see Recipe 10.2) must be accessible for the following example code to work properly. (You should include this code in your Date.as file along with the Date.days and Date.months arrays.)

Date.days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", 
             "Friday", "Saturday"];
Date.months = ["January", "February", "March", "April", "May", "June", "July",
               "August", "September", "October", "November", "December"];

// This custom helper method converts a number value to a two-digit string so that
// single-digit values are formatted correctly (e.g., 5 becomes 05).
Date.toTens = function (val) {
  if (val < 10) {
    return "0" + val;
  } else {
    return String(val);
  }
};

// Converts the integer time to a string representation. The 24-hour clock (where 
// hours is from 0 to 23) in converted to a 12-hour clock with AM/PM indictor. 
Date.toTwelveHour = function (hour, min) {
  var amPm = "AM";
  if (hour > 12) {
    hour = hour - 12;
    amPm = "PM";
  } else if (hour == 0) {
    hour = 12;
  }
  return Date.toTens(hour) + ":" + Date.toTens(min) + " " + amPm;
};

Date.prototype.format = function (format) {

  // Create local variables with the date's values.
  var day       = this.getDay(  );
  var monthDate = this.getDate(  );
  var month     = this.getMonth(  );
  var year      = this.getFullYear(  );
  var hour      = this.getHours(  );
  var min       = this.getMinutes(  );
  var sec       = this.getSeconds(  );
  var millis    = this.getMilliseconds(  );

  // Return a string with the date and/or time in the requested format, such as
  // "MM-dd-yyyy". You may want to add more cases to implement the remaining formats
  // within Table 10-1.
  switch (format) {
    case "MM-dd-yyyy":
      return Date.toTens(month + 1) + "-" + Date.toTens(monthDate) + "-" + year;
    case "MM/dd/yyyy":
      return Date.toTens(month + 1) + "/" + Date.toTens(monthDate) + "/" + year;
    case "dd-MM-yyyy":
      return Date.toTens(monthDate) + "-" + Date.toTens(month + 1) + "-" + year;
    case "dd/MM/yyyy":
      return Date.toTens(monthDate) + "/" + Date.toTens(month + 1) + "/" + year;
    case "hh:mm a":
      return Date.toTwelveHour(hour, min);
    case "EEE, MMM dd, yyyy":
      return Date.days[day].substr(0, 3) + ", " + Date.months[month] + " " + 
             Date.toTens(monthDate) + ", " + year;
    case "E, MMM dd, yyyy":
      return Date.days[day] + ", " + Date.months[month] + " " + 
             Date.toTens(monthDate) + ", " + year;
  }
};

Here are a few examples of the format( ) method being used:

// Create a date for December 1, 2002, which is a Sunday. The time is 06:09PM.
myDate = new Date(2002, 11, 1, 18, 9);

trace(myDate.format("MM-dd-yyyy"));   // Displays: 12-01-2002
trace(myDate.format("MM/dd/yyyy"));   // Displays: 12/01/2002
trace(myDate.format("dd-MM-yyyy"));   // Displays: 01-12-2002
trace(myDate.format("dd/MM/yyyy"));   // Displays: 01/12/2002
trace(myDate.format("hh:mm a"));      // Displays: 06:09 PM
// Displays: Sun, December 01, 2002
trace(myDate.format("EEE, MMM dd, yyyy"));
// Displays: Sunday, December 01, 2002 06:09 PM
trace(myDate.format("E, MMM dd, yyyy") + " " + myDate.format("hh:mm a"));

10.3.4 See Also

It is possible to enhance the format( ) method by adding more cases to the switch statement. This is left to you as an exercise. You may find the information at http://www.php.net/manual/en/function.date.php useful as a reference. Also refer to Recipe 10.4.