[Issue 15339] New: std.datetime: document DST handling

[via Digitalmars-d-bugs]

https://issues.dlang.org/show_bug.cgi?id=15339

          Issue ID: 15339
           Summary: std.datetime: document DST handling
           Product: D
           Version: D2
          Hardware: x86_64
                OS: Linux
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: phobos
          Assignee: dhasenan at gmail.com
          Reporter: dhasenan at gmail.com

DateTime (specifically TimeOfDay) contains validation to ensure that its hour
is never above 23. This means that it is intended to represent time shown on a
typical clock (and not, for instance, the nth hour of the day). This should be
documented.

When daylight saving time starts and ends, there is a day with fewer or more
than 24 hours. In the US, the hour of 2am is repeated or omitted as
appropriate. This results in ambiguous dates. This should be documented.

Since `SysTime(DateTime(2015, 11, 1, 1, 0, 0),
TimeZone.getTimeZone("America/Los Angeles")).add!"hours"(1)` returns
2015-11-01T01:00:00, it should further be documented (after verification) that
the date chosen is the earlier of applicable dates.

It should further be clarified that `SysTime(DateTime(2015, 11, 1, 1, 0, 0),
TimeZone.getTimeZone("America/Los Angeles")).add!"hours"(1).add!"hours"(1)`
does in fact yield 2015-11-01T02:00:00, as you would expect.

Finally, we should add unittests to ensure we don't break this behavior.

--