4.2 Time Zones ¶

Tablicious has support for representing dates in time zones and for converting between time zones.

A datetime may be "zoned" or "zoneless". A zoneless datetime does not have a time zone associated with it. This is represented by an empty TimeZone property on the datetime object. A zoneless datetime represents the local time in some unknown time zone, and assumes a continuous time scale (no DST shifts).

A zoned datetime is associated with a time zone. It is represented by having the time zone’s IANA zone identifier (e.g. 'UTC' or 'America/New_York') in its TimeZone property. A zoned datetime represents the local time in that time zone.

By default, the datetime constructor creates unzoned datetimes. To make a zoned datetime, either pass the 'TimeZone' option to the constructor, or set the TimeZone property after object creation. Setting the TimeZone property on a zoneless datetime declares that it’s a local time in that time zone. Setting the TimeZone property on a zoned datetime turns it back into a zoneless datetime without changing the local time it represents.

You can tell a zoned from a zoneless time zone in the object display because the time zone is included for zoned datetimes.

% Create an unzoned datetime
d = datetime('2011-03-04 06:00:00')
    ⇒  04-Mar-2011 06:00:00

% Create a zoned datetime
d_ny = datetime('2011-03-04 06:00:00', 'TimeZone', 'America/New_York')
    ⇒  04-Mar-2011 06:00:00 America/New_York
% This is equivalent
d_ny = datetime('2011-03-04 06:00:00');
d_ny.TimeZone = 'America/New_York'
    ⇒  04-Mar-2011 06:00:00 America/New_York

% Convert it to Chicago time
d_chi.TimeZone = 'America/Chicago'
    ⇒  04-Mar-2011 05:00:00 America/Chicago

When you combine two zoned datetimes via concatenation, assignment, or arithmetic, if their time zones differ, they are converted to the time zone of the left-hand input.

d_ny = datetime('2011-03-04 06:00:00', 'TimeZone', 'America/New_York')
d_la = datetime('2011-03-04 06:00:00', 'TimeZone', 'America/Los_Angeles')
d_la - d_ny
    ⇒ 03:00:00

You cannot combine a zoned and an unzoned datetime. This results in an error being raised.

Warning: Normalization of "nonexistent" times (like between 02:00 and 03:00 on a "spring forward" DST change day) is not implemented yet. The results of converting a zoneless local time into a time zone where that local time did not exist are currently undefined.

• Defined Time Zones