On Tuesday, 2 December 2014 at 19:21:35 UTC, Steven Schveighoffer wrote:
> On 12/2/14 2:14 PM, Steven Schveighoffer wrote:
>
>> Not an oversight.
>>
>> Date.add and Date.roll are for adding units that are variable.
>>
>> For example, how many days are in a month? Answer: depends on the month.
>> How many days in a year? Answer: depends on the year.
>>
>> But days are NOT variable, there are exactly 24 hours in a day. So to
>> add a day, you just add a day with +=.
>
> Aaaand to expand on this, since roll *does* support days, it's because the number being added isn't the important unit, it's the unit above. Hence rolling days means you will stay in the same month.
>
> I'm not exactly sure of the reason behind roll, but I'm sure Jonathan has one :)
>
> -Steve

Oh well, this explanation make so much sense !

Unfortunately, I was not able to find it on the documentation :/

Thank you.

On Tuesday, December 02, 2014 14:14:58 Steven Schveighoffer via Digitalmars-d-learn wrote:
> On 12/2/14 2:00 PM, H. S. Teoh via Digitalmars-d-learn wrote:
> > On Tue, Dec 02, 2014 at 06:49:54PM +0000, via Digitalmars-d-learn wrote:
> >>> But still, why this method http://dlang.org/phobos/std_datetime.html#.Date.add only supports "month" or "years" while this one http://dlang.org/phobos/std_datetime.html#.Date.roll does ?
> >>
> >> But still, why this method http://dlang.org/phobos/std_datetime.html#.Date.add only supports "month" or "years" while this one http://dlang.org/phobos/std_datetime.html#.Date.roll does support days ?*
> >
> > Hmm. Looks like an oversight. File a bug?
>
> Not an oversight.
>
> Date.add and Date.roll are for adding units that are variable.
>
> For example, how many days are in a month? Answer: depends on the month. How many days in a year? Answer: depends on the year.
>
> But days are NOT variable, there are exactly 24 hours in a day. So to add a day, you just add a day with +=.

Exactly. add wouldn't even exist if it weren't for the fact that Duration doesn't work with units greater than weeks because of they depend on what date you're talking about.

- Jonathan M Davis

On Tuesday, December 02, 2014 14:21:35 Steven Schveighoffer via Digitalmars-d-learn wrote:
> On 12/2/14 2:14 PM, Steven Schveighoffer wrote:
>
> > Not an oversight.
> >
> > Date.add and Date.roll are for adding units that are variable.
> >
> > For example, how many days are in a month? Answer: depends on the month. How many days in a year? Answer: depends on the year.
> >
> > But days are NOT variable, there are exactly 24 hours in a day. So to add a day, you just add a day with +=.
>
> Aaaand to expand on this, since roll *does* support days, it's because the number being added isn't the important unit, it's the unit above. Hence rolling days means you will stay in the same month.
>
> I'm not exactly sure of the reason behind roll, but I'm sure Jonathan has one :)

A prime example of where to use it would be if you have a GUI with spinners for the values, and you didn't want incrementing the day to increment the month. It would be kind of annoying to implement that without roll. And since you need to specify the units for rolling (and the addition operator was already used for normal adding), adding a Duration to the time point in order to roll didn't make sense, and a separate function was needed for it even for the smaller units. I don't remember if roll originated with Boost, or if I came up with it though (since portions of std.datetime's API are based on Boost - e.g. julianDay is only there because Boost had it, and astronomers use it such that it seemed useful enough to have; I wouldn't have come up with it on my own though).

- Jonathan M Davis