Date Class

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

Date Class

Flash 5

current time and structured support for date information

Constructor

new Date() new Date(milliseconds) new Date(year, month, day, hours, minutes, seconds, ms)

Arguments

milliseconds: The number of milliseconds between the new date and midnight of January 1, 1970 UTC (Coordinated Universal Time, akin to GMT positive if after; negative if before. Any required local time zone adjustment is made after the date in UTC time is determined. For example, specifying a milliseconds argument of 1000 in Eastern Standard Time creates a date 1 second past midnight on January 1, 1970 in UTC time, which translates to 7:00:01 P.M. on December 31, 1969 in EST time (5 hours behind UTC time).
year: An integer specifying the year. Required when using the year,...ms constructor format. If year is one or two digits, it is treated as the number of years since 1900 (e.g., a year of 11 refers to the year 1911, not 2011). Use four-digit numbers to specify year 2000 or later (e.g., use 2010, not 10). Three-digit years are treated as prior to 1000 A.D. In Flash 5, when year is negative or less than 800, the calculation is unreliable. In Flash 6, a negative year specifies the number of years before 1900. To specify dates prior to 1000 A.D., it's safest to use the single milliseconds constructor format.
month: An integer specifying the month, from 0 (January) to 11 (December), not from 1 to 12. Required when using the year,...ms constructor format. Out-of-range months are carried over to the next or previous year. For example, a month argument of 13 is treated as February of the following year.
day: An optional integer specifying the day, from 1 to 31. Defaults to 1 if not specified. Out-of-range days are carried over to the next or previous month. For example, September 31 is treated as October 1, September 0 is treated as August 31, and September -1 is treated as August 30.
hours: An optional integer specifying the hour, from 0 (midnight) to 23 (11 P.M.). Defaults to 0 if not specified. A.M. and P.M. notation are not supported, so use 24-hour time. Out-of-range hours are carried over to the next or previous day. For example, an hours argument of 25 is treated as 1 A.M. of the following day.
minutes: An optional integer specifying the minute, from 0 to 59. Defaults to if not specified. Out-of-range minutes are carried over to the next or previous hour. For example, a minutes argument of 60 is treated as the first minute of the following hour.
seconds: An optional integer specifying the seconds, from 0 to 59. Defaults to if not specified. Out-of-range seconds are carried over to the next or previous minute. For example, a seconds argument of -1 is treated as the last second of the previous minute.
ms: An optional integer specifying the milliseconds, from 0 to 999. Defaults to 0 if not specified. Out-of-range milliseconds are carried over to the next or previous second. For example, a ms argument of 1005 is treated as 5 milliseconds into the following second.

Class Methods

UTC( ): Retrieve the number of milliseconds between January 1, 1970 and a supplied UTC date.

Methods

getDate( ): Retrieve the day of the month, from 1 to 31.
getDay( ): Retrieve the day of the week, as a number from 0 (Sunday) to 6 (Saturday).
getFullYear( ): Retrieve the four-digit year.
getHours( ): Retrieve the hour of the specified Date object, from 0 to 23.
getMilliseconds( ): Retrieve the milliseconds of the specified Date object, from 0 to 999.
getMinutes( ): Retrieve the minutes of the specified Date object, from 0 to 59.
getMonth( ): Retrieve the month of the year, as a number from 0 (January) to 11 (December).
getSeconds( ): Retrieve the seconds of the specified Date object, from 0 to 59.
getTime( ): Retrieve the date in internal format (i.e., the number of milliseconds between the date and January 1, 1970).
getTimezoneOffset( ): Retrieve the number of minutes between UTC and local time.
getUTCDate( ): Retrieve the day of the month, from 1 to 31, in UTC time.
getUTCDay( ): Retrieve the day of the week, from 0 (Sunday) to 6 (Saturday), in UTC time.
getUTCFullYear( ): Retrieve the four-digit year in UTC time.
getUTCHours( ): Retrieve the hour of the day, from 0 to 23, in UTC time.
getUTCMilliseconds( ): Retrieve the milliseconds, from 0 to 999, in UTC time.
getUTCMinutes( ): Retrieve the minutes, from 0 to 59, in UTC time.
getUTCMonth( ): Retrieve the month of the year, from 0 (January) to 11 (December), in UTC time.
getUTCSeconds( ): Retrieve the seconds, from 0 to 59, in UTC time.
getYear( ): Retrieve the year, relative to 1900.
setDate( ): Assign the day of the month.
setFullYear( ): Assign the year in four-digit format.
setHours( ): Assign the hour of the day.
setMilliseconds( ): Assign the milliseconds.
setMinutes( ): Assign the minutes.
setMonth( ): Assign the month of the year.
setSeconds( ): Assign the seconds.
setTime( ): Assign the date in internal format (i.e., the number of milliseconds between the date and January 1, 1970).
setUTCDate( ): Assign the day of the month in UTC time.
setUTCFullYear( ): Assign the four-digit year in UTC time.
setUTCHours( ): Assign the hour of the day in UTC time.
setUTCMilliseconds( ): Assign the milliseconds in UTC time.
setUTCMinutes( ): Assign the minutes in UTC time.
setUTCMonth( ): Assign the month of the year in UTC time.
setUTCSeconds( ): Assign the seconds in UTC time.
setYear( ): Assign the year in four-digit format, or in two-digit format for the twentieth century.
toString( ): A human-readable string representing the date.
valueOf( ): The number of milliseconds between the date and midnight of January 1, 1970 UTC.

Description

We use objects of the Date class to determine the current time and date and as a means of storing arbitrary dates and times in a structured format.

In ActionScript, a specific date is represented by the number of milliseconds before or after midnight of January 1, 1970. If the number of milliseconds is positive, the date comes after midnight, January 1, 1970; if the number of milliseconds is negative, the date comes before midnight, January 1, 1970. For example, if a date value is 10000, the date being described is 12:00:10, January 1, 1970. If a date value is -10000, the date being described is 11:59:50, December 31, 1969.

Normally, however, we needn't worry about calculating the number of milliseconds to a particular date; the ActionScript interpreter takes care of that for us. When we construct a Date object, we simply describe our date as a year, month, day, hour, minute, second, and millisecond. The interpreter then converts that point in time to the internal milliseconds-from-1970 format. We can also ask the interpreter to create a new Date object using the current time. Once a Date object is created, we can use the Date class's methods to retrieve and set the date's year, month, day, hour, minute, second, and millisecond.

There are three ways to make a new Date object:

Invoke the Date( ) constructor with no arguments. This sets the new Date object to the current time.
Iinvoke the Date( ) constructor with one numeric argument: the number of milliseconds between midnight, January 1, 1970 and the date we're creating.
Invoke the Date( ) constructor with two to seven numeric arguments, corresponding to the year and month (mandatory) and (optionally) the day, hour, minute, second, and millisecond of the date we're creating.

Because dates are stored internally as a single number, objects of the Date class do not have properties to retrieve and set. Rather, they have methods that we use to access the various components of a date in human-readable terms (i.e., in more convenient units). For example, to determine the month of a particular Date object, we use:

myMonth = myDate.getMonth();

We cannot use:

myMonth = myDate.month;  // There's no such property! We have to use methods.

Many Date methods contain the letters "UTC," which is an abbreviation for Coordinated Universal Time. For most purposes, UTC time is directly synonymous with the more colloquial Greenwich Mean Time, or GMT, the time as measured on the Greenwich meridian. UTC simply is a newer standard that is less ambiguous than GMT, which has had several meanings over history. The UTC methods allow us to work with times directly in Coordinated Universal Time without converting between time zones. The equivalent non-UTC methods all generate values based on local, adjusted time zones.

Usage

All dates and times, including the UTC times, are determined according to the settings on the client-side operating system on which the Flash movie is running (not the web server) and include regional offsets and, in some cases, daylight savings times. Times and dates, therefore, are only as accurate as the user's system.

When Date( ) is used as a global function without the new keyword it generates a string that expresses the current time in the same format as would be returned by Date.toString( ).

ActionScript does not include a built-in means to convert a string into a Date object, as is supported in JavaScript.

Example

Dates can be added and subtracted to calculate cumulative times or elapsed times. Suppose our friend Graham decides to go traveling for a little less than a year. While he's gone, we want to keep track of how many days he's been away and how many days we have to wait for him to return. The following code takes care of our countdown:

// Assign the current time to now. var now = new Date();     // Graham leaves September 7, 2000 (remember, months start at 0, // so September is 8, not 9). var departs = new Date(2000, 8, 7);     // Graham comes back August 15, 2001. var returns = new Date(2001, 7, 15);     // Convert the times to milliseconds for easy comparison.  // Then check how many milliseconds have elapsed between the two times.  var gone = now.getTime() - departs.getTime();     // Divide the difference between the departure date and now by the number  // of milliseconds in a day. This tells us how many days we've been waiting. var numDaysGone = Math.floor(gone/86400000);     // Use the same technique to determine how many days we have left to wait. // But this time round up (using the ceil( ) function) instead of rounding down. var left = returns.getTime() - now.getTime(); var numDaysLeft = Math.ceil(left/86400000);     // Display our days in text fields. this.createTextField("goneOutput_txt", 1, 0, 0, 200, 20); this.createTextField("leftOutput_txt", 2, 0, 40, 200, 20); goneOutput_txt.text = "gone for: " + numDaysGone + " days"; leftOutput_txt.text = "returns in: " + numDaysLeft + " days";

When adding a day to, or subtracting a day from, an existing date, we normally assign the number of milliseconds in a day (86400000) to a variable, for convenient use. The following code adds one day to the current date:

oneDay = 86400000; now = new Date(); tomorrow = new Date(now.getTime() + oneDay);     // We could also add one day to the date in now like this now.setTime(now.getTime() + oneDay);

To apply custom formatting to a date, we must manually map the return values of getDate( ), getDay( ), getHours( ), and so on, to custom strings as shown in the following example:

// Takes any Date object and returns a string of the format: // Saturday December 16 function formatDate (theDate) {   var months = ["January", "February", "March", "April",                  "May", "June", "July", "August", "September",                  "October", "November", "December"];   var days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday",                "Friday", "Saturday"];   var dateString = days[theDate.getDay()] + " "                    + months[theDate.getMonth()] + " "                    + theDate.getDate();   return dateString; }     now = new Date(); trace("Today is " + formatDate(now));

The next example shows how to convert the 24-hour clock return value of getHours( ) to a 12-hour clock with AM and PM:

// Takes any Date object and returns a string of the format: // "2:04PM" function formatTime (theDate) {   var hour = theDate.getHours();   var minute = theDate.getMinutes() > 9 ?                theDate.getMinutes() : "0" + theDate.getMinutes();   if (hour > 12) {     var timeString = (hour - 12) + ":" + minute + "PM";   } else {     var timeString = hour + ":" + minute + "AM";   }   return timeString; }     now = new Date(); trace("The time is " + formatTime(now));

For an example that uses the Date class to create an analog-style clock, see Section 13.11 in Chapter 13. Note that programming time-based behavior, such as a 10-second pause in a movie, is often accomplished more easily with the global functions getTimer( ) and setInterval( ).