Add Time.diff, Date.add and DateTime.diff

[josevalim]

Note NaiveDate.add/diff and Date.diff already exists. We should also improve the documentation for using those functions as references and inline common use cases (unix and gregorian epoch).

[fxn]

@josevalim I think Time.diff has the same potential misuses of Time.add. The difference is ill-defined unless all you want is modulo arithmetic.

Date.add could have similar misuses, because sometimes adding 24h (in seconds, say), changes the date, but not always.

It's tempting to define them, but then you have to document they are naive in that sense. But then you are at square one. Which real world use case could serve as documentation example for instance?

[lau]

Time is "naive" just like NaiveDateTime in the sense that it does not have any time zone. Maybe that should be made more clear in the documentation.

[lau]

Date.add could have similar misuses, because sometimes adding 24h (in seconds, say), changes the date, but not always.

Date is simple because there are no seconds, just whole days.

[fxn]

Yes, they are naive and that is known. But adding an API without a use case and with risk of being misused... is risky, can bite back later.

Not saying there are no use cases eh? Only I can't think of one, but can think of others in which people are going to have bugs.

I was thinking about chronographs, lap times and that kind of thing. There adding and substracting make sense, but that would need >24h in the general case.

Dates have whole days, yes, if units were days it would be well-defined, but the units I see defined are seconds and smaller. Is the plan to have date arithmetic only for day units?

[Qqwy]

I see no problem with Date. add, because it should only work with units of day-size and larger, which will make the results predictable.

Time.diff has a problem however, which is what to do when the difference is 'more than twelve hours'. Note the apostrophes, as the difference between, say, 8:00 and 23:00 could be said to be 14, or 9, or even -9. I am not sure which version would be the best. Maybe we can come up with a more descriptive way to call this so the taken approach is clear from the name.

@fxn: For laptimes, a different datastructure alltogether is needed. I think a Duration à la Joda-time would be wonderful, but something to either put in a library rather than the standard library, or to consider only after the current date/time stuff has settled somewhat (because od the ease of adding and difficulty of removing functionality)

[lau]

Yes, they are naive and that is known. But adding an API without a use case and with risk of being misused... is risky, can bite back later.

Yes, I agree that that can be risky.

Thinking of Time as a simple, but very accurate, 24 hour wrist watch without complications (in the watch sense ie. no calendar, no stop watch, no moon phase) can make sense. You can set it forward or backwards by 30 seconds and there is no DST involved in that.

Dates have whole days, yes, if units were days it would be well-defined, but the units I see defined are seconds and smaller. Is the plan to have date arithmetic only for day units?

I assume so. For smaller units it wouldn't make sense. Also in master there is Date.diff which uses an integer for whole days.

[fxn]

The Elixir community could be different here. If everyone is aware that Time is naive (which is very clear), and that in consequence the API works as you would expect in a naive type... then maybe misuses are going to be less likely, and people are going to switch to proper modules if the need arises.

I don't have context there, you guys know better for sure.

Agreed that day units for Date are fine. Also greater if edge cases are documented (eg, what means to add one year to a 29th of February, you know).

[lau]

It's tempting to define them, but then you have to document they are naive in that sense. But then you are at square one. Which real world use case could serve as documentation example for instance?

I think the answer to the use case is closely related to most use cases of the Time type. Which is very much like the TIME type in SQL databases.

If people say when they usually wake up in the morning on weekdays, then Time could be appropriate. It is not on a particular day, it is for multiple days, so having a date in the type does not make sense. If you have two people that respond: one person responds 06:00 and another at 08:00. Now let us say who wakes up first in the morning? We could just say that this is impossible because we don't know the time zone and call it a day. Or maybe we are OK with the results we can compute without having that data. Maybe all of the data is from people living in the same country and time zone. Maybe they are from all over the world, but we just want to compare when people wake up relative to their own time zone.

So who wakes up first (according to their own clock, and how they report it)? For that we could use a diff function. And once we have a diff function with its then a lot of the questions about add can be answered by being consistent with what is decided for diff.

Does it make sense to say that 8:00 is after 6:00? I think so. Does it make sense to say that the difference is two hours or 7200 seconds? Again I think it does.

What if there was a DST changing event between 6:00 and 8:00? Just like with the functions in NaiveDateTime we are not concerned about that.

[fxn]

@lau forgot to mention, yeah the watch example makes sense. Could be a real watch, maybe the watch of a game in which DST does not even exist.

[fxn]

@lau I am in Kiev, in a conf, writing with my phone in a flaky hotel wifi :). We're crossing messages, but the discussion looks productive to me!