[phobos] Split std.datetime in two?

[Jonathan M Davis]

On Thursday 10 February 2011 01:49:24 Lars Tandle Kyllingstad wrote:
> On Wed, 2011-02-09 at 21:54 -0800, Jonathan M Davis wrote:
> > Okay. On the whole, I'm fine with std.datetime being one, large module.
> > It works fine from a maintenance standpoint, and while some people have
> > complained about the large number of unit tests getting in the way of
> > finding stuff in the file, I find that having the unit tests right next
> > to the functions like that to really help with maintenance.
> > 
> > I do have one concern however. As there's a fair bit of functionality in
> > there, there's a lot of documentation, and I'm afraid that the
> > documentation may be a bit overwhelming to someone trying to figure out
> > how to use std.datetime. On the whole, everything in there is quite easy
> > to use, but there's a lot of it.
> > 
> > So, what I'm wondering is if it would be worthwhile to split out the
> > interval and range stuff into a separate module. That wouldn't hugely
> > reduce the size of the module, but it _would_ make the documentation
> > more manageable. It also has the nice side effect that the three main
> > date/time concepts would then be in three separate modules. The duration
> > types were already split into core.time, because Sean needed a duration
> > type for some stuff in druntime. The time points would stay in
> > std.datetime. And the time intervals would then be in std.timeinterval
> > (or whatever we wanted to call it). The documentation would therefore be
> > more easily digestible. Also, if and when I get around to coming up with
> > more date/time functionality, the main area that I'd likely be putting
> > it would be in the intervals and ranges (in particular, at some point,
> > I'd like to create functionality to handle date recurrence patterns), so
> > the bulk of the new stuff would end up in the smaller of the two
> > time-related modules in Phobos, thereby evening out their size a bit.
> > 
> > Again, I don't really have a problem with std.datetime being as big as it
> > is (though some people do), but I _am_ concerned that the documentation
> > is going to be a bit hard to digest for newcomers. It's not complicated,
> > but there's a lot of it. So, I'm thinking that there would be some value
> > in create std.timeinterval for the date/time interval and range
> > functionality, thereby reducing the size of std.datetime and making it
> > easier for newcomers to digest. It will also make it easier to find the
> > interval and range-related functionality if that's what you're looking
> > for.
> > 
> > So, what are everyone else's thoughts on this? Andrei and Walter favored
> > std.datetime being one giant module, and I don't exactly disagree, but I
> > do think that splitting _some_ of its functionality out would make it
> > more digestible, and I know that there are at least a few folks who
> > think that std.datetime is just plain too large.
> 
> I don't think std.datetime should be split.  Keeping it in one file is
> consistent with the way the other Phobos modules are organised.  Rather,
> the Phobos documentation as a whole (and possibly DDOC itself) should be
> improved.
> 
> If it were to be split, I think it would be better to split it into
> std.calendar (Date, TimeOfDay, DateTime), and std.time (SysTime,
> StopWatch).
> 
> Note that I'm not saying I think Phobos' flat module hierarchy is the
> best one.  On the contrary, now that the library is getting so big, it
> would probably be better to have it one level deeper
> (std.algorithm.search, std.algorithm.sort, std.time.calendar,
> std.time.systime, etc.), but I guess it's too late for that.

Splitting along the major concepts - time points, time intervals, and durations 
- makes a lot of sense to me. The time point code doesn't need to care about the 
internals of the durations that it uses, and the time interval code doesn't need 
to care about the internals of the durations or the time points that it uses, 
but some of the D types in each of the three categories need to know about the 
other D types in the same category. So doing something like splitting SysTime 
from Date, TimeOfDay, and DateTime wouldn't work very well. Also, conceptually, 
I don't think that that it makes sense to separate them precisely because 
they're all time points and thus very similar. Not to mention, while Date, 
TimeOfDay, and DateTime are designed with calendar-based uses in mind, SysTime 
has all of the same functions so that you can use _it_ for a calendar solution 
just fine. It's just less efficient for that due to its internal representation, 
and you do have a time zone with it, which may or may not be what you want for 
calendar-based stuff. But from an API perspective, DateTime and SysTime are very 
similar. It's mostly a difference in representation and therefore efficiency. 
Regardless, the various time types are all similar enough that splitting them up 
doesn't really make sense IMO.

Time intervals on the other hand just _use_ time points and durations, so they 
_can_ be put in a separate module quite cleanly. It's kind of like the difference 
between std.range and std.algorithm. For the most part, std.range deals with 
defining range stuff whereas std.algorithm uses the range stuff. They're related 
but separate.

As for improving the documentation, I've been working on that, but you can't 
separate it out without separating the code into separate modules. It makes a 
lot of sense to me to have the time intervals separate. That reduces how much 
documentation is on the one page for std.datetime, and it makes it _much_ easier 
to sort out and find the interval and range types and functions. But without 
dividing the module, you can't divide the documentation - not with how ddoc 
currently works.

Like the Boost date/time stuff, our date/time stuff is built around the concepts 
of time points, time durations, and time intervals. And I think that it makes 
good sense to split the module along those lines. I already had to split out the 
duration stuff into core.time so that druntime could use it. If I split out the 
time interval stuff into a separate module, then each of the three base concepts 
is separated out into its own module, and it makes looking up their related 
types and functions much easier IMHO.

So, I'm not looking to just break up std.datetime willy-nilly or just to reduce 
it's size. I think that it makes a lot of sense to split it based on its core 
concepts. _That_ makes it much easier to find what you're looking for in it. It 
would _also_ reduce the size of std.datetime's documentation, but the interval 
and range stuff is a small enough percentage of the module, that it's not like 
the reduction would be much from the standpoint of the amount of text. It 
_would_ however reduce the number of concepts that the std.datetime 
documentation would have to worry about.

- Jonathan M Davis