how to migrate to std.datetime

[Nick Sabalausky]

"Jonathan M Davis" <jmdavisProg at gmx.com> wrote in message 
news:mailman.80.1304923988.14074.digitalmars-d-learn at puremagic.com...
>
> I could look at writing an article on moving from std.date to 
> std.datetime, I
> suppose. We already have an article contest going, and it would make sense 
> to
> put such an article on the site.
>
> I don't really have anywhere online that I can post anything myself 
> though,
> let alone links to whatever newsgroup posts might be useful for 
> understanding
> std.datetime.
>

You could put it on the D Wiki: http://prowiki.org/wiki4d/wiki.cgi

Or if you just want to post some non-wiki pages, I'd be happy to post them 
on my server for you: www.semitwist.com

> I would have hoped that the documentation in std.datetime would have been
> sufficient, but either it isn't and/or it's just too overwhelming for some
> folks, given some of the things that have been posted. There haven't been 
> a
> lot of questions about it though since it got into Phobos, so either a 
> fair
> number of people are understanding it well enough, or they aren't using 
> it.
>

All the info that's there is good, but I think the problems, at least as I 
see it are:

- Like others said, it could use a migration guide. It's a fantastic module, 
but I think one of the biggest use-cases for it right now is migration from 
std.date and the old deprected funcs in std.file. And since is it so very 
different, a simple migration guide would be very helpful. Without that, I 
had a little bit of touble migrating some stuff, too (although I'm sure part 
of that was just me being lazy and trying to minimize effort to just get it 
done).

- Some of the important "overview" concepts and typical use-cases are spread 
out a bit much. Of course, they should certainly stay where they are for 
reference purposes. But it would be a big help if, for instance, what you 
told Adam about Durations, subtracting/comparing SysTimes, dur!"hours"(8), 
and olderByAtLeast8Hours were summed up in the overview. Another good thing 
to put up there would be this fantastic idiom, which I probably wouldn't 
have even noticed if someone hadn't submitted a bug report to me for Goldie 
that just happened to use it:

Adapted from: http://www.dsource.org/projects/goldie/ticket/18

  StopWatch sw;
  sw.start();
  scope(exit)
      writeln(sw.peek.msecs);

And maybe a quick little example of "benchmark" added to the overview. I 
didn't even realize that existed until I was looking through the whole page.

And of course, like you said, something like what Andrei added to the top of 
the std.algorithm docs would be great, too.

> Part of the problem with better explaining std.datetime though is that 
> it's
> pretty much all in the documentation, so it's not generally clear what I
> should be explaining further without people asking specific questions.
>

Yea, that's definitely understandable.