Time Handling

Units of time are as important to humankind as the bits and bytes are to computers. By them, we live, organize, and operate our daily lives. For that reason, the tango.util.time package collects all the niceties of time and date particulars into a handful of convenient modules, carefully abstracting away all platform details.

The basic unit of time within Tango is represented by an enum within tango.core.Type, called Time. This is a pseudo time quantity capable of spanning a 10,000 year period starting at 1AD, in increments of 100 nano-seconds. Time values are exposed for direct manipulation where appropriate, but can be wrapped within other constructs to simplify usage. Time values are produced principally via Clock and WallClock in the tango.util.time package.

Clock, WallClock, and Date

Clock and WallClock modules represent UTC and local wall time respectively. WallClock performs the equivalent function to Clock, but adjusts for local time zone and daylight savings (DST).

The intent of a Clock is threefold:

• Abstract away OS-level time functions.

• Expose a simple, flexible, consistent expression of time in both UTC and local representations.

• Initialize user accessible time fields with native time information, so that each time component is easy to access independently.

The current value of a clock is retrieved via the now method, which returns a pseudo Time value. This value may be deconstructed by manipulating it directly with Time constants, can be assigned to a DateTime struct for further manipulation, or can be split into fields representing time components.

import tango.util.time.Clock;

void main()
{
         Time time = Clock.now;
}

Much of using the clocks revolves around accessing time "fields" to get or set the time properties with which we need to work. To initialize our time fields we use either Clock.toDate or WallClock.toDate to populate a Date structure with either UTC or local time:

import tango.util.time.Clock;

void main()
{
         auto fields = Clock.toDate;
}

Here we set up the date fields with the current UTC time. We could have made a similar call to WallClock.toDate instead, in which case all field values would have been prepared with local time instead. Sometimes it becomes necessary to convert our current field time values back to an atomic form (a single 64-bit value). fromDate is a method for that purpose. It returns a Time value that contains the 64-bit representation of the current field contents.

Now that the field variables are initialized with the time values, we can go ahead and make good use of them.

import tango.io.Stdout;
import tango.util.time.WallClock;

void main()
{
	auto fields = WallClock.toDate;

	Stdout.formatln ("{} {} {}, {} {:D2}:{:D2}:{:D2}",
                     fields.dow,
                     fields.month,
                     fields.day,
                     fields.year,
                     fields.hour,
                     fields.min,
                     fields.sec );
}

These fields provide us with convenient access to all the parts of the current time. dow returns a string describing the current day of week. month returns a string referring to the month name. day, year, hour, min, and sec supply the integer values of their parts. It is possible to get the current millisecond value of the time with a reference to the ms field.

Recall that when we use that method we are initializing the fields to the the system time rendered at the moment of the call. What if we want to set the Date fields to some arbitrary time and date? Clock and WallClock provide the necessary function via setDate and setTime.

import tango.util.time.Date;

void main()
{
    Date fields;

    fields.setTime( 10, 52, 33, 0  );
    fields.setDate( 2006, 11, 18 );
}

In this case, setTime initializes the time fields for 10:52 AM. It is 33 seconds and 0 milliseconds into the next minute. The date fields are set to November 18, 2006. All these fields now may be printed out as in the previous example. The setDate method also allows you to set the day of week as a fourth parameter. By default it is set to 0 which represents Sunday. Any value between 0 and 6 is acceptable.

Last of all, WallClock allows us to acquire timezone information using the zone method. A call to this method retrieves the local timezone relative to Greenwich Mean Time, where negative values represent west of GMT.

DateTime

DateTime wraps a Time value and provides methods to perform date and time arithmetic based upon the Gregorian calendar. There's an extensive set of methods to extract various date and time components. The DateTime struct is read-only, such that each mutating method returns a new instance.

StopWatch

Need to time a section of code, a 'net request, or some other reasonably short duration? The StopWatch module is your friend, exposing a simple start/stop api. Very high precision on Win32.

Calendars

A variety of calendars providing a foundation for date arithmetic. These are used primarily by the Locale package for purposes of date/time formatting and parsing.

Daylight Savings

All timezone and daylight savings calculations are isolated within WallClock, and conversion between UTC and wall-time is performed in accordance with appropriate OS facilities. There are some potential issues with this dependence, specifically, Win32 systems behave differently to Posix when calculating daylight-savings time. Win32 calculates with respect to the time of the api call, whereas a Posix system calculates DST based upon a provided point in time. We hope to change this at some future point such that Win32 will behave in a similar manner to Posix. This obviously will not affect requests to WallClock.now, since the point in time is actually the current time.