Date and DateTime are often named LocalDate and LocalDateTime

Question

Date and DateTime are often named LocalDate and LocalDateTime

witoldsz opened this issue 7 years ago · comments

Hi,
I think it could be confusing for some users that Date and DateTime are not the equivalent of things represented by Date elsewhere, like in JavaScript. Even the elm-lang/core has a Date which represents a timestamp and Date and DateTime from this lib represent something else.

My proposition would be to rename Date to LocalDate and DateTime to LocalDateTime. Also, we could introduce Timestamp and converters from Timestamp to ZonedDateTime (and vice-versa) and to LocalDate and LocalDateTime (assuming the user would provide a time-zone).

What is your opinion?

Scott Smith · Answer 1 · Wed Mar 01 2017 13:47:41 GMT+0800 (China Standard Time)

@witoldsz I haven't had enough time to really cogitate on this, but there is one principle that really jumps out to me:

Thou shalt not change the API of a foundation library (i.e. one in elm-community) without a compelling reason to do so.

So, I thought: "Can we augment the API w/o changing the basic functionality? Answer: unfortunately no because you are asking to change the API of the existing Date and DateTime modules.

So the question becomes: is there a standard of naming standards for time libraries and is it compelling enough to adhere to it to sacrifice not changing the API. I come from Ruby, and whereas the function names are different, the Ruby equivalent class names are fairly close in functionality.

Hence, there isn't as tight an API naming convention for time as we'd like, and that lessens the justification of changing the API.

So I sympathize w/ what you'd like to do. But as maintainer I've tried to do similarly (see all the closed issues I've generated for this project 😸 )
and have been pushed back by users who understandably don't want the API to change.

I'm open to discussion on this, and you know what my bias is. Thanks for the idea; let's see what the community thinks.

Witold Szczerba · Answer 2 · Wed Mar 01 2017 18:12:03 GMT+0800 (China Standard Time)

Thou shalt not change the API of a foundation library (i.e. one in elm-community) without a compelling reason to do so.

Agree, but the possible confusion is a valid reason for consideration, I guess.
Other option would be to explain at the very beginning of documentation that Date and DateTime are not time-stamp related, they represent local date and local time. Which of course begs the question: if Date is local date and DateTime is local time, why they are not LocalDate and LocalDateTime.

You are right that it's not about what I or you think, the community could have their say.

Eric Gjertsen · Answer 3 · Wed Mar 01 2017 22:48:58 GMT+0800 (China Standard Time)

I think about Date and DateTime as abstracted from any timezone - sure you might use them for a local date or date-time where the time zone is implicit (i.e. "whatever the browser's time zone is"), but they also can be used to represent a date or date-time in any timezone (i.e. "the calendar date 1 March 2017, wherever you are", "6pm on 8 March 2017, wherever you are").

So to me calling them LocalDate and LocalDateTime is a little confusing. Also a date representation is by its nature timezone-less -- there isn't a ZonedDate. So LocalDate seems redundant. As for date-time, what about NaiveDateTime instead of LocalDateTime ?

DateTime/ZonedDateTime vs NaiveDateTime / DateTime , I don't really have a preference.

we could introduce Timestamp and converters from Timestamp to ZonedDateTime (and vice-versa) and to LocalDate and LocalDateTime (assuming the user would provide a time-zone).

Doesn't core Time == Timestamp ?
DateTime already has converters to/from timestamp (implicitly UTC I think -- another reason to avoid calling it LocalDateTime).
ZonedDateTime also has converters to/from timestamp.
Timestamp to/from Date seems problematic. You can force it now via DateTime.fromTimestamp >> DateTime.toTuple and I kind of think it should be hard to do, because you really shouldn't do it without specifying a time zone.

Witold Szczerba · Answer 4 · Wed Mar 01 2017 23:38:58 GMT+0800 (China Standard Time)

Thanks for your comments!

a date representation is by its nature timezone-less -- there isn't a ZonedDate

Good point, the problem is every language I know use Date to represent a timestamp with zone offset or zone id. The Date used in this module is different.

I think about Date and DateTime as abstracted from any timezone. […] (they) can be used to represent a date or date-time in any timezone (i.e. "the calendar date 1 March 2017, wherever you are", "6pm on 8 March 2017, wherever you are")

I have never though about it, you are right. "Local" does not fit here. I was inspired by Java 8 new Date API.

Doesn't core Time == Timestamp

True, that would be redundant to create yet another timestamp.

DateTime already has converters to/from timestamp (implicitly UTC I think -- another reason to avoid calling it LocalDateTime).

Such a function should always ask for a zone id or offset. Implicit UTC might be confusing, it is still 1000 times better that what most languages do, i.e. using system time zone. We happy Elm-ers do not suffer from such a nightmare, as functions are pure :)

Timestamp to/from Date seems problematic. You can force it now via DateTime.fromTimestamp >> DateTime.toTuple and I kind of think it should be hard to do, because you really shouldn't do it without specifying a time zone.

100% agreed.

DateTime/ZonedDateTime vs NaiveDateTime / DateTime , I don't really have a preference.

The "Naive" does not seem to help me understand the concept. Maybe the names, as they are now, are good enough? :)

Eric Gjertsen · Answer 5 · Thu Mar 02 2017 01:25:59 GMT+0800 (China Standard Time)

The "Naive" does not seem to help me understand the concept.

Yeah, I agree. I think this is how Python people talk about it, don't know how widely it's used outside of Python. In any case, it's a strange word particularly if English isn't one's first language.

Johannes Zick · Answer 6 · Tue Mar 07 2017 15:49:06 GMT+0800 (China Standard Time)

I don't think this will help. Java uses LocalDateTime, Python uses NaiveDateTime...

More confusing than the name, to me at least, is the fact that DateTime is not "local" or "naive" but actually in UTC. There is a distinction between "I assume it's UTC" and "I don't know the time zone". So this new naming scheme might actually confuse people even more.

Witold Szczerba · Answer 7 · Tue Mar 07 2017 19:31:30 GMT+0800 (China Standard Time)

DateTime is not "local" or "naive" but actually in UTC.

What makes you think that? It's not in UTC or any other zone/offset. The only unfortunate thing is that DateTime.fromISO8601 and toISO8601 expects/appends Z at the end. That could be corrected.

I use DateTime to represent date selected by user in date picker: they choose year, month, day, hour, etc… On submit I convert that DateTime to ZonedDateTime using correct zone and then ZonedDateTime.toISO8601. The DateTime.toISO8601 should actually omit the zone/offset (now it just appends 'Z'), that could be submitted as another issue.

Johannes Zick · Answer 8 · Tue Mar 07 2017 22:14:51 GMT+0800 (China Standard Time)

When you parse a DateTime with DateTime.fromISO8601 it substracts the offset so that the result is in UTC. Also, there is DateTime.toTimestamp and DateTime.fromTimestamp. Both only makes sense if the DateTime actually represents a fixed point on the timeline, which it only does if it has a time zone. I have not checked ZonedDateTime.fromDateTime, but I suspect it also assumes the DateTime to be in UTC.

One can do this. It is probably fine for many use cases. But it is different from not having a time zone. Compare this behavior with a LocalDateTime from Java for example. For many conversions, for example to an Instant, which is like a UNIX timestamp, you need to explicitly provide a time zone. Otherwise, a LocalDateTime does not represent a single point in time.

Witold Szczerba · Answer 9 · Tue Mar 07 2017 23:25:50 GMT+0800 (China Standard Time)

You are right about the fromISO8601, I did not notice it actually applies the offset, I though it ignores it. Other functions you mentioned implicitly assume UTC.
Other than that, the DateTime can be used as a local time.

I think we can agree on one thing: it's all a bit confusing. The Time.DateTime module is kind of between local time and UTC date time. My suggestion would be to make the parser ignore zone offset (or fail if one is provided), formatter to drop the Z and (maybe) to remove the toTimestamp, so one would have to convert to ZonedDateTime first, providing a time zone explicitly…

Johannes Zick · Answer 10 · Wed Mar 08 2017 04:49:50 GMT+0800 (China Standard Time)

Although I don't like the way DateTime works right now, it is consistent. What you propose would change an important type in a drastic way. That will help noone. If anything, clear up the documentation about the type.

Witold Szczerba · Answer 11 · Wed Mar 08 2017 05:58:26 GMT+0800 (China Standard Time)

I have not checked ZonedDateTime.fromDateTime, but I suspect it also assumes the DateTime to be in UTC.

It does not: fromDateTime : TimeZone -> DateTime -> ZonedDateTime.

Although I don't like the way DateTime works right now, it is consistent.

OK, thanks for comments.

Johannes Zick · Answer 12 · Wed Mar 08 2017 17:12:17 GMT+0800 (China Standard Time)

I have not checked ZonedDateTime.fromDateTime, but I suspect it also assumes the DateTime to be in UTC.

It does not: fromDateTime : TimeZone -> DateTime -> ZonedDateTime.

Actually, it does. I just tried it in my REPL.

>  epoch |> addHours 5 |> fromDateTime (europe_berlin ()) |> hour
6 : Int

It adds the offset from the zone to the previous DateTime. This only makes sense if the previous values are in UTC. So, I stand by what I said. DateTime is confusing, but consistent.

Witold Szczerba · Answer 13 · Wed Mar 08 2017 17:54:26 GMT+0800 (China Standard Time)

oO that IS confusing, to say at least.
It was so obvious to me that I have not even check it:

x = DateTime.dateTime { zero | year = 2016, month = 5, day = 29, hour = 13 }
        |> ZonedDateTime.fromDateTime (europe_warsaw ())
        |> ZonedDateTime.toISO8601

Expected: x is 2016-05-29T13:00 Europe/Warsaw
Actual: x is 2016-05-29T15:00 Europe/Warsaw

I have just found a bug in my application (luckily did not release it yet).

So, I stand by what I said. DateTime is confusing, but consistent

Shouldn't we expect a little bit more that confusing, but consistent for such a library?

Johannes Zick · Answer 14 · Wed Mar 08 2017 19:34:20 GMT+0800 (China Standard Time)

We should. But that ship has sailed. The API of elm-time is not the best. It has no truly time zone-agnostic type, it is not extensible for other calendar systems...

But that is not something you can change later. Not that I'm happy about it, but changing that would be a complete rewrite of not just the internals, but also the API. It would break everything.

Witold Szczerba · Answer 15 · Wed Mar 08 2017 20:47:20 GMT+0800 (China Standard Time)

But that ship has sailed.

Why would you say so? Didn't Evan make breaking changes in Elm itself? Was it worth it?

The don't touch anything attitude is not the only solution here, there can be more pros than cons.

BTW: it would not brake everything. The semver will apply here, so existing code would still work, new API is always optional.

Scott Smith · Answer 16 · Fri Mar 10 2017 05:58:10 GMT+0800 (China Standard Time)

As maintainer, I'm amenable to API additions that don't change existing APIs. Much less amenable to changing existing APIs. Not that it can't be done, but it has to be really important; maintaining multiple major branches is a lot of effort.

If better function naming is proposed, perhaps aliases could be added; would have to measure that advantage against the confusion that might be added. Careful documentation could help.