The most common way of working with temporal data in Flash is to use the Date class. It has been around in Actionscript since version one and like its sister language Javascript, it's implementation is defined by the ECMA-262 specification.

Class vs Object
For the sake of clarification, any mention of the 'Date class' is a reference to the top level Actionscript Date class, and any mention of a 'Date object' is a reference to any instance of that class. Most of this article will deal with instances of Date objects.

What is a Date object?
A Date object is a convenient way of referencing a large collection of related temporal data in a single package. Each instance represents a snapshot of date and time information for a single point in time.

"Real time"
The value of a Date object is fixed - it is not a pointer to the current time. If you wait ten minutes and check your object again it will not have moved on. If you want to create a project such as a 'real time' clock then you will need to update the value of your Date object periodically.

There are two common ways to do this: listen for a new frame event or set up a Timer and listen for its events. You'll find source code for both of these strategies in the article Building an accurate Timekeeper in AS3.

Gotcha: Neither EnterFrame nor Timer events keep very good time. If you need to receive tick events at a uniform interval then you should consider using the AS3 Timekeeper class.

Local time vs UTC
Universal Coordinated Time (UTC) evolved from the clear need for an unambiguous world-wide standard for time. The value of UTC remains constant irrespective of your location on Earth. That makes it ideally suited to use as a timestamp. UTC is defined as the local unadjusted time at the prime meridian. Local time can be derived from UTC by adjusting for local time zone and daylight saving time conditions.

The prime meridian is an imaginary line at zero degrees longitude that runs through the Royal Observatory in Greenwich, London. UTC replaced Greenwich Mean Time (GMT) in January 1972 and is an internationally recognised time standard.

Gotcha: The ECMA-262 implementation of UTC is not complete as it does not attempt to account for leap seconds.

🟥
This post previously contained Flash content.

Epoch and Time

The Epoch
The single most important Date concept to grasp is the notion of the epoch. For all its myriad of properties and methods, the internal structure of a Date is very simple. An 'epoch' is an arbitrary point in time from which other points in time are measured. The date of the Actionscript epoch is the 1st of January 1970 UTC in the modern Gregorian calendar. Actionscript shares the same epoch as Javascript and UNIX.

The Time
The value (or 'point in time') of a Date object is stored as a single number representing the total milliseconds before or after the epoch. Both the internal value and epoch are measured in UTC. Values of time prior to the epoch are negative numbers.

The value of time can be get and set using the following property and methods:

time:Number valueOf():Number
getTime():Number
time:Number valueOf():Number
getTime():Number
setTime(millisecond:Number):Number

The purpose of the properties and methods of the Date object are to turn this base number into familiar human readable values. In this respect the Date class can be considered an implementation of the Decorator Pattern. It decorates a single internal Number.

Gotcha: Time values of the Date class prior to the 15th October 1582 pre-date the introduction of the modern Gregorian Calendar.

You can use the following function to validate a Gregorian calendar date.

public static function isValidGregorian( d1:Date ):Boolean 
{
  var d2:Date = new Date(Date.UTC( 1582, 9, 15, 0, 0, 0, 0 ))
  return ( d1.time >= d2.time )
}