Time Zones (Tablicious v0.4.7)
Description: User manual for Tablicious for Octave.

### 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 `datetime`s. 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 `datetime`s.

    % 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 `datetime`s 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.