Rant: Date and Time fall short of simplicity in D

[Steven Schveighoffer]

On Fri, 29 Mar 2013 01:42:41 -0400, Andrej Mitrovic  
<andrej.mitrovich at gmail.com> wrote:

> import core.thread;
> import core.time;
> import std.datetime;
> import std.stdio;
>
> void main()
> {
>     StopWatch sw;
>     sw.start();
>     Thread.sleep(dur!"seconds"(1));
>     Thread.sleep(dur!"msecs"(200));
>     Thread.sleep(dur!"usecs"(800));

Thread.sleep(1.seconds + 200.msecs + 800.usecs);

>     sw.stop();
>
>     TickDuration time = sw.peek();
>
>     long secs = time.seconds;
>     long msecs = time.msecs - (1000 * secs);
>     long usecs = time.usecs - (1000 * msecs) - (1000 * 1000 * secs);
>
>     writefln("secs: %s, msecs: %s, usecs: %s", secs, msecs, usecs);
> }

This one is VERY annoying, Duration has some of the necessary properties.   
The sub-second values you must obtain with FracSecs, and once you get  
there, it does NOT give you properties which remove the higher units.

So I can't really do this any better than you did.

core.time needs to be fixed.  Duration is really what you should use when  
doing duration math.  I don't know why TickDuration still exists actually.

> Why was this inconsistency introduced?

Well, Duration was the basic type for general date time stuff that  
Jonathan came up with.  TickDuration was created for StopWatch, which was  
developed by Kato Shoichi.

IMO, they should be combined.

> Another example, I once had to convert a long type which represented
> Unix time into DateTime. Here's the code to do it:
>
> return cast(DateTime)SysTime(unixTimeToStdTime(cast(int)d.when.time));

I have three comments here:

1. unixTimeToStdTime should take ulong.
2. There should be a shortcut for this.

Note on Windows, given a SYSTEMTIME we can do:

return cast(DateTime)SYSTEMTIMEToSysTime(t);

We need an equivalent unixTimeToSysTime, and in fact, I think we can get  
rid of unixTimeToStdTime, what is the point of that?

3. I HATE "safe" cast conversions.  If you want to make a conversion, use  
a method/property.  I don't even know why D allows overloading casting.   
Casts are way too blunt for this.

The code should be:

return unixTimeToSysTime(d.when.time).asDateTime;

> Anyway, maybe time and datetime are power-houses in Druntime and
> Phobos, but they trade their features for simplicity.
>
> Perhaps the real problem is the documentation, or the actual layout of
> the API itself. The API seems to contain a ton of functionality, and
> maybe the more specialized functions should be moved into separate
> modules (and make datetime be part of its own package).
>
> The docs for std.datetime for example are huge.

This is an issue with the doc generator.  Date and time are surprisingly  
complex features, you need a lot of power to do them properly.

The doc generator should split up the docs into docs for each type.

For a better experience, see here:

http://vibed.org/temp/d-programming-language.org/phobos/std/datetime.html

-Steve